Godot Characterbody 2D

CharacterBody2D Implementation

Expert CharacterBody2D feel systems — not beginner move_and_slide tutorials.

NEVER Do

• NEVER use RigidBody2D for standard player controllers — RigidBody is for physics-simulated objects. For responsive, feel-driven player movement, always use CharacterBody2D.
• NEVER multiply velocity by delta before move_and_slide() — move_and_slide() handles delta internally. Manual multiplication makes movement framerate-dependent.
• NEVER use global_position updates for gameplay movement — Use velocity + move_and_slide(). Direct position hacks bypass collision, floor snap, and one-way rules.
• NEVER "fall through" one-ways by nudging position.y — Use one-way collision shapes + layer/mask (and temporary mask disable / collide-with-areas patterns). See godot-2d-physics.
• NEVER ignore floor/wall/ceiling state right after move_and_slide() — is_on_floor(), is_on_wall(), is_on_ceiling(), and slide collisions drive coyote, wall jump, and bonk logic.
• NEVER rely on default floor_snap_length for fast stair-climbing — Default snapping is too small for high-velocity characters. Use custom raycast-based stair logic.
• NEVER apply gravity while is_on_floor() is true — Constant downward force causes micro-jitter and fights floor-snap. Reset velocity.y on land.
• NEVER use Area2D as primary ground detection — Prefer is_on_floor() / shapecasts; Areas are for triggers, not floor truth.
• NEVER forget ceiling bonk — Reset velocity.y when is_on_ceiling() or the player floats into the ceiling until gravity wins.
• NEVER round physics positions for pixel art — Keep physics high-precision; round sprite positions in _process only (subpixel_movement_rounding.gd).
• NEVER spam queue_free() for hordes — Pool bullets/enemies when spawn/despawn is frequent (performance_character_pooling.gd).

---

When to Use CharacterBody2D

Decision Tree → MANDATORY Scripts

Golden path: Read expert_physics_2d.gd first. Add dash/wall/jump scripts only after that controller is in place. Do not re-inline coyote/buffer/accel loops in the scene when the script already owns them.

One-Way Platforms (correct recipe)

1. Author one-way on the platform collider (CollisionShape2D one-way / TileSet physics one-way), not by teleporting the player.
2. Put platforms and player on explicit collision layers/masks so drop-through can temporarily clear the platform bit (or disable collide-with) while holding down + jump — then restore next physics frames.
3. Keep drop-through on the physics tick; never bypass move_and_slide with position nudges.
4. For tile one-ways, align TileSet physics layers with CharacterBody masks — see godot-tilemap-mastery + godot-2d-physics.

Expert Character Architectures

1. Wall Cling (Variable Friction)

Monitor is_on_wall() while falling; scale velocity.y by a friction factor (optionally from tile custom data) instead of a binary wall-slide bool. Prefer wall_slide_jump_refined.gd over a bespoke cling fork.

2. Animation-Driven Movement (Root Motion)

Pull AnimationTree.get_root_motion_position(), convert to 2D, assign velocity = motion / delta, then move_and_slide(). Keeps feet locked to authored clips; pair with godot-2d-animation.

3. Game-Feel Profiler (Jump Arcs)

Debug-draw historical positions + current velocity in _draw() to visualize apex, coyote, and buffer windows while tuning exports on expert_physics_2d.gd — game_feel_profiler.gd.

MANDATORY for top-down/tank recipes, moving platforms, slide-collision response, and gotcha tables: movement-recipes.md. Do NOT Load when expert_physics_2d.gd already covers your platformer scope.