Clue Journal

A clue journal keeps every clue the player finds, once, and lets them connect two of them to work out something new. A fitting pair is written down as a deduction, which can be connected like a clue. When the case's deductions are made, the player can close it. After a few misses the journal hints.

Also called: Case notebook, Evidence board, Deduction log.

A small owl detective in a crumpled raincoat pulls a red thread between a muddy boot print and a damp cloak sleeve on a cluttered corkboard, and a little yellow lightbulb pops open above the board. — Pennyfeather Attic, an invented sketchbook detective game. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Clue Journal" to my game.

What it should do: The player solves a mystery by thinking, not by walking into the right room. The journal remembers what was found, checks what the player connects and helps when they are stuck, without ever giving the answer away.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> empty
  empty: No clues yet
  gathering: Gathering clues
  hinted: Hint shown
  ready: Ready to close
  solved: Solved
  empty --> gathering: first clue found
  gathering --> hinted: too many misses
  hinted --> gathering: a pair fits
  gathering --> ready: last deduction made
  hinted --> ready: last deduction made
  ready --> solved: player closes the case
  solved --> [*]
```

Use these starting values:
- hintAfter: 3 misses
- revealPairs: 1 pairs

Watch out for these common mistakes:
- A clue that can be missed: Tell your AI: for every clue that can be missed, play the case forward without it. If a needed deduction disappears, give that clue a second place to be found.
- Red herrings: Tell your AI: keep every clue the case lists, and never make a deduction depend on a clue only because it was found.
- The same pair twice: Tell your AI: a pair that was already made is ignored, not counted as a miss. The same goes for finding a clue twice.
- A hint that spoils: Tell your AI: build a hint only from things the player already holds, and name pairs, never the deduction itself.
- Using a deduction too early: Tell your AI: only clues found and deductions made can be connected. Anything else is ignored.
- A case that asks for nothing: Tell your AI: a case that needs nothing counts as done as soon as the first clue is found. Better still, never ship one.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

The player solves a mystery by thinking, not by walking into the right room. The journal remembers what was found, checks what the player connects and helps when they are stuck, without ever giving the answer away.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

No clues yet → Gathering clues: first clue found
Gathering clues → Hint shown: too many misses
Hint shown → Gathering clues: a pair fits
Gathering clues → Ready to close: last deduction made
Hint shown → Ready to close: last deduction made
Ready to close → Solved: player closes the case

Good starting values

Value	Start with	What it changes
hintAfter	3 misses	How many connections in a row may miss before the journal helps. Three leaves room to try things before it steps in.
revealPairs	1 pairs	How many pairs a hint names. One nudges, three nearly solves the case for the player.

What usually goes wrong

A clue that can be missed

If the only way to learn something lies in a room the player can skip for good, the case can no longer be closed and nobody notices until the end.

Fix: Tell your AI: for every clue that can be missed, play the case forward without it. If a needed deduction disappears, give that clue a second place to be found.

Red herrings

A clue that belongs to no link is easy to treat as a bug: the journal drops it, or the case waits for it.

Fix: Tell your AI: keep every clue the case lists, and never make a deduction depend on a clue only because it was found.

The same pair twice

A player who connects a pair they already worked out gets a miss and sooner or later a hint they do not need.

Fix: Tell your AI: a pair that was already made is ignored, not counted as a miss. The same goes for finding a clue twice.

A hint that spoils

A hint that names clues the player has not found, or the final answer, takes away the thinking the case was built for.

Fix: Tell your AI: build a hint only from things the player already holds, and name pairs, never the deduction itself.

Using a deduction too early

If a deduction can be connected before it is made, the player can skip a step of the story.

Fix: Tell your AI: only clues found and deductions made can be connected. Anything else is ignored.

A case that asks for nothing

A case with no needed deductions can be closed at once, or never, depending on how the check is written.

Fix: Tell your AI: a case that needs nothing counts as done as soon as the first clue is found. Better still, never ship one.

How to check it works

An empty journal. The player finds a clue that belongs to the case: The journal holds that clue.
A journal that already holds a clue. The player finds it again: The journal still holds it once.
A journal with a pair of clues that belong together. The player connects them: The journal writes down the deduction.
A journal with a pair of clues that belong together. The player connects them the other way round: The deduction is made just the same.
A journal with two clues that do not belong together. The player connects them: Nothing is written down and the miss counter goes up by one.
A journal with a deduction and a clue that fit together. The player connects them: A second deduction is made.
A journal where two connections have missed and a fitting pair is in hand. A third connection misses: The journal names the fitting pair.
A journal that is showing a hint. The player makes a fitting connection: The misses go back to zero and the hint disappears.
A journal that is missing a needed deduction. The player tries to close the case: The case stays open and no miss is counted.
A journal with every needed deduction. The player closes the case: The case is solved.
A case with one clue that can be skipped and is needed. The whole-case check plays the case forward without it: The check names that clue and the deduction that is lost.

Works well with

Dialogue System: A line of talk can be a clue. Give each clue one name, so the journal and the conversation agree on what was found. Let the conversation hand out the clue first, then let the journal write it down.
Key Items: A found object can be both: the item goes in the bag, and its clue goes in the journal. Keep the two lists apart so using up the item never removes the clue. Decide first which things in the world are clues and which are only objects the player carries.
Achievements: Solving a case is a natural milestone, and so is solving it without a single hint. Count a solved case after the journal closes it, not when the last clue is found.

Common questions

how do i make a detective game where the player connects clues

Give every clue a name, list which pairs make a deduction, and check each connection the player tries against that list. A fitting pair writes down a deduction, and a deduction can be connected like a clue. Ask your AI to keep each clue once and never lose a deduction.

how do i stop a player from missing a clue and getting stuck

Play the case forward without each clue that can be skipped. If a needed deduction disappears, give that clue a second place to be found. Ask your AI to run this check whenever you change a case.

when should a mystery game give a hint

After a few connections in a row that miss, three is a good start. Name a pair the player already holds, never a clue they have not found and never the answer itself.

what do i tell my ai to add a clue journal

Paste this: Add a clue journal. Each clue is kept once. The player connects two clues or deductions, and a fitting pair writes down a new deduction. After three misses in a row, name one pair the player already holds. The case can be closed only when every needed deduction is made. Then check the whole case for clues that can be missed.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

24 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it