HappyHex

A hexagonal Block Blast (e.g. Hex FRVR) implementation using java, build with custom graphics and advanced data processing.

This is a very happy and fun game, with some Easter Eggs, for everyone :)

Author: William Wu
Languages: Java (Graphics), Python (used for autoplay and ML)
Last edited: 21/09/2025
Latest release: 2.0.0

Important

This project need the following dependencies to run:

1. javax.json package (Source).
2. Implementation of javax.json, such as JSR-000374 Java API (Download).
3. (For tests) org.junit.jupiter.api package (Source).
   Or: delete the tests package in source code
   See Tests for more

Note

The project may contain bugs:

• Report bugs by create an issue.
• The most recent release have two detected bug:
  • Autoplay GUI not updated when python processor unexpectedly close #79. Fix not planned.

---

About

This is just a cute project of mine. From early on after learning java in high school and helped the teacher taught its graphics library javax.swing I felt compelled to actually program a functional game. Combined with my earlier ideas of designing a hexagonal grid coordinate system, the rough picture of what would be future HappyHex formed in my mind. In my spare time, I gradually developed this project through following my timeline and added increasingly attractive features. From version 0.4 to 2.0, it has grown from just a game page with buggy information display that had to be launched through terminal commands and contained no color indication to a comprehensive and enjoyable game that features settings, themes, and animation. Game logging and viewing, and even resume game functionalities are slowly build up in Pull Requests. It has become that one project which I could not stop thinking about. Step by step improvements will be made in different aspects and merged together for revisions after revisions. In the end, I would incorporate intelligent autoplay systems, unlockable achievements, and even fancier graphics.

License

Distributed under the MIT License

License Link

Usage

How to download the game and play, or, if you want, compile it yourself.

• Method 1: Run the .jar file
  1. Find the Latest Release (See the top of this document).
  2. Download the asset from the release.
  3. Find HappyHex_jar Version x.x.x.zip zip file.
  4. Use a tool to decompress the zip file, which will create a folder named HappyHex_jar.
  5. Make sure that the folder contains:
     a. The main jar file, game_HappyHex.jar.
     b. The JSON utilities, javax.json-1.1.4.jar and javax.json-api-1.1.jar.
     c. The data folder.
  6. Double click or use a tool to run game_HappyHex.jar.
• Method 2: Download code from GitHub.com
  1. Find the Latest Release (See the top of this document).
  2. Download the asset from the release.
  3. Download dependencies. You don't need javax.swing if it is already installed.
  4. Set the downloaded dependencies as project dependencies or libraries.
  5. Remove HappyHex_jar Version x.x.x.zip zip file, which contain a compiled jar.
  6. If tests are not needed, remove the tests package.
  7. Compile the program.
  8. Run main method in Main class in the main directory, usually named game_HappyHex.

Usage of the Game Viewer please see its own README. Generally, users may run the JAR File.

Dependencies

• javax.swing
• javax.json
• javax.json api
• org.junit.jupiter.api

Game Play

Launcher Navigation

The launcher is the window that opens after the application is opened. The game is not directly played, but rather can be started with a start button. The settings and color theme can be changed through the launcher, which enhances the game experience for the player. In addition, Easter Eggs can also be activated with the launcher.

The launcher use an adjustable window, and all components contained in the window are dynamically resizable. That said, there is a minimum size limitation of the game window, because otherwise the game cannot show all of its content. The limitation is currently 400 * 400 pixels.

The launcher has the following pages:

Main Page

The main page displays the game name, version, credits, game hints, and provides buttons for navigating to other pages.

• Game Name

  The game name, or title, appears on the topmost of the page. The title contain the characters "⬢HAPPY⬢⬢HEX⬢" with 12 different colors. These 12 colors will be the exact same color as the colors used for piece and block generation.
  The sequencing of the colors is randomized every time the page is refreshed, which can be done by relaunching the application or switch to another page and back.

• Game Version

  The game version is displayed underneath the game title with an italic font. The version should say "Version x.x.x". This version corresponds to all other game versions presented in the game logs, messages, data recordings generated by this specific instance of the game HappyHex.

• Game Hints

  The game hints are hint messages that are displayed in the main page under the game version and game title. These messages either hint at a specific game mechanics, serve as tips for navigating the launcher or obtaining a high score, provide a humorous evironment by providing insights as me the developer, or unveil secrets in the game such as the Easter Eggs.
  They are mostly gray in most themes, but their colors may change.
  The hint message will change everytime the main page is refreshed, which can be done by relaunching the application or switch to another page and back.
  An example message is: "Try hover over blocks", which hints that hovering over blocks in the game field when a piece is selected reveals the potential placements of pieces in the game.

• Buttons

  The game provides clickable buttons for navigating to other pages. All buttons are resizable and are of the same height.

  1. Login Button
     The login button has the word "LOG IN" written on it. It is intended to provide users for redirection to the Login Page.
     When the game launcher is first launched, the player will not be automatically logged it. To log in, click on the button.
  2. Settings Button
     The settings button has the word "SETTING" written on it. It is intended to provide users for redirection to the Settings Page.
     Under the default setting, the game is playable, but the settings page offer player more options in game difficulty, board size, and whether to restart an unfinished game if such games exist.
  3. Themes Button
     The settings button has the word "THEMES" written on it. It is intended to provide users for redirection to the Themes Page.
     The default color theme of the game is Normal Theme, but the themes page enables players to switch to other themes instead if they prefer to do so.
  4. Start Button
     The start button has the word "START" written on it. When clicked, it starts a new game based on the settings provided, modifiable via Settings Page. If the player is logged in and an unfinished game exist, and the restart game setting is set to be ON, the unfinished game will continue.
     The game play part is considered to be outside launcher. For detailed game rules, see Game Rules.

• Game Credits

  On the button of the page there will be a section with the game credits to its developers, which is currently just me.
  To the left of the section, the words "A W.W Game" can be seen, with the two Ws shown in a slightly larger font with a different color.
  To the right of the section, a copy right can be seen, attributing the game copyright to William Wu. See License for details.

Login Page

