Game feature loop

A game can pass every test and still be unplayable: the input is never mapped, the node is not in the scene, the animation fights the movement code. An agent that stacks three features before running the game then cannot tell which one broke it. A screenshot does not settle it either, because a still frame shows layout, not behavior. This playbook builds one mechanic at a time and treats "done" as behavior observed in the running game.

Gates that apply to every step

Step 1: detect the engine and version

Do not assume. Look for the project fingerprint, open the file, and confirm it is a real project root and not a vendored sample or a dependency. Read the version from the project's own version source before choosing any API, because engine APIs differ between major versions and tutorials mix them.

The fingerprints, version sources, and ambiguity rules are in engine-fingerprints. If two engines match (a monorepo), pick by the directory the request is about. If none match and the user named no engine, ask. Never load engine knowledge on a guess.

Then find out how to run the game and drive it. See step 4 for the capabilities to look for. Do this now, not after the code is written.

Step 2: plan one mechanic

Write the plan before the code. Keep it to a few lines:

Mechanic:    one verb the player does (double jump, dash, pick up key)
Pass check:  the observable change that proves it, with numbers
             (example: vertical velocity goes from 0 to a negative value within 3 frames of the jump input)
Input:       the action a player would trigger, by its input-map name
State read:  the exact values to read before and after
Out of scope: what this step will not touch

Rules that keep the plan small:

• If the request holds several verbs, split it and do the first. List the rest as later steps.
• Pick a pass check that a script can read: a position, a velocity, a health value, a state name, a count of spawned objects. If you cannot name one, the mechanic is not specified enough. Ask.
• Check the art bible and existing assets. Placeholder shapes are fine for a mechanic. Paid generation is a separate ask.
• For a prototype whose only question is "is this fun", keep the same loop but allow hard-coded values and one file. The proof step still applies. For timeboxing and keep or kill criteria, see prototype-fast in the community gamedev skills.

Step 3: build

• Keep scripts small and single-purpose. About 300 lines is a starting limit. Split before a file passes it, not after.
• Give players, enemies, and anything with modes a state machine from the start (idle, move, jump, attack, hurt). Add behavior as states or components, not as flags inside one big update function. Retrofitting states later costs more than starting with them.
• Read input through the engine's named actions or bindings, never raw key codes. A missing binding is the most common reason a built mechanic does nothing.
• Put tunable numbers (speed, jump height, cooldown) in exported fields or data, not in the middle of code. The feel pass edits them.
• Split pure logic from engine calls so the logic can be tested without launching the game. Use the tdd playbook for that part only.
• Use the engine's own editing path for scenes and assets when one exists (editor API, CLI, bridge). Hand-editing scene text is a last resort. If you must, keep ids consistent and run the engine's import or validate step afterwards.
• Run the engine's static check (compile, script parse, lint) after each change and fix errors before running the game.

Step 4: run the game

Launch the real game or scene, not only a unit test runner. Look for these capabilities, and use whatever the project and your tools offer:

If a capability is missing, add the cheapest substitute: a log line or on-screen text that prints the value you need, a test scene that plays a scripted input sequence, or an automated play-mode test. Engine notes lists where to find each in the main engines.

Step 5: prove the behavior

Reading state before and after a simulated input is the proof. Do it in this order:

1. Read the plan's state values and record them (before).
2. Send the plan's input through the player path (an input action or key event), not by calling the function or setting the value yourself. Hold it long enough for several frames or ticks.
3. Wait a fixed number of frames or a fixed time, then read the same values (after). Reading in the same frame as the input reads the old state.
4. Compare with the plan's pass check, with a tolerance. Quote both readings in your report.
5. Run the negative case: no input gives no change, and releasing the input stops the effect.
6. Read the logs for errors and warnings from the run. A new warning is a finding.
7. Capture a frame only for visual claims (sprite visible, UI placed), and only after the state checks pass.

If the numbers do not match, that is a failed attempt, so count it against the two-attempt limit. Fix one thing, run the whole proof again, and compare.

If the game cannot be run here (no display, no editor, no engine installed), say so, list what is therefore unproven, and do not call the feature done. A passing unit test does not replace this step.

Step 6: commit

Commit one mechanic per commit, after the proof passes. Commit the engine's sidecar files that the project tracks, and do not commit its cache folder (for Godot that is .godot/, see the Godot version control page). Follow the project's commit conventions. Put the pass check and the before and after readings in the message or the pull request, because they are the evidence.

For the general rule on completion claims, see verification-before-completion.

Step 7: game-feel pass

Do this as a separate pass, only after the mechanic is proven and committed. Never add feedback to a mechanic that is broken or unproven, because the effects hide the bug and the numbers you tuned against will move when it is fixed.

Weight feedback by how much the event matters. Hits, deaths, and big pickups get the most. Routine actions such as walking or a common pickup get little or none, because constant effects become noise and tire the player. Layer small effects (sound, particles, camera shake, a short freeze on impact, a flash, a tween on the target) for heavy events and use one or two for light ones. Do not cover information the player needs, and give players a way to reduce shake and flashing.

Every effect is its own small change: add it, run the game, check that it fires, returns to rest, and does not block input, then move on. The tier table, the starting values (all of them defaults to tune by playing, not rules), and the pitfalls are in game-feel-pass.

Engine notes

These are installed by the user, not by this skill. Read an unfamiliar package before installing it. Unreal's plugin gives the agent broad control of a running editor, so its README asks you to treat it like running code from an assistant.

Pitfalls

• Reading "after" state in the same frame as the input, then deciding the mechanic is broken (or fine).
• Setting the value directly or calling the handler, which skips the input binding that was the real bug.
• Judging a mechanic from a screenshot. A frame can look right while the object does not move.
• Adding shake, particles, and sound while the mechanic is still being debugged.
• Building the second mechanic on top of an unproven first one, then debugging both at once.
• Hand-writing engine API calls from memory of an older major version. Check the version from step 1 and the engine docs.

Reference files