NEVER Do

NEVER remove Z-axis without gameplay compensation — Blindly flattening 3D to 2D removes spatial strategy. Add other depth mechanics (layers, jump height variations).
NEVER keep 3D collision shapes — Use simpler 2D shapes (CapsuleShape2D, RectangleShape2D). 3D shapes don't convert automatically.
NEVER use orthographic Camera3D as "2D mode" — WHY: You still pay 3D transform/lighting costs and miss CanvasItem batching. Use Camera2D + 2D nodes (ortho_simulation.gd only for simulated height).
NEVER assume automatic performance gain — Poorly optimized 2D (too many draw calls, large sprite sheets) can be slower than optimized 3D.
NEVER forget to adjust gravity — 3D gravity is Vector3(0, -9.8, 0). 2D gravity is float (980 pixels/s²). Scale appropriately.
NEVER treat ground and air hits as the same Area2D overlap — In 2.5D, a ground slash must not hit jumping targets. WHY: 2D physics has no Z. Use hitbox_depth_manager.gd height AABB checks.
NEVER fight Y-sort with per-sprite z_index spam — WHY: Ownership of sort order belongs on the Y-sorted parent. Use depth_sorting_y_sort.gd; manual z_index drifts every frame.

Available Scripts

MANDATORY: Read the appropriate script before implementing the corresponding pattern.