godot-genre-platformer

NEVER Do (Expert Anti-Patterns)

Physics & Movement Feel

• NEVER multiply velocity by delta before move_and_slide(); the method internalizes the timestep.
• NEVER skip Coyote Time (approx 0.1s); without this grace period, jumps will feel unresponsive when walking off ledges.
• NEVER ignore Jump Buffering (approx 0.15s); players expect to jump the instant they touch the ground if they pressed the button early.
• NEVER use a fixed jump height; strictly implement Variable Jump Height (cut velocity on release) for player expression.
• NEVER forget to scale gravity by delta before adding to velocity; gravity is an acceleration and must be frame-rate independent.
• NEVER rely on discrete collision for high-speed movement; strictly use CCD_MODE_CAST_RAY to prevent tunneling through geometry.
• NEVER use move_and_collide() for standard traversal; it lacks the slope/stair handling of move_and_slide().
• NEVER check coyote or buffer timers using exact equality (== 0.0); strictly use is_equal_approx() or >= 0.0.

Polish & Level Design

• NEVER use linear camera snapping; strictly use Camera Smoothing or lerp() to prevent motion sickness.
• NEVER skip Squash and Stretch on jump/land; movement feels weightless without these subtle visual "juice" cues.
• NEVER create Blind Jumps; strictly use camera look-ahead or zoom triggers to reveal landing zones.
• NEVER use individual Sprite2D nodes for level geometry; strictly use TileMapLayer for optimized collision and rendering.
• NEVER use complex/concave CollisionShape2D for the player; strictly favor primitive shapes (Capsule/Rectangle) for stability.

Architecture & Performance

• NEVER use CharacterBody2D for simple moving platforms; strictly use AnimatableBody2D and enable sync_to_physics.
• NEVER ignore platform_on_leave for descending platforms; use PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY to preserve jump impulse.
• NEVER disable recovery_as_collision on the player character; it is required for correct floor snapping reports.
• NEVER use the ! (NOT) operator in AnimationTree expressions; strictly use is_walking == false.
• NEVER use standard Strings for high-frequency state checks; strictly use StringName (e.g., &"jumping").
• NEVER load heavy level chunks synchronously; strictly use ResourceLoader.load_threaded_request() to prevent frame stutters.

---

Available Scripts

> MANDATORY: For movement feel, read the controller + modules — do not re-implement coyote/buffer/variable-jump inline.

Controllers (golden path)

• [advanced_platformer_controller.gd](scripts/advanced_platformer_controller.gd) — MANDATORY before any precision jump/run controller.
• [platformer_controller_2d.gd](scripts/platformer_controller_2d.gd) — Leaner CharacterBody2D baseline when the advanced stack is overkill.
• [player_ground_controller.gd](scripts/player_ground_controller.gd) — Floor constant speed + slope snap refinements.

Movement modules

• [coyote_timer.gd](scripts/coyote_timer.gd) — MANDATORY with jump feel work (or use the integrated advanced controller).
• [jump_buffer.gd](scripts/jump_buffer.gd) — MANDATORY with coyote for landing responsiveness.
• [variable_jump.gd](scripts/variable_jump.gd) — MANDATORY for release-cutoff height expression.
• [wall_slide_sensor.gd](scripts/wall_slide_sensor.gd) — Nodeless wall detection.
• [ledge_grab_sensor.gd](scripts/ledge_grab_sensor.gd) — Shape-query ledge grabs.
• [one_way_drop_handler.gd](scripts/one_way_drop_handler.gd) — MANDATORY before drop-through / one-way platform input.
• [custom_collision_slider.gd](scripts/custom_collision_slider.gd) — High-speed inter-frame slide response.

World / camera / polish

• [synchronized_platform.gd](scripts/synchronized_platform.gd) — AnimatableBody2D sync_to_physics platforms.
• [fast_projectile_ccd.gd](scripts/fast_projectile_ccd.gd) — CCD to stop tunneling.
• [platformer_animation_sync.gd](scripts/platformer_animation_sync.gd) — Boolean-safe AnimationTree sync.
• [platformer_camera.gd](scripts/platformer_camera.gd) — Look-ahead / smoothing (pair with godot-camera-systems).
• [game_feel_helper.gd](scripts/game_feel_helper.gd) — Tween squash/stretch on visual node (pivot at feet).
• [speed_trail.gd](scripts/speed_trail.gd) — GPUParticles trail toggle for dash/run juice.
• [checkpoint.gd](scripts/checkpoint.gd) — Area2D checkpoint id + SaveManager position hook.

---

Core Loop

Jump → Navigate Obstacles → Reach Goal → Next Level

Skill Chain

godot-project-foundations, godot-characterbody-2d, godot-input-handling, godot-2d-animation, godot-audio-systems, godot-tilemap-mastery, godot-camera-systems, godot-monte-carlo-balancer

---

Movement Feel — Decision Knobs (not tutorials)

> MANDATORY read: [advanced_platformer_controller.gd](scripts/advanced_platformer_controller.gd) plus [coyote_timer.gd](scripts/coyote_timer.gd) / [jump_buffer.gd](scripts/jump_buffer.gd) / [variable_jump.gd](scripts/variable_jump.gd). Copy those modules; do not paste coyote/buffer recipes here.

Tune only these knobs in project code after reading the scripts:

| Knob | Expert default / note |

|------|------------------------|

| Coyote window | ~0.1s — without it, ledge jumps feel broken |

| Jump buffer | ~0.15s — early press must land as jump |

