tick-mass

# Tick Mass

Most "broken physics" is a mismatched clock, a mass that nobody tuned, or a layer that only looks one way. Fix the feel of the integrator first. The engine is rarely the bug.

Inspired by gamedev-skills/awesome-gamedev-agent-skills physics-tuning (Apache-2.0). Original Grok remake. Complements stick-map (coyote/buffer live there; this skill does not own jump windows), juice-pass (shake/hit pop on an action that already fires), pawn-mind (intent/path/steer, not the integrator), lens-rig, hud-stack, bus-mix, room-flow, gold-sink, save-slot, seed-map, branch-talk, godot-teacher (engine body/collider APIs). Not godot-teacher.

Read `references/phys-rules.md` before you design. Fill the three templates under `templates/`.

## When to use

- Motion jitters, stutters, or looks frame-rate dependent
- Fast objects punch through thin walls (tunneling)
- Stacks explode, joints stretch, sleeping never kicks in
- Feel is floaty or "too heavy" and they keep turning the mass knob
- They ask about FixedUpdate, a fixed Hz tick, CCD, or collision layers/masks
- Need a two-way layer matrix so player, world, projectiles, and pickups actually meet

## When NOT to use

- Godot/Unity physics node or component walkthroughs, collision callbacks, RigidBody inspector tours → use godot-teacher
- Coyote time, jump buffer, rebind, deadzone → use stick-map (those windows live on the input layer; this skill does not own them)
- Screen shake, hit-stop, juice on an action that already fires → use juice-pass
- FSM / behavior tree / A* / steering intent → use pawn-mind
- Level blockout, critical path, room beats → use room-flow
- Aimbots, wallhacks, physics-engine exploits as cheats, ESP, malware

## Inputs

- Genre slice (platformer, top-down, 3D rigid, ragdoll-lite, projectile-heavy)
- Pain: jitter, tunneling, exploding stacks, floaty fall, FPS-dependent motion, missed collisions
- Target physics Hz (default ~50–60) and whether the engine already interpolates visuals
- Bodies that matter (player, crates, bullets, platforms) plus the thinnest wall thickness
- Layer names they care about (world, player, enemy, projectile, pickup, trigger)

## Procedure

1. Read `references/phys-rules.md`. Refuse aimbots, wallhacks, physics exploits as cheats, ESP, malware, Godot/Unity API dumps, and copied GDScript/C#. Coyote/buffer belong on stick-map. Hit pop belongs on juice-pass. Intent/path belongs on pawn-mind.
2. Lock a **fixed timestep**. Simulate at a constant rate (~50–60 Hz). Apply forces in the physics callback with *that* `dt`, not the render frame's `dt`. Write Hz, hitch clamp, and max steps per frame on `templates/loop-card.md`.
3. Draw interpolated. Visuals lerp between the previous physics pose and the current one, or you turn on the engine's built-in interpolation. Prefer the built-in before you hand-roll.
4. Clamp a giant frame `dt` and cap how many physics steps run in one render frame. After a hitch, extra leftover time is dropped so the sim cannot spiral.
5. Treat **mass as relative collision weight**. It does not change fall speed. Use drag and `gravity_scale` for how it *feels* to move and fall. Bounce and friction come from contact materials, not from cranking mass.
6. Stop tunneling: CCD on small/fast bodies, plus a speed cap so distance-per-step stays under the thinnest wall. If it still punches through, thicken the wall or raise Hz. Write those numbers on `templates/body-tune.md`.
7. Keep stacks and joints honest: modest mass ratios (about 1:10, not 1:1000), extra solver iterations on the pile, sleeping once things rest. Huge ratio + default iterations is how a crate tower detonates.
8. Layers: a body is **on** its layer and **scans** its mask. A pair usually needs *both* directions configured. Fill a two-way matrix on the body-tune card (player vs world, projectile vs enemy, pickup vs player, and so on).
9. Fill `templates/verify-phys.md`. Run low FPS and high FPS. Fire fast objects at thin walls. Shove a stack. Confirm sleep. Flip the layer pair both ways.
10. Tiny original engine-neutral notes only if useful. No vendor API dumps. No GDScript or C# copied from any source.

## Output format

- Loop card (fixed Hz, interpolation, hitch clamp / max steps)
- Body-tune card (relative mass, drag, gravity_scale, restitution/friction, CCD, speed cap, layer matrix)
- Verify-phys checklist (low/high FPS, thin walls, stacks, sleep, both-direction layers)
- One line: physics-feel worksheet; not a Godot tutor or a cheat overlay

## Safety

- Follow `references/phys-rules.md` with no exceptions.
- Gaming design only. Engine-neutral notes. Not a Godot tutor.
- No cheat overlays, aimbots, wallhacks, physics exploits for cheating, malware.
- No CSAM in mock content.
- No copied GDScript/C# from any source. Tiny original pseudocode only.

## Stop conditions

- Three templates delivered, or refused for cheats / godot-teacher API tours / coyote-buffer (stick-map) / hit juice (juice-pass) / AI path (pawn-mind) / room blockout (room-flow)