"I know what to do but I'm stuck": a game hint system with a hint ladder, timed nudges and three more tricks
Five tricks for a game hint system side by side: rules taught alone, confirmed steps, a delayed nudge, a hint ladder from vague to explicit and an in-world pointer.
What we asked“Make a web page that demonstrates the five hint tricks that get stuck players unstuck without spoiling the puzzle one at a time, so anyone can see and feel each one within a few seconds. For each one, show the same short moment side by side: without it on the left, with it on the right, playing in a loop, with a caption that says what just happened and a replay button. Where it helps, let me play the moment myself. It will sit inside a blog post about 720 pixels wide, so it has to look good at that width and on a phone. Also make each one viewable alone with ?trick=<id>&solo, using these ids: teach-alone, step-confirm, timed-nudge, hint-ladder, world-pointer. Use one small, original switch-and-door puzzle for all five, compress any waiting to a few seconds (show a clock), and on the left let the player stay stuck or get the whole answer dumped at once. Use the internet freely for better results: free CC0 art, fonts or small libraries (for example Kenney's CC0 assets) are welcome; download anything you use into this folder so the page works without outside links, and list each item with its licence and source in CREDITS.md.”
What happened
- Loaded the puzzle-hint-system skill
- Downloaded Kenney's CC0 Tiny Dungeon tiles and Kenney fonts, after working out the real download link hidden behind a JavaScript step
- Wrote one switch-and-door puzzle engine, scripted side-by-side loops for each trick, and a play mode
- Checked the other four loops, the "answer dumped" mode, play mode and the phone layout, with no console errors
- Put each trick behind its own on/off switch, with every right side turning on exactly one
- Listed the art and font with their CC0 licences in CREDITS.md
“I know what to do but I’m stuck” usually means one of two things went wrong. Either the player never learned a rule the puzzle needs, or they’re close and nothing tells them so. A big “Show answer” button fixes the stuck part and spoils the rest. Professor Layton does it with more care: each puzzle has three hints, and you spend a hint coin to open each one (Wikipedia).
All five demos use the same small puzzle: three floor plates (▲ ● ■), three lamps over a shut door, and a stone by the door with the order carved on it. Step on the plates in that order and the door opens. Both sides start the same way: the player tries ●, ▲, ■ and gets stuck. The clock in each room is in-game time, and a yellow fast-forward badge shows when waiting is sped up. The Left switch picks how the left side fails: Stays stuck ends in QUIT near five minutes, Answer dumped shows the whole answer in one box and ends in SPOILED. Play lets you tap the plates yourself, with time running at ×20.
1. Teach each rule on its own first
Before the real puzzle, introduce each rule in a tiny puzzle that uses only that rule. Then combine it with rules the player already knows. Super Mario 3D Land director Koichi Hayashida describes the same order: “First, you have to learn how to use that gameplay mechanic”, then “a slightly more complicated scenario”, then “something crazy happens” (Game Developer). In our demo, room 1 has one plate and one lamp, and room 2 adds the stone with two marks. In the real room the player goes straight to the stone and solves it with no hint, at 1:18 in-game, never stuck longer than 0:23.
2. Confirm every correct step
When a step is right, say so at once: a click, a part that stays down, a light that stays on. When it’s wrong, give nothing. Then the player can work forward one step at a time instead of guessing the whole order. In Portal 2’s puzzle maker, a row of indicator dots runs from a button to what it opens, “blue when the connection is inactive, and orange when activated” (Valve Developer Community). In our demo, the left player tries orders with no feedback and quits. On the right, ▲ clicks and lamp 1 stays lit, a wrong ■ puts the lamps out, and the door opens at 0:52, with no gap longer than 0:17.
3. A small nudge after two minutes stuck
If the player makes no progress for about two minutes, give one small hint inside the world: a sparkle on the right object, a character glancing at it. Never in the first minute, and reset the timer on every correct step. Players can find early hints annoying: God of War Ragnarök’s PC version added an option that “will reduce the frequency with which you hear puzzle hints from your companions” (PlayStation Blog). In our demo, a “no progress” timer counts in the corner of the right room. Nothing happens until 2:00, then a sparkle appears on the stone. The player reads the order themselves and solves it at 2:46.
4. A hint ladder, one rung per press
When the player asks for help, give the smallest hint first. Each press gives the next rung: 1 where to look, 2 which rule matters, 3 the next step, and only then 4 the full answer. Never skip ahead. Thimbleweed Park’s in-game hint line gives “progressively more explicit hints, including a solution” (PC Gamer), and Paul Franzen keeps his hints “vague at first, so the player can still have that ‘EUREKA!’ moment” (Game Developer). In our demo, hint 1 says “Look at the wall beside the door” and hint 2 says “The marks on the stone are an order”. The player solves it on hint 2 at 1:39, and hints 3 and 4 are never opened.
5. Point inside the world, not in a text box
Show the next step in the world itself: light the object, turn the camera to it for a second, or have a companion stand by it. The player still reads the clue and makes the connection. Indiana Jones and the Great Circle uses Indy’s in-game camera as its optional hint tool; director Jerk Gustafsson, as quoted by GamesRadar+, says “We don’t have to be afraid that we need to completely dumb it down because someone gets stuck” (GamesRadar+). In our demo, pressing Ask Pip sends a companion to stand under the stone, and the stone lights up. There is no text. Solved at 1:00, with no gap longer than 0:34.
Don’t make hints too easy
A hint that’s always one click away gets used before the player has really tried. Jenn Sandercock, who worked on Thimbleweed Park’s hint line, puts it simply: “If it’s super easy to get hints, then people will do that all the time” (PC Gamer). Rules for tuning:
- The full answer is the last rung, never the first. If testers often reach rung 4, the puzzle or an earlier rung needs work, not a faster answer.
- Start the nudge timer at about two minutes, never under one, and let players turn timed hints down or off.
- Measure the longest gap without a correct step. In our demo, the left side’s gap is about 4:50 before the player quits; every trick on the right brings it under 2:30, most under 1:15. With the tricks on, most solves should need rung 1 or 2 at most, and no one should quit.
Add it to your game
- Copy the skill at the end of this page into your project.
- Ask your agent: “Players get stuck on my puzzles. Add hints that don’t spoil them.”
- Play it, then tune in plain words: “The sparkle comes too early, I almost had it.”
Art in the demos: Tiny Dungeon and the Kenney Mini font by Kenney (CC0).
The skill that made it work
This is the whole skill we gave Claude Code. Copy it into your project and ask your agent to help stuck players without spoiling your puzzles. Every trick sits behind its own switch, and the last step makes it measure how long players stay stuck.
- Find every puzzle: its rules, its solution steps in order, and where players stall.
- Put every trick behind one named switch in a single settings object, all on by default, so each can be tested on its own.
- teach-alone. Introduce each new rule in a small puzzle that uses only that rule, then combine it with known rules. Mario 3D Land's director: first learn the mechanic, then a slightly harder use, then a twist.
- step-confirm. Confirm every correct partial step at once: a click, a light that stays on, a part that moves into place. Portal 2's indicator dots run from a button to what it opens and turn from blue to orange when it is active. Wrong steps get no reward sound.
- timed-nudge. If the player makes no progress for about 2 minutes, give one small in-world nudge (a character glances at the right object, a sparkle on it). Never in the first minute: God of War Ragnarök later added a "reduced puzzle hints" option after players found its companions too quick to help. Reset the timer on each correct step.
- hint-ladder. On request, give hints in order: 1 where to look, 2 which rule matters, 3 the next step, and only then the full answer. One rung per press, never skip ahead. Thimbleweed Park's in-game hint line gives "progressively more explicit hints, including a solution."
- world-pointer. Point at the next step inside the world, not in a text box: light the object, swing the camera to it for a second, or have a companion stand by it.
- Measure it. Have testers or a bot play each puzzle with tricks on and off. Log the longest gap without a correct step, which hint rung solved it, and quits. With tricks on, the longest stuck gap should drop, most solves need rung 1 or 2 at most, and no one quits a puzzle.
Save it as .claude/skills/puzzle-hint-system/SKILL.md in your project. Or connect your agent and type /aigamedev: it loads this skill with its reference files and the results from this post.