| Variable jump | Cut upward velocity on release |

| Apex / fall gravity | Higher fall multiplier after apex = snappier landings |

| CCD | Enable cast-ray CCD for fast projectiles / dashes |

| Moving platforms | AnimatableBody2D + sync_to_physics; set platform_on_leave |

| One-ways | [one_way_drop_handler.gd](scripts/one_way_drop_handler.gd) — mask/layers, not ad-hoc disable |

Ground: instant direction response. Air: slightly reduced accel. Gravity scaled by delta; never velocity *= delta before move_and_slide().

---

Level Design Principles

The "Teaching Trilogy"

1. Introduction — safe learn → 2. Challenge — moderate risk → 3. Twist — combine / time pressure

Flow and Pacing

Easy → Easy → Medium → CHECKPOINT → Medium → Hard → CHECKPOINT → Boss

Camera

Use [platformer_camera.gd](scripts/platformer_camera.gd) / peer godot-camera-systems for look-ahead — never blind jumps.

---

Platformer Sub-Genres

• Precision (Celeste / Super Meat Boy) — instant respawn, tight controls, frequent checkpoints
• Collectathon — hub worlds, ability unlocks, backtracking
• Puzzle — slow pacing, environmental physics
• Metroidvania — route to godot-genre-metroidvania

---

Common Pitfalls

| Pitfall | Solution |

|---------|----------|

| Floaty jumps | Increase fall gravity after apex |

| Imprecise landings | Coyote + buffer modules + land juice |

| Unfair deaths | Hazards telegraphed before contact |

| Blind jumps | Look-ahead camera / zoom triggers |

| Boring mid-game | New mechanic every 2–3 levels |

---

Polish Checklist

• [ ] Dust particles on land/run
• [ ] Screen shake on heavy landings (godot-camera-systems trauma)
• [ ] Squash/stretch on jump/land (visual pivot at feet)
• [ ] SFX for jump/land/wall-slide
• [ ] Checkpoint visual/audio feedback
• [ ] Assist mode / remappable controls

> MANDATORY for depth beyond decision trees and script catalog: [platformer-movement-deep.md](references/platformer-movement-deep.md). Do NOT Load on first-pass wiring — use bundled scripts/ first.

Godot-Specific Tips

1. CharacterBody2D vs RigidBody2D: Always use CharacterBody2D for platformer characters - precise control is essential
2. Physics tick rate: Consider 120Hz physics for smoother movement
3. One-way platforms: Use set_collision_mask_value() or dedicated collision layers
4. Wall detection: Use is_on_wall() and get_wall_normal() for wall jumps

---

Example Games for Reference

• Celeste - Perfect game feel, assist mode accessibility
• Hollow Knight - Combat + platforming integration
• Super Mario Bros. Wonder - Visual polish and surprises
• Shovel Knight - Retro mechanics with modern feel

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Using CharacterBody2D — move_and_slide floor/wall/ceiling reports, slope snap, and platform_on_leave behavior that platformer feel depends on.
• CharacterBody2D — floor_constant_speed, floor_snap_length, recovery_as_collision, and motion-mode knobs for precision controllers.
• Physics introduction — collision layers/masks for player, one-ways, hazards, and projectiles without accidental overlaps.
• Collision shapes (2D) — why capsule/rectangle player shapes stay stable vs concave geometry.
• 2D movement overview — CharacterBody vs RigidBody tradeoffs and common input→velocity patterns.
• Using TileMaps — TileMapLayer collision for level geometry instead of per-sprite StaticBodies.
• Using TileSets — one-way collision and physics layers authored in the tileset for drop-through platforms.
• AnimatableBody2D — sync_to_physics moving platforms that riders must stick to without jitter.
• Camera2D — position smoothing, drag margins, and look-ahead offsets that prevent blind jumps and motion sickness.
• Using AnimationTree — boolean advance conditions for idle/run/air states without unsafe expression negation.
• Ray-casting — nodeless wall-slide and ledge queries via PhysicsDirectSpaceState2D.
• Input examples — action just-pressed/released patterns behind jump buffer and variable jump cutoff.

Related Skills

Prerequisites

• godot-project-foundations — project settings, input map actions, and scene structure before wiring coyote/buffer timers.
• godot-characterbody-2d — move_and_slide grounding, slopes, and wall normals that every precision jump builds on.
• godot-input-handling — remappable jump/move actions and unhandled-input buffering for assist-mode accessibility.

Complements

• godot-2d-physics — layers, CCD, Area2D hazards, and AnimatableBody platforms beyond the controller core.
• godot-tilemap-mastery — TileMapLayer/TileSet one-ways and collision painting for teachable level geometry.
• godot-camera-systems — look-ahead, room cameras, and smoothing that reveal landings without blind jumps.
• godot-animation-tree-mastery — AnimationTree conditions synced from is_on_floor / velocity for juice-safe state graphs.
• godot-2d-animation — squash/stretch and land/run cycles that sell weight after physics resolves.
• godot-particles — dust trails and land puffs called from jump/land events.
• godot-audio-systems — jump/land/wall-slide SFX timing that reinforces responsive feel.
• godot-monte-carlo-balancer — sample coyote/buffer/gravity/jump knobs and level difficulty curves before shipping assist defaults.

Downstream / consumers

• godot-genre-metroidvania — ability-gated exploration that reuses precision movement and TileMap rooms.
• godot-save-load-systems — checkpoint position persistence across deaths and scene reloads.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.