The login page enables the user to log in with their username. While no password is required, a unique username is recommended. User information is logged in logs.json, which stores past game records, including recent and highest scores and turns.

The page contains the following elements:

• Game Title

  This is the exact same element as that in Main Page, with the only difference being the elimination of the space above this title. The element contains the game title, appears on the topmost of the page. The title contain the characters "⬢HAPPY⬢⬢HEX⬢" with 12 different colors, which will be the exact same color as the colors used for piece and block generation. The sequencing of the colors is randomized every time the page is refreshed.

• Username Requirements

  The username requirements displays in monospaced font about the requirements for allowed usernames. The requirements read as follows:

  1. Must be between 3 - 24 characters long, inclusive.  
  2. Only contain 1-9, A-Z, a-z, dash, underline or space.  
  3. Must contain at least one letter.  
  4. Special Symbols such as #%$ are not allowed.  
  5. Cannot start or end with dash, underline or spaces.  
  6. Cannot be one of the keywords used by the game system.  
  

  The game keywords can be found in the Prohibited-Usernames section of this document, but note that Easter Eggs may be connected to some of the keywords that is "prohibited". Generally speaking, however, keywords are considered to be invalid.

• Username Entering Field

  This is an interactive field for the player to enter their username.

  The length and composition of the username must follow the username rules described above of the username to be considered valid. This field provides keyboard interaction, as the players may use their keyboard to enter their desired usernames.

  When no player is logged in, this field will display a prompt "ENTER THE USERNAME HERE!". Deleting this prompt to enter the username. On the other hand, when a player is logged in, this field will display the username of the logged in player in another color, as defined by the current theme. To log out, the player may enter "Out", "Logout", or "Log out".

  Whenever an action, such as clicking the Confirm Button, is performed, the field will display a short prompt for a limited period of time, then switch back to normal. If the player attempts to enter a name with the incorrect format, the prompt will usually be red, stating "INCORRECT NAMING FORMAT!". If the player attempts to one of the keywords, the prompt will usually be red, stating "GAME KEYWORD PROHIBITED!". If the login was successful, the field will display the short prompt, usually green, "SUCCESSFUL PLAYER LOGIN!" and then display the logged in player's username.

• Confirm Button

  This is a button similar to all the other redirection buttons, but appears usually in green and contains the text "ENTER".

  When clicked, the launcher will check the current text inside the Username Entering Field. If the name is valid and matches the current logged-in user, nothing will happen. If the name is valid and representing a new login, the field will display "SUCCESSFUL PLAYER LOGIN!". If the name is one of the keywords, the field will display a red prompt stating "GAME KEYWORD PROHIBITED!". If the name does not meet the rules and is not valid, the field will display a red prompt stating "INCORRECT NAMING FORMAT!".

  Player must click on this button to confirm their newly entered username when attempting login. Otherwise, nothing will happen.

• Quit Button

  This is a button similar to all the other redirection buttons, but appears usually in red and contains the text "QUIT".
  When clicked, this button redirects to the Main Page unconditionally. Your inputs in the Username Entering Field may not be saved.

• Game Credits

  A section detailing the credit and copyright information of the HappyHex game, identical to that in Main Page.

Trophies Page

This page displays the trophies and achievements the player has unlocked. Trophies are purely for fun and do not affect game play.

The page contains the following elements:

• Game Title

  This is the exact same element as that in Main Page, with the only difference being the elimination of the space above this title. The element contains the game title, appears on the topmost of the page. The title contain the characters "⬢HAPPY⬢⬢HEX⬢" with 12 different colors, which will be the exact same color as the colors used for piece and block generation. The sequencing of the colors is randomized every time the page is refreshed.

• Achievements Title Under the Game Title, there is a text "Achievements", which indicates that this is the trophies page used to display achievements. The font of this title will be the exact same font as that used in the Settings Page.

• Close Button

  Unlike other close buttons with a "QUIT" text, this is a small button with an "X" text on it, located in the top right corner of the page. When clicked, this button redirects to the Main Page unconditionally. The button is automatically resized to the same size as the height of the achievements title and is on the exact same horizontal line as the title.

• Trophies Display Area

  This is an area that displays all the trophies and achievements the player has unlocked. Each trophy is represented by an icon, its name, and a description of how to unlock it. If the player has not unlocked any trophies, this area will be blank. Underneath all the achievement items there is a small area with a text and four buttons, used to navigate through the pages of trophies. The text displays the current page number, in the format "Page X", and the buttons function as follows:

  • <<: Go to the first page of trophies.
  • <: Go to the previous page of trophies.
  • >: Go to the next page of trophies.
  • >>: Go to the last page of trophies. Displayed content and the page number will change accordingly when the buttons are clicked.

  It is important to mention that the number of items in a page is dynamically determined by the size of the game window. When the window is resized, the number of items that can be displayed in a single page will change accordingly. The minimum number of items that will be displayed on a page is 1, and the minimum number of item slots on a page is 3. If the page number is big and resizing changes the number of items displayed dramatically, the indicated page number may change, but the content is preserved as much as possible.

• Game Credits

  A section detailing the credit and copyright information of the HappyHex game, identical to that in Main Page.

Settings Page

The settings page allows the player to control over key game parameters, enhancing the game functionality while make HappyHex more fun.

The page contains the following elements:

• Game Title

  This is the exact same element as that in Main Page, with the only difference being the elimination of the space above this title. The element contains the game title, appears on the topmost of the page. The title contain the characters "⬢HAPPY⬢⬢HEX⬢" with 12 different colors, which will be the exact same color as the colors used for piece and block generation. The sequencing of the colors is randomized every time the page is refreshed.

• Settings Title

  Under the Game Title, there is a text "Settings", which indicates that this is the settings page.

• Easy Mode Settings

  Turned OFF by default. Turning the switch ON enables Easy Mode, while turning it OFF disables Easy Mode.

  This switch controls whether to enables "Easy Mode," which modifies piece generation to make the game significantly easier.

  Easy mode is compatible with all special game modes in the Easter Eggs.

