Game Blueprints for AI: What They Are, How to Write One
A game blueprint is a plain description of one mechanic that your AI builds from, covering its states, its settings, what must always hold and the tricky cases. It works better than describing the mechanic in a chat, because you can check a blueprint before anything gets built.
The word has a second meaning: Unreal Engine has a visual scripting system also called Blueprints. That is a different thing. Here, a blueprint is a document.
What is in a blueprint?
Here are the parts, for an invented fishing mechanic: you cast, a fish nibbles, and you have a moment to strike.
- Purpose. Why it exists. "A moment of tension after a long wait."
- States. All the situations the mechanic passes through, and what leads to the next, as a diagram.
- Settings. Each number with a starting value and what changes if it goes up or down. "Strike window: 0.6 seconds. Longer is kinder, shorter is harder."
- Rules that must always hold. "A fish can only be hooked once per cast."
- Tricky cases. "You strike before any nibble." "The game pauses mid-strike."
- Things to try. What to do in the game to see that it works.
Mermaid lets your AI show you the second part as a picture, written in a few lines of text:
stateDiagram-v2
[*] --> Waiting
Waiting --> Nibble: fish bites
Nibble --> Hooked: I strike in time
Nibble --> Waiting: window ends
Hooked --> Landed: reeled in
Hooked --> Waiting: line snaps
Landed --> [*]
Why check it before building?
This is the step that decides the quality of everything after it, so do not skip it. Draw first, check the drawing, and then build from it, in that order.
Look at the diagram above for one minute, and two problems appear.
A loop with no end. Nibble, window ends, waiting, nibble, forever. Nothing says the fish ever leaves. So you add a box: after three nibbles, the fish swims away.
A missing arrow. There is no arrow for striking too early. The AI would fill that gap with a guess. So you decide: an early strike scares the fish, and the cast ends.
Both were found without a line of code. Fixing an arrow takes seconds, and fixing the same thing in a built game can take an evening.
Next comes the rule check. Your AI goes down each path and gives the reason a rule survives there, or shows you the path that breaks it. Here it finds one: hooked, line snaps, waiting, nibble, hooked again. That is a second fish on one cast, so "a fish can only be hooked once per cast" is broken. The fix is one arrow: a snapped line ends the cast. A path you can follow on the diagram is worth more than "yes, that works".
When do I need one?
Whenever a mechanic has more than two states, or depends on another. A colour change needs none. A save file or a quest does.
Where do blueprints come from?
The blueprints here cover common mechanics, with values and usual mistakes. See coyote time for a full one. With Spielerando connected over MCP, your AI can fetch them itself, along with ready-made code and the wiki. It takes a free account through Google or an e-mail address, and your game and code are left alone. Set it up here.
For anything else, have your AI write one.
Paste this to your AI
I want to add this to my game: [describe the mechanic].
Do not build it yet. Write a blueprint in blueprint.md:
1. Purpose, in one sentence.
2. A Mermaid diagram of every state and what moves it on.
3. Settings: each number, a starting value, what changes if it goes up or down.
4. Rules that must always hold.
5. Tricky cases: what goes wrong, and what should happen.
6. Things I can try in the game to see that it works.
Then check your own blueprint. Go down each path and give the reason each rule survives there, or the path that breaks it. Whatever the blueprint leaves open goes on a list of questions for me. Do not guess.
When that list is empty, build from the blueprint and change nothing outside it. If the build has to differ, update the blueprint first and tell me why.
Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP
How to check it worked
- Follow every arrow with your finger. Does any path go round forever?
- Attack one rule. Ask: "Find me a way to break this."
- Read the tricky cases. Is one there that you had not thought of?
- After the build, do every item under "things to try".