version: "1.0.1" name: debugging-game-feel description: "Debug features that work but feel wrong: floaty jumps, mushy combat, sluggish camera."

Debugging Game Feel

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:

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.

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.

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:

1. Note the starting values before you begin.
2. One variable at a time.
3. After every tweak, ask: anchor closer or farther? If unsure, revert.
4. 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:

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

Rationalization Prevention

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.

Related skills

• 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.

<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->

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.

<!-- /shell-commands -->