• Machine Learning Enable

  Turned ON by default. Turning the switch ON enables Machine Learning, while turning it OFF disables Machine Learning Models.

  This is useful if you dislike the performance of the current machine learning models, and want to switch to the traditional heuristic algorithm for autoplay. Disabling machine learning models will make the autoplay less "intelligent", but may result in faster autoplay speed and more stable performance.

  If your machine suffers significant performance issues when machine learning models are used, consider turning this switch OFF.

Note

Since first Official Release (v1.0.0), unspecified game mode creation is no longer supported.

Players can choose between Small, Medium, and Large game board sizes for their next game. The default size is Small, and selecting one option will automatically deselect the others.

• The Small size will result in a game board radius of 5 and piece queue size of 3.
• The Medium size will result in a game board radius of 8 and piece queue size of 5.
• The Large size will result in a game board radius of 11 and piece queue size of 7.

It is recommended to use the small size for beginners and players who do not want to spend a lot of time on a single game session. Large size often prolong game session to over an hour, if played well at normal pace.

• Quit Button

  This is a button similar to all the other redirection buttons, but appears usually in red and contains the text "QUIT".
  When clicked, this button redirects to the Main Page unconditionally. All changes in settings will be saved.

• Game Credits

  A section detailing the credit and copyright information of the HappyHex game, identical to that in Main Page.

Themes Page

• Game Title

  This is the exact same element as that in Main Page, with the only difference being the elimination of the space above this title. The element contains the game title, appears on the topmost of the page. The title contain the characters "⬢HAPPY⬢⬢HEX⬢" with 12 different colors, which will be the exact same color as the colors used for piece and block generation. The sequencing of the colors is randomized every time the page is refreshed.

• Theme Setting

  For special themes, see in the Easter Eggs section. For detailed description on the themes, see the dedicated theme section.

  Players can choose between Normal, Dark, and White game themes for displaying. These themes alter the color of all game graphics and are effective immediately. When a switch is flicked, the user can notice the change in the coloring of the theme page. All changes in the theme in theme settings will be carried to all other pages, until the theme settings is modified again. The default theme is Normal.

  The theme settings has nothing to do with the game settings and will not affect game logic at all.

  The changes of theme maybe override by special dates dictated by Special Themes. When a special theme is active, the buttons will still work but the theme will remain the same.

  There's no superior theme among the three themes. Personally I prefer the Dark Theme, but the most classic one is the default theme, namely the Normal Theme.

• Quit Button

  This is a button similar to all the other redirection buttons, but appears usually in red and contains the text "QUIT".
  When clicked, this button redirects to the Main Page unconditionally. All changes in theme settings will be saved.

• Game Credits

  A section detailing the credit and copyright information of the HappyHex game, identical to that in Main Page.

Resume Page

This page helps the player to resume a previously stated but unfinished game stored in the data directory. For a game to show up on this page, the following requirements all be meet:

1. A valid .hpyhex game log file, in colored format, must exist in the data directory. Validity of game file means that they are not corrupted and can be read by the HappyHex program.
2. The game is unfinished. This means in the binary .hpyhex files need to have the key complete set to false.
3. The username and user ID recorded in the binary .hpyhex game log files matched the currently logged-in user. In addition, the user logged in, as when user is not logged in, games will not be able to resumed or recorded.
4. The game queue and board sizes matches the sizes currently selected in the settings. If the settings do not match, no game may show up.

Whenever a game shows up, the panel will have a section with round corners displaying essential information about the game. This information does not include username or id because whenever resuming game is possible, the user must be logged in. This information, however, includes the game's file name, which is a randomly generated 16 hexadecimal character hash (64 bit). The file name may include its location, namely data/, referring to the data directory. In addition, the field also displays the game's current score and turn, indicating the game's progress. Players can judge based on the score and turn to decide which game to resume and play.

Each section has a green button, show as green text "RESUME". Click on the button to the specific game. If the game cannot be resumed due to undetected data corruption in the game log, or when game log reading encountered an error, the application will automatically start a new game for the player. If the player does not want to play the new game, they may quit out of the game.

If there are no sections indicating existence of unfinished games, the field will be blank. If there are more sections than what can be displayed in the field at the same time, a scroll bar will show up, enable scrolling of the field. Move the scroll bar vertically to view more game entries and click on their resume buttons to resume those games.

On the bottom of the page, there are three buttons:

• Quit Button

  This is a button similar to all the other redirection buttons, appears in red and contains the text "QUIT".
  When clicked, this button redirects to the Main Page unconditionally.

• Start Button

  This button functions exactly like the start button of the Main Pagem appears in black and contains the text "RESUME".
  This will start a new game or resume an unfinished game based on the game setting.

• New Button

  This is a button to start an entirely new game, appears in green and contains the text "START". This button will not resume any game.

Start Game

This will direct the page out of the launcher and initialize the game components in a new game page.

Usually, the game page have separate colors and fonts as the launcher, and is made up from two panels instead of a single panel. This provides significant efficiency to the game execution and make the game play process much smoother.

The game page includes components such as:

• Hexagonal Game Board: The core game engine using hexagonal coordinates, where players can place blocks.
• Piece Queue: A set of randomly generated pieces with predefined shapes and colors. The difficulty level affects piece generation.
• Game Information: The current game turn and game score are displayed on the two top corners.
• Player Information: The current player name is displayed in the down right corner.
• Conventional Quit Button: Clicking on the quit button will enable you to quit the game. Current progress will be logged into log.json if a game has started.
• "Dynamic Island": This GUI component mainly controls autoplay. It can also be used to quit the game. See Autoplay for more.

Theme, Color and Font

This describes the default themes of the game, including coloring and fonts of texts. For special themes, see the Special Themes section.

Fonts

The various sections of the game GUI use the following Fonts, they are stored as static variables in GUI.GameEssentials and Launcher.LaunchEssentials. They may be modified by Easter eggs.

