Debugging game feel skill for AI agents

debugging-game-feel is a skill from the Summer skill library: a guide your AI agent reads when the task matches, so it builds the good version on the first try. Debug features that work but feel wrong: floaty jumps, mushy combat, sluggish camera.


Status	Stable
Domains	Agent workflow, Gameplay
Version	`1.0.3`
Engine version	`>=4.6`
Recommended set	No, installed by `--all` or by name

When your agent uses it

A gameplay feature works correctly but feels wrong — floaty jumps, mushy combat, sluggish camera, weightless impacts
Tuning jump height, gravity, camera lag, hit-stop, or impact feedback until controls feel right

Install

summer setup installs every skill for your agent. To add only this one:

npx -y summer-engine@latest skills install debugging-game-feel --agent claude-code

Swap claude-code for your agent, such as codex or cursor. See Skills for every option.

The skill

Overview

“Works but feels wrong” is its own debugging discipline. The code is correct. No diagnostic flags it. The unit tests pass. And yet the jump is floaty, the sword has no weight, the camera lags the player, the dash is unsatisfying. Core principle: Game-feel bugs are tuning bugs, not logic bugs. Treat them with discipline — isolate one variable, compare to a reference, measure what you can, feel what you can’t. This skill is for the diagnostic phase. The polish-and-juice layer (screen shake, hit-stop, particles, sound design) is game-feel — go there once you’ve identified WHICH variable is wrong.

When To Use

The user says: “feels floaty”, “feels mushy”, “feels off”, “feels sluggish”, “doesn’t feel right”, “lacks impact”, “lacks weight”, “doesn’t feel satisfying”.
The feature passes playtesting-a-feature (no errors, golden path runs) but still doesn’t feel right.
You’re tuning movement, combat, camera, or any interaction with frame-level timing.

When NOT To Use

The feature has a concrete reproducible bug — go to investigating-bugs.
The feature crashes or throws — go to debug.
The feature hasn’t been built yet — design it via brainstorming first.

The Iron Law

ONE VARIABLE AT A TIME. ALWAYS.

Game-feel debugging is the place where engineers most often violate this rule, because each variable is a small tweak. “Let me bump acceleration AND friction AND max speed all together” produces a result you cannot reason about. You learn nothing. The bug returns.

The Loop

  Anchor → Isolate → Tweak one variable → Compare → Decide → Repeat

1. Anchor: name the reference

Before touching any value, decide what “right” feels like. Game feel is subjective; without an anchor, you are debugging air. Two ways to anchor:

Anchor type	When to use	Example
Reference game footage	The user has a target in mind (Hollow Knight jumps, Dark Souls weight, Hades dashes)	“Match the Hollow Knight jump arc — peak in ~0.25s, fall ~0.35s, terminal velocity around frame 30”
Internal known-good	An older build / a sibling feature in the same game already feels right	”The pistol fires snappy. Make the rifle feel as snappy as the pistol minus the recovery frames.”

Write the anchor down in one sentence. If the user can’t articulate it, ask. “What game does this remind you of when it’s working?” is a fast way to extract the reference.

2. Isolate: name the suspect variable

Game-feel bugs almost always live in one of a small set of axes. Pick the most likely one first.

Domain	Common suspect variables
Jump	gravity, jump velocity, terminal velocity, coyote-time window, jump-buffer window, variable-jump cutoff, apex hang time
Run	acceleration, max speed, friction (ground vs air), deceleration on input release, turn-around speed
Combat hit	hit-stop duration (attacker), hit-stop duration (target), screen shake amplitude + duration, knockback velocity + decay, recovery frames
Camera	follow lag (lerp factor or spring stiffness), lookahead distance, deadzone size, snap-vs-smooth on direction change
Dash	distance, duration, ease curve, cooldown, i-frame window, end-lag
UI feedback	input-to-response frame count, tween duration, easing function, sound onset delay

If you cannot pick one suspect: state the top two, pick the one you think is most likely (say which), tweak it, see if it moved the feel. Do not tweak both.

3. Tweak one variable

Read the current value via summer_inspect_node or open the relevant .tres / .gd file.
Change ONE value. Save.
Trigger summer_play and walk the feature.
Ask: did the feel move toward or away from the anchor?

4. Compare

Two compare modes: Feel: subjective. The user (or you, if you have eyes on the screen) reports “warmer” or “colder.” This is fine. Most game-feel work is felt, not measured. Measure: objective. When the feel is ambiguous, drop down to frame counts — and take them yourself with a RunVerification probe rather than asking the user to eyeball anything. The probe presses the input, samples per frame, and hands back an array.

Question	Measurement
”Does the jump peak too fast?”	Probe: `press("jump")`, sample `player.velocity.y` every `process_frame`, count frames to the sign flip
”Is the camera too laggy?”	Probe: sample `camera.global_position - target.global_position` per frame while driving movement
”Is the input dead?”	Probe: report the frame input was injected and the frame the state machine changed; subtract
”Is the hit-stop too short?”	Probe: report frame at hit and frame at unfreeze

Sketch:

