Really really good 'thinky' !
I have a technical question about the hint system and overall design. Does the game store some sort of tree of all possible game states for each level? If so, did you also use that tree to check that you can't softlock yourself by bringing balls into levels? If not, how does the hint system know if it's solvable or not? Also, how is "closest to the finish" measured if the path is not unique?
Great questions!
Each puzzle stores a set of every state in which the puzzle is solvable. Because the game is relatively small I was able to create these sets manually, but if the game were any larger I would have used a solver to find all the solvable states. Checking a hash set is a constant time operation, so it's virtually free to check if the current state of the puzzle is contained in the set, which if and only if it is, the puzzle is solvable.
Since each puzzle only has a finite number of shots the player can possibly obtain, and the player cannot move without consuming some sort of resource, each puzzle can be represented as a Directed Acyclic Graph with all solution states being leaf nodes. Because of this, we know that every move will always bring the player closer to a solution state (provided they move into a state that is contained in our solvable states set). Therefore, we can fairly accurately check how close a player is to solving a puzzle by just checking how many moves they have made in that puzzle.
I should also mention now that levels and puzzles are distinct. Some levels will have multiple puzzles in them. For instance, the level named "Bridge" has two different puzzles in it: the one entering from "Toucan" and exiting into "Gator", and the one entering from "Gator" with an extra ball and exiting into "Cyclone". This means that each level can have multiple sets of solvable states corresponding to different puzzles within the level. The game knows which puzzle the player is attempting to solve within a level by using the player's starting position, whether they brought a ball with them, and the lists of pipes the player has already entered and exited through. If there is no puzzle that matches the starting configuration, the hint system will say there is no solution.
Also, the game is designed in a way where it is never bad to bring a blue ball into a level with you, so there are no possible softlocks (as far as I'm aware)