• Fonts for author information and copyright on the button of launcher pages are always "Helvetica".
• Font for the mark "W.W" is always "Georgia".
• Font for the title, styled "Happy Hex", is "Courier".
• Font for the version string beneath the title is "Comic Sans MS".
• Font for the buttons to switch pages in the launcher or to start the game is "Times New Roman".
• Fonts for hints, displayed texts, username rules, etc. that require a mono font is "Courier".
• Fonts for the sliding ON-OFF switch in settings and theme pages are "Helvetica".
• Fonts for quit button, user information, game turns and score inside the game page is "Courier".

Normal Color Theme

This theme is the default game theme, or can be activated in the launcher page themes, when the Normal switch is set to ON.

• Color for the background of any launcher page is rgb(241, 243, 213).
• Color for the background of the strip behind the title, styled "Happy Hex", is rgb(219, 223, 151).
• Colors for author information and copyright on the button of launcher pages are rgb(0, 73, 54).
• Colors for the mark "W.W" is rgb(0, 0, 0).
• Colors for game version string beneath the title is rgb(0, 0, 0).
• Colors for game hints string beneath the title is rgb(128, 128, 128).
• Color for the background of the log-in field in the log-in page in launcher is rgb(247, 248, 238).
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a logged in player name, is rgb(136, 136, 0).
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a prompt, is rgb(0, 136, 0).
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a warning or an error, is rgb(136, 0, 0).
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a special message, is rgb(0, 136, 136).
• Colors for the background of the buttons to switch pages in the launcher are rgb(0, 0, 0).
• Colors for the background of the buttons to quit to main page from another launcher page in the launcher are rgb(255, 0, 0).
• Color for the background of the button to confirm the information player inputted in the login field in the launcher is rgb(0, 223, 39).
• Colors for the foreground of the button to start a new game when an existing game ends are rgb(0, 193, 211).
• Colors for the empty portion of the sliding ON-OFF switch in settings and theme pages are rgb(255, 255, 255).
• Colors for the foreground of the sliding ON-OFF switch in settings and theme pages, when ON, are rgb(0, 255, 0).
• Colors for the foreground of the sliding ON-OFF switch in settings and theme pages, when OFF, are rgb(255, 0, 0).
• Color for the background of the game field in game page is rgb(213, 236, 230).
• Color for the background of the piece queue in game page is rgb(113, 129, 122).
• Color for the background of the game over page is rgb(163, 188, 180).
• Color for texts displaying game username, turns, and score information, in game page, is rgb(5, 34, 24).
• Color for the quit button in game page, is rgb(136, 7, 7).
• Colors for blocks in the game field, when they are not filled, are rgb(0, 0, 0).
• Color for the block selected in the piece selected in the piece queue, is rgb(168, 213, 201).
• The 12 Colors available for blocks, are, rgb(0, 0, 240), rgb(0, 100, 190), rgb(0, 180, 180), rgb(0, 180, 120), rgb(0, 210, 0), rgb(100, 180, 0), rgb(180, 180, 0), rgb(200, 90, 0), rgb(210, 0, 0), rgb(200, 0, 120), rgb(180, 0, 180), and rgb(100, 0, 200).

Dark Theme

This theme can be activated in the launcher page themes, when the Dark switch is set to ON.

• Color for the background of any launcher page is the inverted color of the Normal Theme.
• Color for the background of the strip behind the title, styled "Happy Hex", is the inverted color of the Normal Theme.
• Colors for author information and copyright on the button of launcher pages are rgb(158, 157, 232).
• Colors for the mark "W.W" is rgb(204, 204, 204).
• Colors for game version string beneath the title is rgb(204, 204, 204).
• Colors for game hints string beneath the title is rgb(128, 128, 128).
• Color for the background of the log-in field in the log-in page in launcher is the inverted color of the Normal Theme.
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a logged in player name, is the inverted color of the Normal Theme.
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a prompt, is the inverted color of the Normal Theme.
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a warning or an error, is the inverted color of the Normal Theme.
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a special message, is the inverted color of the Normal Theme.
• Colors for the background of the buttons to switch pages in the launcher are rgb(0, 0, 0).
• Colors for the background of the buttons to quit to main page from another launcher page in the launcher are rgb(255, 0, 0).
• Color for the background of the button to confirm the information player inputted in the login field in the launcher is rgb(0, 223, 39).
• Colors for the foreground of the button to start a new game when an existing game ends are the inverted colors of the Normal Theme.
• Colors for the empty portion of the sliding ON-OFF switch in settings and theme pages are rgb(22, 22, 22).
• Colors for the foreground of the sliding ON-OFF switch in settings and theme pages, when ON, are rgb(0, 255, 0).
• Colors for the foreground of the sliding ON-OFF switch in settings and theme pages, when OFF, are rgb(255, 0, 0).
• Color for the background of the game field in game page is rgb(23, 23, 42).
• Color for the background of the piece queue in game page is rgb(63, 61, 112).
• Color for the background of the game over page is rgb(63, 61, 112).
• Color for texts displaying game username, turns, and score information, in game page, is the inverted color of the Normal Theme.
• Color for the quit button in game page, is rgb(255, 144, 110).
• Colors for blocks in the game field, when they are not filled, are rgb(22, 22, 22).
• Color for the block selected in the piece selected in the piece queue, is rgb(36, 33, 101).
• The 12 Colors available for blocks are the inverted colors of the Normal Theme.

White Theme

This theme can be activated in the launcher page themes, when the White switch is set to ON.

