Puzzle design research
Designing a Hint That Does Not Leak the Answer
The simplest hint is to reveal the answer, and it is also the least useful. It ends the deduction instead of teaching it, and it turns the puzzle into a sequence of reveals. BeanNest uses a different model in its published games: a hint explains which public rule applies to the current position, leaving the player to make the inference. The difference is structural rather than a matter of phrasing.
What this guide helps you decide
A hint that tells you the right cell is just a solution. What can a hint usefully do instead?
This research explains the hint model BeanNest uses in published puzzle games. It does not publish hint output for a live puzzle and does not describe any game's internal solver.
Try it on the anchor product: BeanNest Games /games/.
The answer-oracle model
An answer oracle compares the player's board against a stored solution and reports where they differ. It can only work when a solution is available, which means the game holds one, and it cannot explain why the difference matters. It also degrades the puzzle, because a player learns that the fastest route to progress is to ask repeatedly.
The public-rule model
A public-rule hint looks only at the current board and the published constraints, then identifies a rule that applies. It can say that a constraint is currently violated, or that a particular pattern makes one value impossible. It never needs a stored solution, and the player receives a reason rather than a value.
Why the rule model also improves verification
Because the rule model works from the board and the constraints, its output can be checked the same way any move can be checked. The repository's evidence contract separates canonical puzzle state from presentation precisely so rules can be evaluated outside the browser. A hint system built on public rules inherits that verifiability, while an oracle cannot be checked without the secret it consults.
The conflict-feedback distinction
A related design decision is whether ordinary play tells the player that a move was wrong. Public-rule-only conflict feedback means a move is rejected only when it violates a stated rule, never because it differs from a hidden answer. That keeps the mistake the player's own and keeps the hint honest, because both operate on the same public information.
What a player experiences
With rule-based hints, asking for help produces an explanation that becomes reusable. After two or three hints a player typically recognises the pattern unaided. With an oracle, the same number of hints produces a partially filled board and no reusable understanding, which is why oracle hints tend to be requested more often rather than less.
Where the line is drawn
An explicit reveal control can still exist, and several published games provide one as a deliberate last resort. The distinction the guides draw is between an explanation that teaches and a value that ends the puzzle. Both can coexist, but the default assistance should teach.
Why the oracle model is tempting
An oracle is the simplest possible implementation: store a solution, compare it to the board, and report a difference. It requires no rule analysis and works for any puzzle that has a solution. The temptation is strong because the code is trivial, and the cost is deferred to the player, who receives a value instead of an understanding.
How a rule hint is computed
A rule hint examines the current board and the published constraints, then identifies a constraint that applies to the current position. It can report that a stated constraint is violated without needing to know the answer, because the violation is a property of the board. The computation is local to the rules, which is why it works identically for a board nobody has solved before.
Why both models can coexist
Several published games offer an explicit reveal as a deliberate last resort alongside rule-based assistance. The distinction the guide draws is about the default, not about prohibition. A player who wants the answer can have it; a player who asks for help receives an explanation first, which keeps the puzzle's reasoning available to them.
How this interacts with conflict feedback
If ordinary play rejects moves by comparing them to a hidden answer, then the game is already using an oracle and the hint is only one surface of it. Public-rule-only conflict feedback keeps the same information basis for rejection and for assistance, so a player's mistakes remain their own and the help remains explanatory rather than authoritative.
Why an oracle degrades the puzzle over time
An oracle teaches that progress comes from asking, so a player who uses it repeatedly becomes faster at requesting help rather than faster at solving. The puzzle's reasoning is bypassed each time, and the bypass is cheaper than the reasoning, which is a strong incentive to repeat it. The degradation is gradual and is why the model is unattractive even when it works.
How a rule hint stays useful across puzzles
A rule explanation transfers to any board governed by the same rule, because it describes the constraint rather than the current state. A player who learns that a split pair forces the middle can apply that to a board they have never seen. An oracle produces no transferable fact, which is the clearest difference between the two models.
Why the two models can coexist
Several published games offer an explicit reveal as a last resort alongside rule-based assistance. The guide distinguishes the default from the option: a player who wants the answer can have it, while a player who asks for help receives an explanation first. That ordering keeps the reasoning available without forbidding a direct answer.
How the two models differ in what they require
An oracle requires a stored solution for every board it will ever advise on, which means the game must possess answers for boards it has not yet served. A rule model requires only the constraints and the current position, which is the same information any played move already uses. The second requirement is smaller and is satisfied by the rules the game already publishes.
Why the choice affects what a player learns
An explanation transfers to other boards because it describes a constraint; a revealed value does not transfer because it describes one cell. A player who receives explanations accumulates reasoning they can reuse, while a player who receives values accumulates only progress. That difference is the practical consequence of the design choice rather than a philosophical one.
How the models can coexist without conflict
Several published games offer an explicit reveal as a last resort alongside a rule-based hint. The guide distinguishes the default from the option: help means an explanation, and an answer is available on request. That ordering keeps the reasoning available without forbidding a direct answer, which is why both can be present in one game.
How a player would notice the difference
A player using a rule hint reads an explanation and then makes a move. A player using an oracle reads a value and copies it. The first produces a moment of understanding that changes what the player can do on the next board; the second produces progress on the current board only. The difference is observable in play rather than only in design discussion.
What the guide declines to claim
It does not claim that rule hints improve learning or that any measured outcome follows from them, because this repository has not collected such data. It describes the two models and the reasoning behind the preference, and it stops there.
First-party evidence and provenance
How we checked this
We reviewed the evidence contract and the published rule metadata for a representative logic game to confirm that conflict feedback and hints operate on public constraints rather than on a hidden solution. We did not inspect or publish any stored solution state.
- Method
- We reviewed this repository's evidence contract and the published game metadata, then traced the shipping behaviour to confirm the mechanism described here. We deliberately did not read or publish a hidden solution state.
- Environment
- Repository source review of the current main branch. No live traffic, account data, or player-identifying information was read.
- Captured
- Reviewed by
- BeanNest Studio
Repository evidence artifacts:
docs/gameplay-reconstruction/EVIDENCE-CONTRACT.mdgames/bit-balance/game.json