Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/genres/platformer

platformer

Verified

Designs 2D platformers in any engine: jump feel (coyote time, jump buffering, variable height, fall gravity, corner correction), wall jumps, hazards, checkpoints and one-way platforms. Use for a Mario- or Celeste-like, or a jump that feels floaty or laggy. Pair with the engine skill (`godot-2d-movement`, `phaser-arcade-physics`). Not for generic input buffering (`input-systems`) or juice (`game-feel`).

Platformer

Owns how the jump feels and how levels are built around it. Numbers are engine-neutral, in tiles and seconds, so they survive a change of tile size or engine. The engine's movement skill supplies the body API (godot-2d-movement, unity-physics, phaser-arcade-physics).

When to use

  • Building a side-view game whose core verb is jumping between surfaces.
  • Fixing feel: "floaty", "heavy", "the jump didn't register", "I fell off and couldn't jump", "I bonk on corners", short hops that are too tall or too short.

When not to use: top-down movement without gravity (engine movement skill), 3D traversal (fps-shooter or the engine 3D skill), grid or turn-based movement (roguelike, puzzle).

Workflow

  1. Read the controller first. Find where velocity is integrated and at what rate: Godot _physics_process (60 Hz default), Unity FixedUpdate (0.02 s = 50 Hz default), Phaser Arcade (fixedStep on by default). Note the tile size, the y direction and the current constants. Ask which game the feel should resemble if the user has not said; "Mario-like" (momentum, heavy fall) and "Celeste-like" (instant, precise) need different targets.
  2. Pick targets from the table below, in tiles and seconds.
  3. Derive the constants with the calculator (path relative to this skill folder): python3 scripts/jump_tuner.py --height 3.5 --apex-time 0.35 --tile 16 --tick 60 --run-speed 8. It prints rise and fall gravity and launch velocity, simulates the jump at the project's tick, and warns about apex error from the integrator, grace windows that lose a tick, tap-hop ratio and tunnelling. Add --json for machine-readable output.
  4. Implement the feel core (Pattern 1) in this order: buffer, coyote, variable height, apex hang, fall cap, then corner correction. Run it on the fixed tick.
  5. Size the level to the measured reach. Critical-path platforms sit at least half a tile below the reached apex and gaps at least one tile shorter than the gap reach the tool prints. Optional routes may use the full reach.
  6. Check it. Add a debug switch that writes t,y for every physics tick of one jump (start on the tick the jump fires) to a CSV, run the scene (headless where the engine allows: godot --headless), then run python3 scripts/jump_tuner.py <same targets> --log jump.csv. Exit 1 means the measured apex height or time to apex is off by more than 5%. Then script these edge cases as tests and report what each one did: press 1 tick before landing, press N ticks after walking off a ledge (N = coyote ticks, then N + 1), tap versus hold, and jump into a ceiling corner 2 px off the edge.

Feel targets

Starting points. The Celeste column comes from its published Player.cs (8 px tiles, 60 Hz); use it as a "precise and snappy" reference, not as the only right answer.

KnobStart hereRangeCeleste
Full jump height3.5 tiles2-5about 3.5 tiles (28 px)
Time to apex0.35 s0.25-0.45about 0.37 s
Full airtime on flat ground0.6-0.7 s0.5-0.9about 0.68 s
Tap hop30% of full15-60%about 20%
Fall gravity1.8 x rise1.3-2.5same as rise, but terminal speed capped low
Terminal fall speed18-25 tiles/skeep under half a tile per tick20 tiles/s, 30 with fast-fall
Apex hanghalf gravity while held and vertical speed under ~40% of launch speed0.4-0.6 xhalf gravity under 40 of 105 px/s
Coyote time0.1 s0.06-0.150.1 s
Jump buffer0.1-0.15 s0.05-0.2not in the published file
Ground accelerationtop speed in 0.05-0.1 sinstant to 0.2 s0.09 s
Air control0.65 x ground accel0.5-1.00.65 x
Ceiling corner correctionup to half a tile sideways1/4-1/2 tile4 px
Wall-jump steering lock0.15 s0.1-0.20.16 s

Floatiness usually comes from a long apex hang, a low terminal speed or a long time to apex, not only from symmetric gravity. Change one knob at a time and re-run the calculator.

Pattern 1: the feel core

Count grace windows in whole ticks at the fixed rate. A float countdown such as timer -= dt; if timer > 0 silently loses a tick at some rates (0.1 s at 50 Hz gives 4 ticks, not 5), so the same build feels different in Unity and Godot. Tick stamps avoid that and also let Unity's Update record a press for FixedUpdate to consume.

# Pseudocode at the fixed tick. y points DOWN. Constants come from jump_tuner.py.
COYOTE_TICKS = round(COYOTE_TIME * TICK_RATE)     # 0.1 s at 60 Hz -> 6
BUFFER_TICKS = round(JUMP_BUFFER * TICK_RATE)     # 0.12 s at 60 Hz -> 7
NEVER = -10**9                                     # initial value of both stamps

tick += 1
if on_floor and velocity.y >= 0:
    last_ground_tick = tick                        # refresh only while standing, not rising
if jump_pressed_this_tick:
    last_press_tick = tick