• Color for the background of any launcher page is rgb(255, 255, 255).
• Color for the background of the strip behind the title, styled "Happy Hex", is rgb(255, 255, 255).
• Colors for author information and copyright on the button of launcher pages are rgb(0, 73, 54).
• Colors for the mark "W.W" is rgb(0, 0, 0).
• Colors for game version string beneath the title is rgb(0, 0, 0).
• Colors for game hints string beneath the title is rgb(192, 192, 192).
• Color for the background of the log-in field in the log-in page in launcher is rgb(255, 255, 255).
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a logged in player name, is rgb(136, 136, 0).
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a prompt, is rgb(0, 136, 0).
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a warning or an error, is rgb(136, 0, 0).
• Color for the foreground of the log-in field in the log-in page in launcher, if the text is a special message, is rgb(0, 136, 136).
• Colors for the background of the buttons to switch pages in the launcher are rgb(64, 64, 64).
• Colors for the background of the buttons to quit to main page from another launcher page in the launcher are rgb(64, 64, 64).
• Color for the background of the button to confirm the information player inputted in the login field in the launcher is rgb(64, 64, 64).
• Colors for the foreground of the button to start a new game when an existing game ends are rgb(64, 64, 64).
• Colors for the empty portion of the sliding ON-OFF switch in settings and theme pages are rgb(64, 64, 64).
• Colors for the foreground of the sliding ON-OFF switch in settings and theme pages, when ON, are rgb(0, 0, 0).
• Colors for the foreground of the sliding ON-OFF switch in settings and theme pages, when OFF, are rgb(0, 0, 0).
• Color for the background of the game field in game page is rgb(255, 255, 255).
• Color for the background of the piece queue in game page is rgb(255, 255, 255).
• Color for the background of the game over page is rgb(255, 255, 255).
• Color for texts displaying game username, turns, and score information, in game page, is rgb(64, 64, 64).
• Color for the quit button in game page, is rgb(64, 64, 64).
• Colors for blocks in the game field, when they are not filled, are rgb(0, 0, 0).
• Color for the block selected in the piece selected in the piece queue, is rgb(192, 192, 192).
• The 12 Colors available for blocks, are the same colors as they are in the Normal Theme

Screen Shots

These are screenshots of various portions of the game as of patch 1.1.3. The colors and fonts of the three basic themes have not changed since, but a resume button similar to all other buttons has been added to the main page.

• Normal Color Theme:
  
• Dark Theme:
  
• White Theme:
  

Game Rules

These game rules are automatically enforced by game logic stored in the game code. Players do not need to pay special attentions to them, but it is a good idea to understand why the game behaves the way it does. Easter Eggs can sometimes override game rules.

Game Start

• If the player is logged in, the game will start with the current player information. Otherwise, it will enter guest mode with player being "Guest".
• The game will start with the current difficult setting and size setting, both of which can be adjusted in settings page.
• If the player is directed from the Resume Page, the unfinished game will resume. The color of the board and queue of the unfinished game will be the exact same according to the current theme.
• If no valid unfinished game is detected, a new empty game will start with empty game board and randomized game queue according to piece generation logic.

Piece Generation

• Pieces are generated by an underlying piece generator that is mostly based on random.
• In Normal Mode (Easy Mode is turned OFF in Settings), the generator generates almost equal frequency of all pieces. The generator will never generate the single-block piece but may generate the full 7-block piece.
• In Easy Mode (Easy Mode is turned ON in Settings), the generator favors small and more placeable pieces. The generator will never generate full 7-block piece but may generate the single block piece.
• Pieces will be generated according to logic in the queue whenever another piece is dequeued by placement.
• The color of the piece will be randomly generated according to the current theme. All blocks in a piece will have the exact same color.
• There are 12 possible colors for any piece or block according to the current theme. The piece or block may also be gray or in another default color if an old version unfinished game is loaded.
• Pieces cannot contain unoccupied blocks.
• The game queue is always filled.

Piece Placement

• Player must select pieces in the game piece queue. They may not select any other piece.
• Player can only select one piece at a time.
• Player must click on a block on the selected piece to complete selection.
• Pieces can NOT be rotated.
• Pieces can NOT change in size or color.
• Player can only place pieces when a piece is selected a valid location is clicked. This means the placed piece will not overlap with existing filled blocks, extend out of the boundaries of the game board, or occupy a location of a previously placed piece.
• Invalid placement will result in the deselection of piece and no change to the piece queue or game board.
• Once placed, piece will be dequeued from the game queue, which will result in another new piece be generated according to logic.
• Placing a piece of n blocks increments the game score by n, and game turn by 1.

Block Elimination

• When a row in any of the three directions are filled with blocks after a placement, that row will be eliminated. This means all blocks in that row will be set to empty.
• There is no particular sequence of elimination, which means two intersection row can be eliminated at the same time.
• Elimination is automatic, activated after any piece placement.
• Not all piece placements will result in block elimination.
• There is a short time delay between piece placement and elimination, as designed.
• Eliminate a total of n blocks increments the game score by 5 * n. If a piece is overlapped between two rows, it counts twice.

Game Ending

• When a piece is placed, queue updated, and elimination checked such that no more piece can be placed, the game ends.
• The score and turns of the game will be recorded.
• The game will be logged in a colored binary .hpyhex file inside the folder data.
• The terminated game will be connected with the user information.

Game Quitting

• The player may quit the game by clicking on the quit button inside the game at any time.
• The score and turns of the game will be recorded.
• The game will be logged in a colored binary .hpyhex file inside the folder data.
• The unfinished game will be connected with the user information.
• If the player logs in again with the identical information and game setting, and the game log exists in the correct location, the unfinished game could be revived with the unfinished board and game queue. The color of the board and queue of the unfinished game will be the exact same according to the current theme, because colors will be stored in color indexes since version 1.3.0. If you have are playing a safe on a version before that, colors maybe gray or random, depending on the implementation.
• The player may quit the game by quit the application.

Autoplay and "Dynamic Island"

• The "Dynamic Island" component, which is in the lower left corner of the game page, is mainly used to control autoplay. When autoplay is turned off or when the game has just started, the component contain two buttons. One button is a quit button, and it functions the same as the convention quit button just above the player's username, and clicking it will result in quitting and saving the game. The other button is autoplay start button, and clicking it will result in starting the autoplay in SLOW mode, following a brief animated transition. During the transition, the autoplay backend is initializing.
• When exit the transition animation, the autoplay may toggle between SLOW and FAST mode by clicking on the component. It is also possible to click on a small button inside the component, and clicking on that button will result in shutdown of autoplay, following a brief animated transition. During the transition, the autoplay backend is shutting down.
• Manually placing blocks or clicking on the board will also shutdown autoplay, in which the "Dynamic Island" will respond with the shutdown animation.
• In case the autoplay backend close unexpectedly due to process communication issues or interruption, the "Dynamic Island" will not reflect such closure, but the user can try to turn the autoplay on and off.
• All components in the "Dynamic Island" can detect hover. When hovering over they may change color in an animated way, expect for when a current animation is playing.
• The algorithm used in autoplay is Nrsearch, which is a greedy high-performing algorithm that fuses the advantage of Density Index's local optimization and Score Index's global optimization. This algorithm is fast and effective, and it is possible to survive for a long time with this algorithm. However, if machine learning models are enabled and available, and python evironment supporting that model is detected, the machine learning model will be used instead. When using a machine learning model, the autoplay will be smarter, but it will need time to load during startup.

