godot-adapt-3d-to-2d

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.

Strategy router (MANDATORY / Do NOT Load)

Strategy	Load	Do NOT Load
True 2D (drop Z)	jump_z_axis_sim.gd only if platformer height remains; else CharacterBody2D patterns	ortho_simulation.gd, iso math, fake shadows
2.5D / fake depth	MANDATORY ortho_simulation.gd + jump_z_axis_sim.gd + hitbox_depth_manager.gd + depth_sorting_y_sort.gd (+ parallax_depth_camera.gd / fake_3d_shadows.gd)	Manual z_index = int(y) spam; ortho Camera3D as 2D
Isometric stay	MANDATORY isometric_math_core.gd + depth_sorting_y_sort.gd	Cartesian-only velocity samples; Camera3D ortho fake
Bake 3D→sprites	MANDATORY model_to_sprite_bake.gd (+ billboard_sprite_manager.gd for Doom-style)	Blender bake recipes in body
Node/physics convert only	Decision tree + gravity/collision notes below	Strategy code samples; Dimensional Patcher regex without review

ortho_simulation.gd

Simulates 3D Z-axis height in 2D top-down games. Handles vertical velocity, gravity, sprite offset, and shadow scaling.

projection_utils.gd

Projects 3D world positions to 2D screen space for nameplates, healthbars, and targeting. Handles behind-camera detection and distance-based scaling.

isometric_math_core.gd

Expert utility generating translating between 2D Cartesian and True Isometric screenspace projection matrices without using 2D Node transforms.

depth_sorting_y_sort.gd

Expert dynamic Z-index Y-Sort script for fake 3D sorting isolated trees matching CanvasItem _update_sorting().

jump_z_axis_sim.gd

Complete CharacterBody2D snippet separating structural physical ground movement (X,Y) from a mathematically simulated jumping height (Z) in a topdown game.

parallax_depth_camera.gd

Fake Depth Camera applying varying offset algorithms to completely disparate CanvasLayers based on an index to simulate 3D camera translation panning.

hitbox_depth_manager.gd

Area2D derived class that requires explicit custom Z-height overlap (1D AABB collision) prior to validating 2D triggers to stop incorrect "ground vs air" collision in 2.5D.

fake_3d_shadows.gd

Sprite2D shadow simulator exploiting Godot 4.x Transform2D matrix skew shear to project and angle shadows away from a simulated 3D sun direction on a 2D floor.

billboard_sprite_manager.gd

8-directional FPS Doom-style sprite controller isolating the simulated 3D relative angle between a moving 2D CharacterBody and a Camera2D viewpoint.

nav_region_flattening.gd

Topdown 2D pathfinding workaround allowing "aerial" units to cross walls by leveraging multiple tiered 2D Navigation Layers instead of proper 3D verticality.

ortho_to_perspective_fx.gd

Screen space CanvasItem warp Shader simulating a Mode 7 / tabletop perspective pitch. Maps top screen coordinates via division pinching.

2d_lighting_normals.gd

Automatic programmatic generation of CanvasTexture combining base albedo and baked normal maps at runtime so Sprites correctly react to 2D PointLIGHTs like 3D geometry.

model_to_sprite_bake.gd

MANDATORY for automated 3D→sprite angle baking via SubViewport. Keep body as strategy router.

grid_nav_bridge.gd

Flatten 3D nav intent onto AStarGrid2D for grid-based 2D ports (XZ → cell indices).

---

Dimension Reduction Strategies

Pick one row from the strategy router above — do not paste conversion tutorials in-scene.

Strategy	Intent	Scripts
True 2D	Drop Z; Vector2 velocity; Camera2D	Peer godot-characterbody-2d / godot-camera-systems
2.5D / fake depth	Simulated height + Y-sort ownership + ground-vs-air hitboxes	ortho_simulation.gd, jump_z_axis_sim.gd, hitbox_depth_manager.gd, depth_sorting_y_sort.gd
Isometric stay	2D physics + iso projection	MANDATORY isometric_math_core.gd

Gravity scale: 3D 9.8 m/s² → 2D ~980 px/s² when 1 m ≈ 100 px. Collisions: CapsuleShape3D → CapsuleShape2D (see Physics Adjustments). Camera: Camera3D/SpringArm → Camera2D — NEVER ortho Camera3D as “2D mode”.

---

Art Pipeline: 3D Models → Sprites