if tick - last_press_tick <= BUFFER_TICKS and tick - last_ground_tick <= COYOTE_TICKS:
    velocity.y = JUMP_VELOCITY                     # negative = up
    last_press_tick = last_ground_tick = NEVER     # consume both: no second jump from coyote
    if not jump_held:                              # buffered press already released: short hop
        velocity.y *= JUMP_CUT

if jump_released_this_tick and velocity.y < 0:
    velocity.y *= JUMP_CUT                         # 0.4-0.6; only while rising

g = FALL_GRAVITY if velocity.y > 0 else RISE_GRAVITY
if jump_held and abs(velocity.y) < APEX_THRESHOLD:
    g *= APEX_HANG                                 # 0.5
velocity.y = min(velocity.y + g * dt, MAX_FALL_SPEED)
# then move and collide once; on a ceiling hit try corner correction (refs §4), else zero vy

Variable height has three common models. Use the release cut above by default: it is one line and gives a fixed minimum hop. For precision platformers use the Celeste model instead: hold the launch speed for up to ~0.2 s while the button is held, then let gravity act; release ends the hold. The third model raises gravity (2-3 x) while rising with the button up; it gives the smoothest arc but is the hardest to reason about. Pick one; mixing two doubles the effect.

Engine pointers

  • Godot 4: run the controller in _physics_process; Input.is_action_just_pressed() reports presses per physics tick, so it is safe there. is_on_floor() is valid after move_and_slide(). Body API, slopes and moving platforms: godot-2d-movement.
  • Unity 6: Rigidbody2D.linearVelocity (velocity is obsolete). Record the press in Update (set a flag or the tick number) and consume it in FixedUpdate; polling a "pressed this frame" call inside FixedUpdate can miss or repeat presses. y points up, so flip the signs above. One-way platforms: PlatformEffector2D.
  • Phaser 4 Arcade: body.blocked.down or body.onFloor(), Phaser.Input.Keyboard.JustDown in update; y points down. See phaser-arcade-physics.

Gotchas

  • Jump height changes with frame rate → integration runs on a variable dt. The usual "add gravity, then move" step peaks short by about v0 * dt / 2 (about 5% of a 3.5-tile jump at 60 Hz, more at 30 Hz). Run on the fixed tick and design to the simulated apex, or use the half-step update (refs §1, --integrator half).
  • Double jump inside the coyote window → coyote was not zeroed when the jump fired, or it refreshes while still rising off the floor on the first tick. Consume both timers on jump and refresh coyote only when velocity.y >= 0.
  • Buffered jump is always full height → the release happened before landing, so the release edge never reaches the rising jump. Check the held state when the buffered jump fires.
  • Head-bonk keeps the jump sustained → a ceiling hit must zero upward speed and end the variable-height hold (Celeste allows 0.05 s of grace before ending it).
  • Player is flung off or doubles speed leaving a moving platform → platform velocity added twice. Godot's CharacterBody2D already adds it on leave (platform_on_leave); Unity's CharacterController does not carry riders at all (refs §6).
  • Wall jump eats the ground jump or the double jump → resolve one buffered press in ground/coyote, then wall, then air order, with an explicit air-jump refresh rule (refs §9).
  • Snagging on tile seams → per-tile box colliders. Merge level collision into larger shapes and use one capsule or rounded box for the player.
  • Falling through thin floors → terminal speed moves more than half a tile per tick. The calculator warns; cap fall speed or enable continuous collision (physics-tuning).
  • Presses lost in Unity → input polled in FixedUpdate. Latch it in Update.

References

  • references/feel-tuning.md: read when you need the jump math derivation and half-step integrator, apex hang and fast-fall code, ceiling corner correction, one-way drop-through, moving-platform behaviour per engine, or the full wall slide and wall jump resolver.
  • scripts/jump_tuner.py --help: every option of the calculator and the log check.

Related: level-design (teaching order, pacing), camera-systems (platformer camera deadzone and look-ahead), game-feel (landing dust, squash, hit-stop), input-systems (rebinding, gamepad, generic input buffers).

Version notes

Last verified: 2026-11-11.

  • Celeste numbers: Source/Player/Player.cs in https://github.com/NoelFB/Celeste (MIT, file released 2018): JumpGraceTime 0.1, JumpSpeed -105, VarJumpTime 0.2, Gravity 900, HalfGravThreshold 40, MaxFall 160, FastMaxFall 240, MaxRun 90, RunAccel 1000, AirMult 0.65, UpwardCornerCorrection 4, WallJumpForceTime 0.16, CeilingVarJumpGrace 0.05. Height, apex time and tap hop were computed from these at 60 Hz.
  • Godot 4.7.2: Input.is_action_just_pressed documents per-physics-tick behaviour (doc/classes/Input.xml).
  • Unity 6.3 LTS: Rigidbody2D.linearVelocity; default fixed timestep 0.02 s (https://docs.unity.com/en-us/engine/6000.6/manual/physics-section/physics-overview/physics-optimization/cpu/frequency).
  • Phaser 4.2.1: Arcade fixedStep defaults to true; Keyboard.JustDown and body.onFloor() exist in the shipped typings.
  • Jump-from-height-and-time method: Kyle Pittman, "Math for Game Programmers: Building a Better Jump", GDC 2016.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall