Platformer
A playbook for 2D platformers — the run/jump controller "feel", level structure, hazards,
and goals. This is a compositional skill: it wires an engine movement skill, a tilemap
skill, and design skills into a working game. It does not re-teach physics or tilemaps;
it tells you what to build and how to make jumping feel good.
When to use
- Use when building a side-scrolling or single-screen platformer, a "Mario-like" /
"Celeste-like", or any game whose core verb is jump between surfaces.
- Use when a jump feels floaty, unresponsive, or "unfair" and you need feel fixes
(coyote time, jump buffering, variable height, corner correction).
When not to use: top-down movement with no gravity → use the engine movement skill
directly. 3D first-person traversal → fps-shooter. Grid/turn movement → roguelike.
For the raw kinematic body API, use godot-2d-movement (or your engine's controller skill).
Core loop
Observe a gap/hazard → commit to a jump or move → land safely (or die) → reach the next
checkpoint/goal. A platformer lives or dies on the moment-to-moment feel of that single
jump, repeated thousands of times. Tighten the controller first; everything else is content.
Must-have systems
- Run/jump controller — horizontal accel/decel, gravity, jump, with the feel aids below.
- Solid + one-way collision — ground, walls, and "jump-through" platforms.
- Level geometry — a tilemap or hand-placed colliders; the playable space.
- Hazards + death/respawn — spikes, pits, enemies; reset to the last checkpoint.
- Checkpoints / level goal — progress markers and a win condition (flag, door, exit).
- Camera — follows the player with a deadzone and look-ahead, clamped to level bounds.
- Juice — landing dust, squash/stretch, hit-stop, sound. Cheap, huge feel payoff.
Design knobs (make the jump feel right)
Tune these by outcome (height in tiles, time to apex in seconds), not by raw numbers.
| Knob |
Effect |
Sane starting point |
| Max jump height |
reach |
3–4 tiles |
| Time to apex |
"weight"/snappiness |
0.30–0.40 s |
| Fall gravity multiplier |
snappy, non-floaty fall |
1.5–2.0× rise gravity |
| Coyote time |
jump just after leaving a ledge |
0.08–0.12 s (~5–7 frames @60) |
| Jump buffer |
press just before landing still jumps |
0.10–0.15 s |
| Variable jump cut |
tap = short hop, hold = full |
cut upward velocity ×0.4–0.5 on release |
| Apex hang |
brief float at the top for air control |
reduce gravity ×0.5 near ` |
| Ground accel / friction |
responsiveness vs. ice |
reach top speed in 0.05–0.1 s |
| Corner correction |
nudge past a ledge clipped by 1–2 px |
nudge up to ~4 px sideways |
| Wall slide / wall jump |
controlled descent and kick-off |
wall grace, kick/steering lock, air-jump refresh policy; see refs §9 |
Derive gravity and jump velocity from the feel values rather than guessing — see Pattern 1.
Patterns
1. Solve jump physics from height + time (not magic numbers)
# Pseudocode. Pick the FEEL you want, then derive the physics. y-axis points DOWN.
# From kinematics: h = (g * t^2) / 2 and v0 = g * t.
JUMP_HEIGHT = 3.5 * TILE # how high, in world units
TIME_TO_APEX = 0.35 # seconds to reach the top
gravity = (2 * JUMP_HEIGHT) / (TIME_TO_APEX ** 2) # rising gravity
jump_velocity = -(2 * JUMP_HEIGHT) / TIME_TO_APEX # negative = upward
fall_gravity = gravity * 1.8 # heavier on the way down → less floaty
2. Coyote time + jump buffer + variable height (the feel core)
For wall or air jumps, replace this simple jump resolver with the unified resolver in refs §9;
keep variable-height and gravity integration only once per tick.
# Pseudocode in the per-frame update. dt = seconds since last frame.
# Timers count DOWN; refresh coyote while grounded, buffer on a fresh press.
if on_floor:
coyote_timer = COYOTE_TIME # 0.1
if jump_pressed_this_frame:
buffer_timer = JUMP_BUFFER # 0.12
coyote_timer -= dt
buffer_timer -= dt
# A jump is allowed if we pressed recently AND were grounded recently.
if buffer_timer > 0 and coyote_timer > 0:
velocity.y = jump_velocity
buffer_timer = 0
coyote_timer = 0 # consume both so we can't double-jump
# Variable height: releasing jump early while still rising cuts the arc short.
if jump_released_this_frame and velocity.y < 0:
velocity.y *= 0.45
# Asymmetric gravity: snappier fall than rise; clamp to a terminal speed.
g = fall_gravity if velocity.y > 0 else gravity
velocity.y = min(velocity.y + g * dt, MAX_FALL_SPEED)
3. One-way platforms
Solid from above, pass-through from below. Use the engine's flag rather than collision math:
Godot CollisionShape2D.one_way_collision (or the one-way option on a TileSet collision
polygon), Unity a PlatformEffector2D with Use One Way on a collider set to be used by the
effector, Phaser Arcade platform.body.checkCollision.down = false (plus left/right for thin
ledges). Let the player drop through by ignoring that platform for ~0.1–0.2 s when they hold
Down + Jump (refs §5).
Pitfalls / failure modes
- Per-frame movement not scaled by
dt → speed changes with frame rate. Every velocity
integration and timer must use dt. (See physics-tuning.)
- Jump height differs between machines → the jump runs on a variable render
dt. Simple
per-step integration lands a few percent short of the designed height, by a different amount
at each frame rate. Run the controller on the fixed physics tick (Godot _physics_process,
Unity FixedUpdate) or use the half-step update in refs §1.
- Player is flung off or doubles speed leaving a moving platform → platform velocity added
twice. Godot's
CharacterBody2D already carries the body and adds the platform's velocity on
leave (platform_on_leave); don't add it again in script (refs §6).
- Floaty jumps → symmetric gravity. Make fall gravity heavier than rise gravity.
- "The jump didn't register" → no input buffering. Buffer presses for ~0.1 s before landing.
- "I fell off and couldn't jump" → no coyote time. Allow a jump for ~0.1 s after leaving ground.
- Wall jump overrides a ground jump or consumes the double jump → resolve one buffered
press in ground/coyote → wall → air order, with an explicit air-jump refresh policy (refs §9).
- Sticking to walls / catching on tile seams → use a single capsule/box collider, not
per-tile colliders, and add corner correction.
- Tunneling through floors at high speed → enable continuous collision / smaller fixed
timestep for fast bodies (see
physics-tuning).
- Camera snaps and induces nausea → smooth/lerp the follow, add a deadzone, clamp to bounds.
- Difficulty wall from bad teaching → introduce one mechanic per area before combining them.
Composition (build it from these skills)
- Controller body:
godot-2d-movement (Godot CharacterBody2D); for other engines use
the engine core + physics skill (unity-physics, phaser-arcade-physics, pygame-core).
- Levels:
godot-tilemap / unity-tilemap-2d for geometry; level-design for layout,
pacing, and teaching order.
- Feel/physics:
physics-tuning for timestep, CCD, and stability.
- Input:
input-systems for buffering, rebinding, and gamepad support.
- Polish:
audio-design for SFX/music; the engine animation skill for squash/stretch.
- Process:
prototype-fast to greybox the controller before building content.
References
- For jump math derivation, wall slide/jump, a full feel-tuning table, corner correction, moving/one-way
platforms, and camera follow, read
references/feel-tuning.md.
1---2name: platformer3description: >4 Build a 2D platformer: run/jump control with coyote time, jump buffering, and variable jump5 height, wall slide and wall jump, plus tiled levels and hazards. Use for a platformer or6 Mario/Celeste-like, or tuning jump feel.7metadata:8 source: https://skillmd.com/skills/junmystery/platformer9---1011# Platformer1213A playbook for 2D platformers — the run/jump controller "feel", level structure, hazards,14and goals. This is a **compositional** skill: it wires an engine movement skill, a tilemap15skill, and design skills into a working game. It does **not** re-teach physics or tilemaps;16it tells you what to build and how to make jumping feel good.1718## When to use1920- Use when building a side-scrolling or single-screen platformer, a "Mario-like" /21 "Celeste-like", or any game whose core verb is **jump between surfaces**.22- Use when a jump feels floaty, unresponsive, or "unfair" and you need feel fixes23 (coyote time, jump buffering, variable height, corner correction).2425**When *not* to use:** top-down movement with no gravity → use the engine movement skill26directly. 3D first-person traversal → `fps-shooter`. Grid/turn movement → `roguelike`.27For the raw kinematic body API, use `godot-2d-movement` (or your engine's controller skill).2829## Core loop3031**Observe a gap/hazard → commit to a jump or move → land safely (or die) → reach the next32checkpoint/goal.** A platformer lives or dies on the *moment-to-moment* feel of that single33jump, repeated thousands of times. Tighten the controller first; everything else is content.3435## Must-have systems36371. **Run/jump controller** — horizontal accel/decel, gravity, jump, with the feel aids below.382. **Solid + one-way collision** — ground, walls, and "jump-through" platforms.393. **Level geometry** — a tilemap or hand-placed colliders; the playable space.404. **Hazards + death/respawn** — spikes, pits, enemies; reset to the last checkpoint.415. **Checkpoints / level goal** — progress markers and a win condition (flag, door, exit).426. **Camera** — follows the player with a deadzone and look-ahead, clamped to level bounds.437. **Juice** — landing dust, squash/stretch, hit-stop, sound. Cheap, huge feel payoff.4445## Design knobs (make the jump feel right)4647Tune these by **outcome** (height in tiles, time to apex in seconds), not by raw numbers.4849| Knob | Effect | Sane starting point |50|------|--------|---------------------|51| Max jump height | reach | 3–4 tiles |52| Time to apex | "weight"/snappiness | 0.30–0.40 s |53| Fall gravity multiplier | snappy, non-floaty fall | 1.5–2.0× rise gravity |54| Coyote time | jump just after leaving a ledge | 0.08–0.12 s (~5–7 frames @60) |55| Jump buffer | press just before landing still jumps | 0.10–0.15 s |56| Variable jump cut | tap = short hop, hold = full | cut upward velocity ×0.4–0.5 on release |57| Apex hang | brief float at the top for air control | reduce gravity ×0.5 near `|vy|`<threshold |58| Ground accel / friction | responsiveness vs. ice | reach top speed in 0.05–0.1 s |59| Corner correction | nudge past a ledge clipped by 1–2 px | nudge up to ~4 px sideways |60| Wall slide / wall jump | controlled descent and kick-off | wall grace, kick/steering lock, air-jump refresh policy; see refs §9 |6162Derive gravity and jump velocity from the *feel* values rather than guessing — see Pattern 1.6364## Patterns6566### 1. Solve jump physics from height + time (not magic numbers)6768```python69# Pseudocode. Pick the FEEL you want, then derive the physics. y-axis points DOWN.70# From kinematics: h = (g * t^2) / 2 and v0 = g * t.71JUMP_HEIGHT = 3.5 * TILE # how high, in world units72TIME_TO_APEX = 0.35 # seconds to reach the top7374gravity = (2 * JUMP_HEIGHT) / (TIME_TO_APEX ** 2) # rising gravity75jump_velocity = -(2 * JUMP_HEIGHT) / TIME_TO_APEX # negative = upward76fall_gravity = gravity * 1.8 # heavier on the way down → less floaty77```7879### 2. Coyote time + jump buffer + variable height (the feel core)8081For wall or air jumps, replace this simple jump resolver with the unified resolver in refs §9;82keep variable-height and gravity integration only once per tick.8384```python85# Pseudocode in the per-frame update. dt = seconds since last frame.86# Timers count DOWN; refresh coyote while grounded, buffer on a fresh press.87if on_floor:88 coyote_timer = COYOTE_TIME # 0.189if jump_pressed_this_frame:90 buffer_timer = JUMP_BUFFER # 0.1291coyote_timer -= dt92buffer_timer -= dt9394# A jump is allowed if we pressed recently AND were grounded recently.95if buffer_timer > 0 and coyote_timer > 0:96 velocity.y = jump_velocity97 buffer_timer = 098 coyote_timer = 0 # consume both so we can't double-jump99100# Variable height: releasing jump early while still rising cuts the arc short.101if jump_released_this_frame and velocity.y < 0:102 velocity.y *= 0.45103104# Asymmetric gravity: snappier fall than rise; clamp to a terminal speed.105g = fall_gravity if velocity.y > 0 else gravity106velocity.y = min(velocity.y + g * dt, MAX_FALL_SPEED)107```108109### 3. One-way platforms110111Solid from above, pass-through from below. Use the engine's flag rather than collision math:112Godot `CollisionShape2D.one_way_collision` (or the one-way option on a TileSet collision113polygon), Unity a `PlatformEffector2D` with **Use One Way** on a collider set to be used by the114effector, Phaser Arcade `platform.body.checkCollision.down = false` (plus `left`/`right` for thin115ledges). Let the player **drop through** by ignoring that platform for ~0.1–0.2 s when they hold116Down + Jump (refs §5).117118## Pitfalls / failure modes119120- **Per-frame movement not scaled by `dt`** → speed changes with frame rate. Every velocity121 integration and timer must use `dt`. (See `physics-tuning`.)122- **Jump height differs between machines** → the jump runs on a variable render `dt`. Simple123 per-step integration lands a few percent short of the designed height, by a different amount124 at each frame rate. Run the controller on the fixed physics tick (Godot `_physics_process`,125 Unity `FixedUpdate`) or use the half-step update in refs §1.126- **Player is flung off or doubles speed leaving a moving platform** → platform velocity added127 twice. Godot's `CharacterBody2D` already carries the body and adds the platform's velocity on128 leave (`platform_on_leave`); don't add it again in script (refs §6).129- **Floaty jumps** → symmetric gravity. Make fall gravity heavier than rise gravity.130- **"The jump didn't register"** → no input buffering. Buffer presses for ~0.1 s before landing.131- **"I fell off and couldn't jump"** → no coyote time. Allow a jump for ~0.1 s after leaving ground.132- **Wall jump overrides a ground jump or consumes the double jump** → resolve one buffered133 press in ground/coyote → wall → air order, with an explicit air-jump refresh policy (refs §9).134- **Sticking to walls / catching on tile seams** → use a single capsule/box collider, not135 per-tile colliders, and add corner correction.136- **Tunneling through floors at high speed** → enable continuous collision / smaller fixed137 timestep for fast bodies (see `physics-tuning`).138- **Camera snaps and induces nausea** → smooth/lerp the follow, add a deadzone, clamp to bounds.139- **Difficulty wall from bad teaching** → introduce one mechanic per area before combining them.140141## Composition (build it from these skills)142143- **Controller body:** `godot-2d-movement` (Godot `CharacterBody2D`); for other engines use144 the engine core + physics skill (`unity-physics`, `phaser-arcade-physics`, `pygame-core`).145- **Levels:** `godot-tilemap` / `unity-tilemap-2d` for geometry; `level-design` for layout,146 pacing, and teaching order.147- **Feel/physics:** `physics-tuning` for timestep, CCD, and stability.148- **Input:** `input-systems` for buffering, rebinding, and gamepad support.149- **Polish:** `audio-design` for SFX/music; the engine animation skill for squash/stretch.150- **Process:** `prototype-fast` to greybox the controller before building content.151152## References153154- For jump math derivation, wall slide/jump, a full feel-tuning table, corner correction, moving/one-way155 platforms, and camera follow, read `references/feel-tuning.md`.