MANDATORY when baking multi-angle sprites from GLB/scenes: model_to_sprite_bake.gd (@tool SubViewport baker). Manual Blender export stays outside this skill. Strategy choice stays in the decision tree below — do not re-inline bake recipes in the body.

---

Physics Adjustments

Gravity Scaling

# 3D gravity (m/s²): 9.8
# 2D gravity (pixels/s²): Scale to pixel units

# If 1 meter = 100 pixels:
const GRAVITY_2D = 9.8 * 100  # = 980 pixels/s²

# Adjust jump velocity proportionally:
# 3D jump: 4.5 m/s
# 2D jump: -450 pixels/s

Collision Simplification

# 3D: CapsuleShape3D (16 segments, expensive)
var shape_3d := CapsuleShape3D.new()
shape_3d.radius = 0.5
shape_3d.height = 2.0

# 2D: CapsuleShape2D (much simpler)
var shape_2d := CapsuleShape2D.new()
shape_2d.radius = 16  # pixels
shape_2d.height = 64

---

Control Simplification

3D Free Movement → 2D Restricted

# 3D: Full 3D movement with camera-relative controls
var input_3d := Input.get_vector("left", "right", "forward", "back")
var camera_basis := camera.global_transform.basis
var direction := (camera_basis * Vector3(input_3d.x, 0, input_3d.y)).normalized()

# 2D: Simple 4-direction (or 8-direction with diagonals)
var input_2d := Input.get_vector("left", "right", "up", "down")
velocity = input_2d.normalized() * SPEED

---

Performance Gains

Optimization Techniques

# 1. Use TileMapLayer instead of individual Sprite2D nodes
var tilemap := TileMapLayer.new()
tilemap.tile_set = load("res://tileset.tres")

# 2. Batch sprite rendering
# Use single large sprite sheet instead of individual textures

# 3. Reduce particle count
var godot-particles := GPUParticles2D.new()
godot-particles.amount = 50  # Down from 200 in 3D

---

UI Adaptation

# Most 3D games already use 2D UI (CanvasLayer)
# No changes needed!

# Just verify UI scaling for new aspect ratios
get_viewport().size_changed.connect(_on_viewport_resized)

func _on_viewport_resized() -> void:
    var viewport_size := get_viewport().get_visible_rect().size
    # Adjust UI anchors/margins

---

Edge Cases

Depth Sorting

NEVER drive sort with per-sprite z_index = int(global_position.y) — that contradicts Y-sort ownership. MANDATORY depth_sorting_y_sort.gd: enable y_sort_enabled on the parent and keep children at default relative z.

Lost Spatial Audio

# 3D spatial audio (AudioStreamPlayer3D) → 2D panning (AudioStreamPlayer2D)

var audio_2d := AudioStreamPlayer2D.new()
audio_2d.stream = load("res://sounds/footstep.ogg")
audio_2d.max_distance = 1000.0  # 2D range
audio_2d.attenuation = 2.0
add_child(audio_2d)

---

Decision Tree: When to Simplify to 2D

Factor	Keep 3D	Go 2D
Target platform	Desktop, console	Mobile, web
Art style	Realistic, immersive	Stylized, retro
Gameplay	Requires 3D space	Works in 2D plane
Performance	Have GPU budget	Need 60 FPS on low-end
Team skills	3D artists	2D artists or pixel art

Expert Techniques & Optimizations

1. Flattened Navigation (3D Navmesh to 2D Grid)

While Godot treats 2D and 3D navigation as separate systems, you can project 3D pathfinding logic onto a 2D grid using AStarGrid2D. This is highly optimized for 2D grid-based movement and avoids the overhead of a full 3D navmesh.

class_name GridNavBridge extends Node

var astar_grid: AStarGrid2D

func _ready() -> void:
    astar_grid = AStarGrid2D.new()
    astar_grid.region = Rect2i(0, 0, 100, 100)
    astar_grid.cell_size = Vector2(16, 16)
    astar_grid.update()

## Converts a 3D target position to a 2D grid path.
func get_grid_path_from_3d(start_3d: Vector3, end_3d: Vector3) -> PackedVector2Array:
    var start_map := Vector2i(start_3d.x / 16, start_3d.z / 16)
    var end_map := Vector2i(end_3d.x / 16, end_3d.z / 16)
    
    return astar_grid.get_point_path(start_map, end_map)

2. Auto-LOD for 2D (Performance Optimization)

