Project Convention

This page outlines the general convention used when naming files and choosing what classes to edit during project development.

General Convention

Naming Folders and Files

All Java Classes use Pascal Case, while all functions use Camel Case. Test puzzle files should be named according to the rule that uses the puzzle in its tests. Please place test puzzle files outside of the repository or add them to your local .gitignore file.

Coordinate System

Because of how arrays are represented in code, cells are indexed using (x, y), starting from (0,0) at the top left of the board. Increasing y corresponds to lower rows in the grid, and growing x moves right along the grid.

Vocabulary

• Grid: A coordinate plane where each coordinate consists of a single cell.
• Cell: An element in a grid (usually in the form of a square).
  • A cell is unknown if its content is unknown.
  • A cell is adjacent to another cell if they are orthogonally adjacent (orthogonal directions consist of left, right, up, and down).
  • A cell adjoins another cell if they are either orthogonally or diagonally adjacent.
• Content: The content or data inside a single cell.
• Region: A set of cells that are all adjacent to each other.
• Proof Tree: The branching structure in the bottom of the proof editor when you are solving a puzzle.
• Node: A circle or triangle in the proof tree, connected by a black line.
  • Every node holds a board state, which is the board and all moves made up to the given node.
  • A node is a leaf if there are no nodes that are directly connected to the right of it
  • A transition node is one of the triangular nodes, which holds some logical rule that proves the validity of a given move.

Folder Structure

LEGUP Engine

The Engine code is located within the /src/main/java/edu/rpi/legup/ directory. It is split between ./app, ./controller, ./history, ./model, ./save, ./ui, and ./utility. The ./Legup class is the entry point to the entire program. See documentation (WIP) for more information about each part of the Engine.

Puzzles

Puzzles may be referred to as multiple names online, such as nurikabe and that black and white tile puzzle. Only one should be used in the context of LEGUP to maintain consistency.

The implementation for puzzles is located at /src/main/java/edu/rpi/legup/puzzle/<puzzle_name>, which includes all backend code. Any images used to display puzzle elements are located in /src/main/resources/edu/rpi/legup/images/<puzzle_name> Following the Implementing Puzzles Guide ensures the correct format that the engine looks for when loading puzzles.

JUnit tests are located in /src/test/java/puzzles/<puzzle_name>/rules and run automatically during a pull request or manually through IntelliJ. Mock puzzle boards used for testing are stored in /src/test/resources/puzzles/nurikabe/rules/. Each rule for a puzzle has a folder named after the rule, containing puzzle files used for testing. These files should briefly describe what they test for. For example, DiagonalBlackBetweenRegions1 checks that connecting cells between two diagonal white cells are correctly identified, and EmptyRow3x3OneTent ensures the FillInRowCaseRule creates 3 cases for how to place a tent in an empty row of size 3.

Puzzle Rules

Rule names should describe the action the rule allows/disallows. The description should 3 words of less, and be in the format [Description][Rule Type]. For example, the Star Battle FinishWithTentsDirectRule fills in a row or column with tents when all unknown cells must be tents, and the Skyscrapers ExceedingVisibilityContradictionRule checks for cases where too many skyscrapers are visible.

Puzzle Files

Within the "Puzzle Files" folder, each puzzle should have its own folder named after the puzzle type. Inside each of these puzzle type folders, there should be subfolders organized using the format [Size] [Puzzle Type] [Difficulty]. For example, 5x5 Nurikabe Easy or 8x8 Binary Very Hard. Difficulties should be limited to Easy, Medium, Hard, and Very Hard. Within these subfolders, the puzzle files themselves should be named to reflect their parent folder and a sequence number, following the format [Subfolder Name] [File Number]. For instance, the folder 6x6 Binary Easy would contain files named 6x6 Binary Easy 1, 6x6 Binary Easy 2, and so on.

Star Battle puzzles are also differentiated by the number of stars, which is currently not displayed anywhere while solving. Until the GUI is updated, there is no way of knowing how many stars need to be placed in each region apart from the puzzle name. Thus, puzzles will be named [Size] [Puzzle Type] [Difficulty] [Star Count] Stars for now.

Miscellaneous

There are various folders within the / directory. These include:

• .github: Files used by GitHub when utilizing the Git version control system.
• .idea: Files used by IntelliJ
• bin: Unused (Trash bin ?)
• build: Local build of LEGUP when running the [jar] or [build] Gradle configuration.
• config/checkstyle: Checkstyle requirements
• gradle: Gradle information
• legup-update: Auto-Updater for LEGUP install. Currently not working
• output-path: Unused