Achievement System

The Achievement System lets players earn and track achievements in a game. It's easy to use, saves progress, and works smoothly in the background.

What It Does

• Defines Achievements: Set up achievements with names, descriptions, and icons using simple templates.
• Tracks Player Progress: Keeps a record of each player's achievements.
• Runs in the Background: Updates achievements automatically without slowing down the game. This is achieved through a dedicated thread that handles achievement checks and a clock thread that triggers periodic updates.
• Saves Data: Stores achievements as JSON files for easy loading and saving.

Key Features

Achievement Templates (GameAchievementTemplate)

• What They Are: Blueprints for achievements with a name, description, and icon.
• How They Work:
  • Provide an unique name for identification and brief description.
  • Define what players need to do to unlock the achievement.
  • Can be configured with implementation specific JSON fields for variable criteria.
  • Automatically generate a unique icon based on the achievement’s name (or use a custom one).
  • Stay consistent and can’t be changed once set.

Player Achievements (UserAchievements)

• What They Are: A collection of achievements tied to a specific player.
• How They Work:
  • Save all achievements a player has earned.
  • Each saved achievement is tied to its template for reference.
  • Only the game system can update them to keep things safe and consistent.
  • Can be saved to or loaded from JSON.

Special Achievements

• Hidden Achievements:
  • Secret achievements players don’t see in the game interface.
  • Used for tracking internal goals (e.g., game mechanics).
  • Saved and loaded like regular achievements but hidden from view.
• Phantom Achievements:
  • Special achievements that always check conditions, even if already earned.
  • Can be "unachieved" if conditions change.
  • Never shown to players and used for ongoing system checks.
• Markable Achievements:
  • Achievements that can be triggered by things like button clicks or external events.
  • Safe to use across different parts of the game.
  • Must be reset when switching players to avoid mix-ups.

How The System Works

1. Setup: Load achievement templates from a JSON file included in the game.
2. Playing: When a player is logged in, the system checks their progress in the background every 120ms (adjustable).
3. Saving: Achievements are saved as JSON to keep progress safe.
4. Shutdown: Stop the system cleanly to free up resources when the game is closed.

JSON Setup

Achievements are set up using JSON with these fields:

• name: A unique name for the achievement (required).
• description: What the achievement is about (required).
• icon: The achievement’s visual (optional, auto-generated if not provided).
• type: The kind of achievement (links to its specific rules).

The setup is automatically loaded when the game starts, and its contents are fixed.

Easter Eggs

Prohibited Usernames

The following usernames are prohibited from inputting into the log-in field in the log-in page. This includes the capitalized and lowercase versions of all words in the following list. If the player attempts to log in with those names, the message "GAME KEYWORD PROHIBITED!" will be displayed.

However, under special circumstances (as activating an Easter Egg), they may do something else. In addition, "out", "log out", and "logout" are functional keywords the logs the current player out.

Keyword List

- player
- default
- dev
- guest
- host
- user
- driver
- auto
- autoplay
- execute
- god
- evil
- devil
- hard
- easy
- harmony
- hash
- code
- game
- gamer
- happyhex
- hex
- name
- club
- event
- out
- logout
- log out

Special Game Modes

Special game modes alter game mechanics, and they would not be affected by setting or change the setting of the game. Currently, they are for you to discover and unlock. There are no prerequisites for activation.

They are normally not activated as it is for every other Easter Eggs, but it is also possible to switch to normal after activation.

1. God Mode
   A special game mode that alters the game piece generation. This mode effectively check the current game board statues and only generate pieces that will be placeable. This ensures that you can basically never end or lose the game, except by force quitting.

   This mode is packaged inside special.Logic and contained in special.FeatureFactory with the class tag hex.Piece and hint tag God.

   Spoiler: Activation

    To activate, go to settings and turn on easy mode. Then go to log in page and try log in as "God". This will display the message "THE DIVINE INTERVENTION!".
    To quit out of special modes, regardless of the current game setting, type "Normal" into the login field to switch back to normal. This will not change the game setting otherwise.

2. Hard Mode
   A special game mode that alters the game piece generation. This mode effectively attempts to generate the most difficult pieces to play. It usually favors pieces with 4 or more block but also accept pieces that are currently hard to play in the game field. Usually, if you can survive 25 moves in Hard Mode, you will have proven to have real skills in HappyHex.

   This mode is packaged inside special.Logic and contained in special.FeatureFactory with the class tag hex.Piece and hint tag Hard.

   Spoiler: Activation

    Method 1:
     Go to log in page and try log in as "Hard" or "Evil". This will display the message "RELEASING THE HARD MODE!".
    Method 2:
     Go to log in page and try log in as "Devil". This will display the message "PLACE UNBREAKABLE CURSE!".
    Quit:
     To quit out of special modes, regardless of the current game setting, type "Normal" into the login field to switch back to normal. This will not change the game setting otherwise.

Special Themes

These are themes that could only be activated during certain days. They will always activate regardless of the theme chosen or the game settings. When these themes are in activation, the theme switch button will still work, but they will not change the theme.

These themes can change the color of every component in the game and the launcher, and may also change the font of components.

1. Grayscale
   This theme turns everything on the game screen into grayscale. This theme is always activated on September 11th and has a 6% chance of activating on a normal day.

   This theme is packaged inside special.Styles and contained in special.FeatureFactory with the class tag java.awt.Color.