Automatic LOD is natively a 3D feature, but you can simulate it in 2D using VisibleOnScreenEnabler2D. This node automatically toggles the process_mode of target nodes (like high-res sprites or complex AI) when they leave the screen, preserving CPU cycles and GPU fill rate.

# Attach to a complex 2D entity
func setup_2d_lod(target_node: Node2D) -> void:
    var enabler := VisibleOnScreenEnabler2D.new()
    # Define the 'high-detail' rect
    enabler.rect = Rect2(-64, -64, 128, 128) 
    enabler.enable_node_path = target_node.get_path()
    add_child(enabler)

3. Dimensional Patcher (CharacterBody3D to 2D Regex)

To automate the down-porting of 3D controllers, use a RegEx script to map Vector3 to Vector2 and replace 3D-specific properties. This is essential for massive porting tasks where manual conversion of movement logic is prone to error.

@tool
extends EditorScript

func _run() -> void:
    var regex = RegEx.new()
    # Pattern to find Vector3 constructors and replace with Vector2
    regex.compile("Vector3\\(([^,]+),\\s*([^,]+),\\s*([^)]+)\\)")
    
    var script_content = "velocity = Vector3(input.x, 0.0, input.y) * speed"
    var result = regex.sub(script_content, "Vector2($1, $3)", true)
    
    # Output: "velocity = Vector2(input.x, input.y) * speed"
    print(result)

Deep recipes (on demand)

Topic	Reference / script
True 2D / bake / camera conversion	dimension-reduction.md

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

• Introduction to 2D — Establishes the CanvasItem/Camera2D pipeline you must switch into when leaving Node3D rendering for real 2D performance.
• Using CharacterBody2D — Canonical move_and_slide / floor / jump patterns after CharacterBody3D → CharacterBody2D conversion.
• Physics introduction — Units, layers/masks, and why 3D gravity/Vector3 assumptions break when gravity becomes a 2D scalar.
• 2D transforms — Transform2D basis/skew math used for isometric placement and fake projected shadows.
• 2D parallax — Layer scroll scales that replace Z-depth when gameplay collapses to a plane.
• Canvas layers — Stacking CanvasLayers for fake-depth cameras without keeping an orthographic Camera3D.
• 2D lights and shadows — Normal-mapped CanvasTexture / Light2D path that restores 3D-looking lighting on sprites.
• Navigation introduction (2D) — 2D nav regions/layers for flattening vertical 3D pathing into tiered 2D agents.
• Using Viewports — SubViewport capture of 3D models into Sprite2D textures (runtime or bake pipeline).
• Camera2D — Zoom, limits, and follow API that should replace “ortho Camera3D as 2D mode.”
• CanvasItem — y_sort_enabled / z_index / z_as_relative for depth sorting after losing true Z.
• General optimization — Reminds that 2D only wins if draw calls, overdraw, and process cost are actually reduced.

Related Skills

Prerequisites

• godot-characterbody-2d — Destination movement API for top-down/platformer ports once Z is simulated or removed.
• godot-2d-physics — CapsuleShape2D/Area2D collision simplification and layer masks after dropping 3D shapes.
• godot-camera-systems — Camera2D follow/limits/zoom so ports do not keep a fake ortho Camera3D.
• godot-gdscript-mastery — Typed Vector2/Transform2D math and tooling scripts used throughout dimension-reduction helpers.

Complements

• godot-2d-animation — Sprite-sheet / AnimatedSprite2D pipeline after baking 3D models to directional frames.
• godot-shaders-basics — CanvasItem shaders for Mode-7 / perspective pitch and other screen-space depth fakes.
• godot-tilemap-mastery — TileMapLayer batching that often replaces individual 3D mesh instances in the 2D port.
• godot-navigation-pathfinding — Deeper 2D navmesh/AStarGrid2D patterns when flattening aerial/vertical routes.
• godot-audio-systems — AudioStreamPlayer3D → AudioStreamPlayer2D panning/attenuation after spatial audio is lost.
• godot-adapt-2d-to-3d — Inverse adaptation lattice when deciding which axis of the port to keep or reverse.

Downstream / consumers

• godot-performance-optimization — Escalate when the 2D port still misses frame budgets despite dimensional reduction.
• godot-platform-mobile — Common shipping target that motivates 3D→2D simplification for battery and GPU limits.
• godot-adapt-desktop-to-mobile — Broader desktop→mobile adaptation that often includes this skill’s flatten-to-2D step.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting 2D/3D concern.