使用方法
- 复制安装命令,在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill platformer开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。
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
- 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.
- Pick targets from the table below, in tiles and seconds.
- 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.
- 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.
- 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.
- Check it. Add a debug switch that writes
t,yfor 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.
| Knob | Start here | Range | Celeste |
|---|---|---|---|
| Full jump height | 3.5 tiles | 2-5 | about 3.5 tiles (28 px) |
| Time to apex | 0.35 s | 0.25-0.45 | about 0.37 s |
| Full airtime on flat ground | 0.6-0.7 s | 0.5-0.9 | about 0.68 s |
| Tap hop | 30% of full | 15-60% | about 20% |
| Fall gravity | 1.8 x rise | 1.3-2.5 | same as rise, but terminal speed capped low |
| Terminal fall speed | 18-25 tiles/s | keep under half a tile per tick | 20 tiles/s, 30 with fast-fall |
| Apex hang | half gravity while held and vertical speed under ~40% of launch speed | 0.4-0.6 x | half gravity under 40 of 105 px/s |
| Coyote time | 0.1 s | 0.06-0.15 | 0.1 s |
| Jump buffer | 0.1-0.15 s | 0.05-0.2 | not in the published file |
| Ground acceleration | top speed in 0.05-0.1 s | instant to 0.2 s | 0.09 s |
| Air control | 0.65 x ground accel | 0.5-1.0 | 0.65 x |
| Ceiling corner correction | up to half a tile sideways | 1/4-1/2 tile | 4 px |
| Wall-jump steering lock | 0.15 s | 0.1-0.2 | 0.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 vyVariable 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(velocityis 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.downorbody.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 inUpdate.
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.csin 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_presseddocuments 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
fixedStepdefaults to true;Keyboard.JustDownandbody.onFloor()
exist in the shipped typings.
- Jump-from-height-and-time method: Kyle Pittman, "Math for Game Programmers: Building a Better
Jump", GDC 2016.