2. Lovely Theme (FilledWithLove)
   This is a Valentine's Day special theme. It turns the launcher and game board into primarily pink and purple color and also modify other colors in other components. This theme also replaces the animation that is placed after piece elimination with a disappearing pink heart. It is always activated only on Valentine's Day.

   This theme is packaged inside special.Valentine and contained in special.FeatureFactory with the class tag java.awt.Color and GUI.animation.Animation.

3. Spooky Theme
   This is a Halloween theme. It turns the launcher and game board into primarily orange and red, with other colors populating other areas of the graphics. This theme also replaces the font of the title, buttons, and display messages with spooky fonts to enhance effects of the holiday. It is always activated only on Halloween.

   This theme is packaged inside special.Halloween and contained in special.FeatureFactory with the class tag java.awt.Color and java.awt.Font.

4. Independence Day Theme
   Active on Independence Day. This theme contains two themes, one white and one dark, which can be toggled through the use of the theme settings. These two themes populate every pixel of the game with the colors of the flag, namely white, blue, and red. Game pieces colors will be reduced to six colors, three blue and three red. It is automatically activated on July Fourth.

   This theme is packaged inside special.Independence and contained in special.FeatureFactory with the class tag java.awt.Color.

5. GratefulHarvest Theme
   This is a Thanksgiving theme. It turns the launcher and game board into primarily orange, with other colors populating other areas of the graphics. The game pieces use colors that mimic the colors usually seen on the dinner table on Thanksgiving dinner and those during harvest, invoking a sense of grace. This theme also replaces the font of the title, buttons, and display messages with fonts to enhance effects of the holiday. It is always activated only on Thanksgiving.

   This theme is packaged inside special.Thanksgiving and contained in special.FeatureFactory with the class tag java.awt.Color and java.awt.Font. In the package, a special date class is defined to determine whether a day is Thanksgiving.

6. Snowy!!!
   This is a really special theme. This feature is to celebrate my friend Matthew Ye, who is the first person to reach 40 turns in Devil Mode, which is part of the Easter Eggs and can be activated by typing keywords into the Login Page. As he really enjoys at that time the version 1.3.2 of HappyHex, I revealed to him the ways to access hidden modes and my friend found Devil Mode especially interesting. For that, I promise him that I will add a new theme designed by him if he can reach a record score in that mode, and so he did. All colors in this special theme are picked by my friend and implemented by me as promised.

   This theme is packaged inside special.Snowy and contained in special.FeatureFactory with the class tag java.awt.Color.

Auto Play

The autoplay feature will be added in the future. With a click of a button, the player will be able to enjoy hands-off automatic piece placement in the "HappyHex" game. There would a button starting and stopping the automatic playing of the game. Meanwhile, the player may also place pieces manually, and Their intervention will pause the autoplay until the player starts it again. Separately, one button will enable the player to see engine suggestions of piece placements.
The first game engine will be built with random moves, and will not support suggestions. The more advanced version of Auto Play will feature methods to score positions of placements and suggests placements accordingly. As for now, code in game piece and game engine are gradually build to support position scoring and future machine learning. The final result of Auto Play will incorporate machine learning, which will enable better game results and even personalized game play.

Development

Contribution

This is mostly my project under my design, and I am managing all branches.

As of Version 2.0, all public contributions are welcome through pull requests. Please tag your pull request with appropriate labels, and explain what has been changed and why. Please also make sure your code is well documented and tested. Here are the specific package rules:

• Code in the package hex is the core of the game, and it is unlikely that I will accept any changes to this package unless it is a bug fix. Additional methods to HexEngine might be accepted if they are useful for future development, but you may need to explain why they need to exist in that class, instead of being a helper method in another class.
• The hexio package handles io of the hex package. It is a very stable package, and only bug fixes will be accepted. I am not making new .hpyhex file formats.
• Code in the package launcher is the launcher of the game. You are welcome to improve the user experience and graphics of the launcher, but please make sure they are well-designed and implemented. Changes to graphics will be approved if they are well-designed and implemented.
• Code in the package GUI is the graphics and user interface of the game. Do not change it unless you know what you are doing. Please rarely touch stuff in GameEssentials, because even I don't know how it works. Changes to graphics will be approved if they are well-designed and implemented.
• Code in the package special is for special modes and themes. You are welcome to add your own special mode or theme, but please make sure they are well-designed and implemented. Please also make sure they do not interfere with existing modes and themes. All special modes and themes must be registered in FeatureFactory.
• The python package's python code is used for machine learning, and are pulled from a separate repository. Please do not change anything in this package. If you want to contribute, please go to hpyhexml instead.
• Miscellaneous helper code is in the util package. You are welcome to add your own helper code, but please make sure they are well-designed, documented, tested, and organized.
• Contribution for Game Viewer please see Game Viewer README.
• Please do not change the project structure unless absolutely necessary. If you wish to change the project structure, please create an issue first explaining why it is necessary.
• Please contact me if you want to contribute to major features such as Autoplay, the game achievement system, the purchasable system, etc.

If you wish to suggest a feature, create an issue and add appropriate tags. Please add the enhancement label to your issue. Please also note that any suggestions to change architecture, coding language, and most suggestions to graphics improvements will be dismissed.

Contribution for Game Viewer please see Game Viewer README.

Developed Sections

These are parts of the game that are considered fully developed and refined. Unless there is a bug no further updates will be made.

1. Game Mechanics
   The underling data structure of the game, packaged in hex, is extensively tested and used from pre-release version 0.4 to the most recent release. Although method may be added for future purposes, modification in implementation or structuring are unlikely.
   
2. Game Graphics
   Not to be confused with Launcher Graphics, the game graphics refers to the page where the player actually plays the game. This portion include a hexagonal grid representing the game field (or engine), a piece queue for potential selection of pieces, and game information display. This page had its own background colors, which are separated from that of the launcher. However, it is dependent on the information provided by the launcher and cannot run on its own. All code for this section is currently under the GUI package.
   
3. Graphics Animations
   The robust linear animation handler animation is tested and documented. The handler is designed for simple temporary effects such as fading, expanding, or progress animations and implemented use java.awt package and java.awt.event. It is lightweight and not a Swing component. You are welcome to use it for your own project. Follow the javadoc in the source code for more details.
   