extends SummerProbeBase
func _ready() -> void:
    await super._ready()
    await get_tree().process_frame
    var p := get_tree().root.find_child("Player", true, false)
    var trace: Array = []
    await press("jump", 100)
    for i in 40:
        await get_tree().process_frame
        trace.append(p.velocity.y)
    report("vel_y_per_frame", trace)
    save_frame("apex")
    finish()

Send it with summer_batch ops:[{"op":"RunVerification","probe_source":"<the probe>","max_seconds":20}]. The point of measurement is to ground the conversation in numbers when “feels off” stops being useful. You do not need to measure most tweaks — only the ambiguous ones. The verdict on whether it now feels right stays with the user — that part is genuinely subjective, and it is the only part of this loop you hand over.

5. Decide

After the tweak:

Felt closer to the anchor → commit the change, move to the next suspect variable if the feel still isn’t right.
Felt further → revert the change, pick a different suspect variable.
No change in feel → revert the change, you tweaked the wrong variable.

Never leave a tweak in the codebase that you couldn’t tell did anything. It will compound with the next tweak and you will lose the thread.

The Compounding Tweaks Trap

The most common failure mode in game-feel work:

  Jump feels floaty.
  Bump gravity from 980 → 1200. Still floaty.
  Bump it to 1500. A bit better.
  Also reduce jump velocity from 500 → 450.
  Also tweak terminal velocity 1500 → 2000.
  Also add a 3-frame coyote window because why not.
  Now it feels... different. But the dash that used to feel great no longer does.
  Try to undo? You don't remember the starting point.

Antidote:

Note the starting values before you begin.
One variable at a time.
After every tweak, ask: anchor closer or farther? If unsure, revert.
Commit small revertible changes — one variable per commit during a feel-tuning session. Easy to bisect.

Feel Principles (Briefly)

Game feel rests on three small ideas. Most “feels wrong” bugs trace to one of these being undertuned:

Principle	What it means	What it looks like when broken
Anticipation	A small wind-up before a big action	Sword swings feel like they “appear” instead of being thrown
Follow-through	The action continues past the input	Player snaps to a stop on input release — feels robotic
Weight	Visible cost to changing direction or stopping	Player turns on a dime at full speed — feels weightless

These are diagnostic tools, not lecture material. When the user says “feels weightless,” your suspect-variable shortlist is: deceleration on input release, friction, turn-around speed, animation cross-fade time.

Red Flags — STOP

Red flag	Reality
Tweaking 2+ variables in one play session without reverting between	You will lose the signal.
”Let me just feel it out without an anchor”	You will tune in circles. Name the reference.
”The user said floaty so I’m jacking gravity"	"Floaty” can also mean weak air control, slow terminal velocity, or too-long apex hang. Confirm before tweaking.
Skipping the play step (“I’ll just bump the number and trust the feel”)	Game feel is felt, not predicted. Play every tweak.
Adding “while I’m here” tweaks to unrelated features	Game feel debugging is a focused activity. Stay on the one feature.
Going to `game-feel` before identifying the broken variable	Juice on top of a broken tuning makes the bug louder. Fix tuning first.
Spending >30 minutes on one variable without progress	The anchor is wrong, or the variable is wrong. Step back, re-anchor.

Rationalization Prevention

Excuse	Reality
”It’s subjective — I’ll just iterate fast”	Fast iteration without isolation is thrashing, not iteration.
”I know game feel, I don’t need an anchor”	Even pros anchor. Especially pros anchor.
”Two variables are coupled, I have to tune them together”	Then tune one, ship that delta, tune the other separately.
”The user can’t articulate the anchor"	"What game does this remind you of when it works?” — one question, anchor obtained.
”Adding juice will hide the bad tuning”	It won’t. It amplifies it.

When To Escalate

After diagnosis pins down which variable(s) are wrong, the tuning is done — but the feature may still want polish. Hand off to:

game-feel — for the screen-shake, hit-stop, particle, sound layer once tuning is locked.
debug — if mid-debug you discover an actual error (signal not firing, node freed) hiding under the feel issue.

investigating-bugs — for logical bugs with concrete repros, not feel.
playtesting-a-feature — the playtest discipline this skill plugs into.
debug — when the feel investigation surfaces an actual error.

From a shell

No Summer MCP tools in this session? Run each one as a command; when summer --version is missing or below 4.0, use npx -y summer-engine@latest in place of summer. Fields are flags in kebab-case (--scene-path res://main.tscn) or one --input '<json>', and summer ops describe <op> prints the exact input. The summer-cli skill has the rest.

In this skill	Command
`summer_batch`	`summer engine batch`
`summer_inspect_node`	`summer engine inspect-node`
`summer_play`	`summer engine play`

Source: library/skills/debugging-game-feel/SKILL.md, rendered from summer-engine@4.3.0 on npm.

​When your agent uses it

​Install

​The skill

​Overview

​When To Use

​When NOT To Use

​The Iron Law

​The Loop

​1. Anchor: name the reference

​2. Isolate: name the suspect variable

​3. Tweak one variable

​4. Compare

​5. Decide

​The Compounding Tweaks Trap

​Feel Principles (Briefly)

​Red Flags — STOP

​Rationalization Prevention

​When To Escalate

​Related skills

​From a shell