Quest Log
A quest log keeps a list of quests with goals that count up. Game events add to every active quest that wants them, progress stops at the goal, a quest with a hand-in waits for the player, optional goals never block, and the log always points at one quest being worked on.
Paste this to your AI
Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.
Add "Quest Log" to my game.
What it should do: A quest log tells the player what they are doing and how far they are. It has to be right at every moment: the numbers count what the player did, finished quests stay finished, the tracker never points at something that is over, and a long list of tasks stays small enough to manage.
Build it exactly as this state machine. First check that it fits my game, then build it like this:
```mermaid
stateDiagram-v2
[*] --> open
open: Not taken
active: In progress
ready: Ready to report
done: Finished
failed: Failed
open --> active: player accepts
open --> ready: accepts with goals met
active --> ready: goals met, hand in
active --> done: all goals met
ready --> done: player hands in
active --> open: player abandons
ready --> open: player abandons
active --> failed: quest fails
ready --> failed: quest fails
failed --> open: player retries
done --> [*]
```
Use these starting values:
- maxActive: 5 quests
- keepProgressOnAbandon: 0
Watch out for these common mistakes:
- A goal counts past its limit: Tell your AI: hold every goal at its limit, and handle a goal that is already full as no change.
- Deeds from before the quest: Tell your AI: decide it and write it down. Here events before taking a quest are lost, and the quest starts at zero.
- One deed that serves two quests: Tell your AI: give every active quest with a matching goal the event.
- An optional goal that comes too late: Tell your AI: give quests that have optional goals a hand-in, and keep counting the optional goals until it.
- A quest abandoned when it was ready: Tell your AI: check the goals when a quest is taken, and make it ready or done at once if they are met.
- The tracker points at a finished quest: Tell your AI: after every change, move the tracker to the next quest in progress, or to none.
- A failed quest that keeps counting: Tell your AI: count events only for quests in progress, and clear the progress on a retry.
- A full log that cannot be left: Tell your AI: count quests waiting for a hand-in as taking a place.
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
A quest log tells the player what they are doing and how far they are. It has to be right at every moment: the numbers count what the player did, finished quests stay finished, the tracker never points at something that is over, and a long list of tasks stays small enough to manage.
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
- Not taken → In progress: player accepts
- Not taken → Ready to report: accepts with goals met
- In progress → Ready to report: goals met, hand in
- In progress → Finished: all goals met
- Ready to report → Finished: player hands in
- In progress → Not taken: player abandons
- Ready to report → Not taken: player abandons
- In progress → Failed: quest fails
- Ready to report → Failed: quest fails
- Failed → Not taken: player retries
Good starting values
| Value | Start with | What it changes |
|---|---|---|
| maxActive | 5 quests | How many quests can be open in the log at once, counting those waiting for a hand-in. Five is what a player can keep in their head. With more, they stop reading the log. |
| keepProgressOnAbandon | 0 | Zero starts a quest from nothing when it is taken again, so abandoning never costs less than finishing. One keeps what was done, which is kinder, but lets a player park a half finished quest. |
What usually goes wrong
A goal counts past its limit
A goal that needs five pieces of wood can show seven if the count is added without a limit, and a screen that reads 7 of 5 looks like a bug.
Fix: Tell your AI: hold every goal at its limit, and handle a goal that is already full as no change.
Deeds from before the quest
A player who killed wolves before taking the wolf quest expects them to count, or expects them not to. Games that do it by accident confuse both kinds of player.
Fix: Tell your AI: decide it and write it down. Here events before taking a quest are lost, and the quest starts at zero.
One deed that serves two quests
If the first quest that wants an event takes it, a second quest for the same deed never moves.
Fix: Tell your AI: give every active quest with a matching goal the event.
An optional goal that comes too late
A quest without a hand-in is finished the moment its needed goals are met, so an optional goal done a moment later is lost, and the player feels cheated.
Fix: Tell your AI: give quests that have optional goals a hand-in, and keep counting the optional goals until it.
A quest abandoned when it was ready
With progress kept, taking the quest again can leave it open with all its goals met and no way to finish it.
Fix: Tell your AI: check the goals when a quest is taken, and make it ready or done at once if they are met.
The tracker points at a finished quest
When the tracked quest ends, the log still shows it, or shows nothing although other quests are open.
Fix: Tell your AI: after every change, move the tracker to the next quest in progress, or to none.
A failed quest that keeps counting
Events keep adding to a failed quest, and a retry starts with progress from before the failure.
Fix: Tell your AI: count events only for quests in progress, and clear the progress on a retry.
A full log that cannot be left
If quests waiting for a hand-in do not count toward the limit, a player can pile up more quests than the log can show.
Fix: Tell your AI: count quests waiting for a hand-in as taking a place.
How to check it works
- A quest nobody has taken. The player takes it: It is in progress, all goals are at zero, it is tracked, and taking it a second time is refused.
- A goal that needs 5 pieces of wood. 7 pieces come in at once: The goal reads 5, and more wood afterwards changes nothing.
- A quest with two needed goals. They are met in one order, or in the other: Both times the quest is finished, and with only one goal met it is still in progress.
- A quest without a hand-in and one goal still open. The last goal is met: The quest is finished and no longer tracked.
- A quest with a hand-in and its needed goals met. The last goal is met, and later the player hands it in: It is ready to report first and only finished after the hand-in; handing in too early is refused.
- A quest with an optional goal. The needed goals are met without the optional one: The quest is ready, and an optional goal met first does not finish it alone.
- A quest ready to report. The optional goal is met, and more of a needed goal comes in: The optional goal counts, and the needed goal stays at its limit.
- A quest nobody has taken. Its event happens twice, and then the player takes the quest: The events changed nothing and the quest starts at zero.
- Two quests in progress that both want the same event. The event happens twice: Both quests move by two.
- A log limit of 2 with two quests in progress. The player takes a third, then one of the two is ready to report, and the third is tried again: Both tries are refused, and after the hand-in the third can be taken.
- A quest that needs another one finished first. The player takes it before, while the other is only ready to report, and after the other is finished: The first two tries are refused and the last one works.
- A quest with some progress. The player gives it up and takes it again: It is open, not tracked and its progress is zero.
- Keeping progress is on. The player gives up a quest and takes it again: Its progress is kept, and a quest given up while ready to report is ready again at once.
- A quest in progress. It fails: Nothing counts for it, taking it directly is refused, a retry makes it open with zero progress, and then it can be taken.
- A finished quest. The player tries to take, give up, fail, retry, hand in or track it, or an event for it comes in: None of it changes anything.
- Two quests in progress with one tracked. The tracked one is finished, and later the other fails: The log moves to the other one, and then to none; a quest that is not in progress cannot be tracked.
- A quest in progress. An event comes in with an amount of 0, below 0, not a number or a fraction below 1: It is ignored; an amount of 2.9 counts as 2 and a missing amount as 1.
Works well with
- Branching Choices: If the player goes back, the log must go back with them, or it shows a quest they never took. Update the log in the same step as the choice.
- Dialogue System: A hand-in is often a talk. Let the same line that thanks the player finish the quest. Offer the quest at the end of the line, take it when the player agrees.
- Experience and Levels: Reward once, when the quest becomes finished. A reward given on every update is paid several times. Give the reward in the step that finishes the quest.
- Multiple Endings: An ending that depends on quests should read the finished ones, not the ones the player happened to see. Count finished quests into the scores in the same step.
Common questions
how do i add a quest log to my game
Paste this: Add a quest log. A quest has goals with a number each, and game events add to the goals of every quest in progress that wants them, never past the goal. A quest is finished when every needed goal is met, or ready to report if it has a hand-in. Optional goals never block. Allow 5 quests at once, count quests waiting for a hand-in, and keep a tracker on one quest in progress.
should quest progress count from before the player took the quest
Either can work, but decide it. Not counting is simpler and safer, and the quest always starts at zero. Counting past deeds feels generous for things like items in the bag, but is confusing for kills.
how many quests should be active at once
About five. It is what a player can remember, and what fits a screen. More, and the log becomes a chore. Keep a tracker on one so the player always knows what to do next.
what happens to quest progress when the player gives up a quest
By default it starts from zero when taken again, so giving up is not cheaper than finishing. Keeping the progress is kinder, but check the goals when the quest is taken again, or a quest that was ready can come back stuck.
Where it comes from
We could not find a reliable origin for this one yet.
What was checked
- 20 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.
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