4. Special Modes
   Easter eggs modifying something fundamental in the game, whether it is piece generation, scoring and elimination rules, or others. Current implemented special modes include GodMode and HardMode, both of which change the difficulty of the game by change the piece generation logic. These game modes use the same injection interface as SpecialThemes, and are packaged in the same special package. Dedicated branch for special modes is special.
   
5. Game Viewer
   A separate runnable program that may read .hpyhex files and display them in a hexagonal grid without color. This program can be grayscale and simple to run with minimal dependencies. This viewer can read binary files or maybe json files.
   The Game Viewer feature on screen keyboard inputs to select which file to view, buttons to increment and decrement the moves recorded in the game, buttons to animate the game process forward or backward, slider for adjusting animation speed. It displays real time game scores, turn, and state associated with the moves. The game viewer is developed and should be a separate concern. See Game Viewer README for more.
   
6. Launcher Graphics
   This section concerns about the launcher of the game, namely the window that shows up when you open the application. The current launcher consists of a main page, with buttons redirecting to pages for player log in, settings, graphics themes, and, of course, the game itself. Branches such as gui are dedicated to the improvements of user experience. The branch fancy, which is no longer in use, was typically used to add fancy graphics.
   
7. Special Themes
   These are themes that could only be activated during certain days, such as Halloween, Independence Day, or Christmas. Some of them also serve as memorial to tragic events such as the September 11th attacks. These themes use the same injection interface as SpecialModes, and are packaged in the same special package. Dedicated branches would be special and sometimes fancy. Only Christmas theme is to be developed.
   

Directions of Development

The developing process are mainly separated into the following parts:

1. Game Play
   How the game is played. This including scoring systems, awards, resetting, fetching and displaying previous game scores, etc. Currently, the most recent score and turns, the highest score and turns, and the average score and turns can be seen when the game is over.
   
   Future considerations in this include setting passwords for user accounts, adding an achievement and purchasable system that would be linked with graphic themes, and providing a page for more detailed user game analysis.
2. Machine Learning
   A more precise way of describing this direction would be auto-game-play. This means a machine would be build to play the game while the player sit there and watch. This autoplay would be initially enabled through scoring algorithms and later through trained artificial intelligence operated in Python. This is a feature of the future but current architecture is being designed around it. At the same time, scoring and reward functions are gradually coming online.
   

Future Timeline

This timeline is subject to frequent change

• Latest Release: 2.0.1

Version 2 will be fundamentally different from all of Version 1 and be incompatible.

• Add user achievements
• Add completed achievements and unlockable system
• Make themes and shinning font unlock-able
• Use machine learning to train AI for advanced autoplay

Code packages

The packages in the source code, their dependencies, and their functions.

Mechanics

package hex
Dependencies:
None
Function:
The backbone of the game. It provides classes and interfaces for managing a hexagonal grid system, including coordinate calculations, game engine operations, and game piece operations.

Game Data

package game
Dependencies:
hex special, and Launcher
Function:
Handles more complex data of the game build on hex. This includes game piece queue operations, game piece generations, and game engine simulations.

Game Data Logging

package hexio
Dependencies:
None
Function:
Provides utility methods for converting hexagonal game components such as Hex, Block, Piece, HexEngine, and game moves to and from colored and uncolored binary representations. It helps developers to save game states to binary .hpyhex files, read them back, and manage game data efficiently. It is not dependent on any other packages and use internal versioning separated from Launcher.

Logging

package io
Dependencies:
javax.json
Function:
Provide data storage structures, such as game information, player information, game time, and logging functionalities. This package enables reading, writing, and converting game metadata, including player information, game sessions, and configuration presets into JSON format for persistent storage or transmission. It is not dependent on any other packages.

Graphics (GUI)

package GUI
Dependencies:
hex, hexio, Launcher, special, comm and javax.swing
Function:
Provides game page graphics through Java Swing. It also records critical game information and serves fundamental game logic to make the game function. This includes functions for buttons, color indication generations, interaction with the launcher, timer for elimination, and more.
This graphics component support dynamic resizing.

Launcher

package Launcher
Dependencies:
io, hexio, GUI, special, and javax.swing
Function:
Provides game launcher graphics through Java Swing. This includes the main page, the settings page, the login page, the game over page, the resume page, and the themes page. It also provides links to set up evironment and start or resume a game. In addition, it calls to the internal game logger to read local data. This includes logging player scores and turns, loading previous unfinished games, calculate player average turns and score, and more.

Python

package python
Dependencies:
pathlib and comm Function:
All python code are packaged here. These include basic hex package, game log reading, both coded in python and following the exact same logic as the java code in other packages. This also include autoplay code, machine learning model supports, and models.

Tests

package tests
Dependencies:
hex, hexio, and org.junit.jupiter.api.
Function:
Serves as a test package for the most fundamental functions of the game, ensuring the backbones are working as intended.

Special Features

package special
Dependencies:
dynamic, can include everything
Function:
Provide special themes, features, and Easter Eggs to the game. The generation is recorded in special.FeatureFactory.

Game Viewer

package viewer
Dependencies:
java.awt, javax.swing, hex, and hexio
Function:
The Game Viewer, a developer tool and standalone, grayscale visualizer for .hpyhex game logs created with the game. It is not integrated with the main game’s Launcher and is grayscale by design for simplicity. See Game Viewer README for more.

Command Processors

package comm
Dependencies:
None
Function:
To establish an interface to execute commands and enable callbacks between controllers and runners. This facilitates thus the communication between different processes by streamlining the command execution service.

Achievement System

package achievements Dependencies: io, GUI, util.geom, javax.json, and java.awt Function: To manage the achievement system, including serializing and deserializing achievement data, tracking player progress, and displaying achievements in the GUI. It also spawns and manages its own threading system to handle achievement updates.

Utility

package util
Dependencies:
Various, depending on the utility
Function:
A bunch of utilities used by the game, mostly generated by artificial intelligence and modified by me.