godot-adapt-2d-to-3d

NEVER Do

• NEVER directly replace Vector2 with Vector3(x, y, 0) — This creates a "flat 3D" game with no depth gameplay. Add Z-axis movement or camera rotation to justify 3D.
• NEVER keep 2D collision layers — 2D and 3D physics use separate layer systems. You must reconfigure collision_layer/collision_mask for 3D nodes.
• NEVER forget to add lighting — 3D without lights is pitch black (unless using unlit materials). Add at least one DirectionalLight3D.
• NEVER use Camera2D follow logic in 3D — Camera3D needs spring arm or look-at logic. Direct position copying causes clipping and disorientation.
• NEVER assume same performance — 3D is 5-10x more demanding. Budget for lower draw calls, smaller viewport resolution on mobile.
• NEVER use the rotation property for complex 3D logic — 3D rotation uses Euler angles. Interpolating Euler angles causes unpredictable paths and Gimbal Lock. Always use Quaternion for 3D rotation interpolation or the Basis matrix for directional vectors.
• NEVER ignore metric scaling — 3D physics and lighting assume 1 unit = 1 meter. Scaling models inside the engine introduces precision errors. Export assets from DCCs at the correct metric scale.
• NEVER disable physics interpolation when using custom camera follow scripts — Updating camera position in _process to follow a body moving in _physics_process causes jitter. Use Node3D.get_global_transform_interpolated() for smooth transforms.

Available Scripts

MANDATORY: Load migration scripts before pasting camera/movement recipes.

spring_arm_camera_setup.gd

MANDATORY third-person SpringArm3D + Camera3D. Do not parent Camera3D bare to the body.

characterbody3d_migration_movement.gd

MANDATORY camera-relative CharacterBody3D movement for 2D→3D ports.

physics_layer_migration_checklist.gd

MANDATORY checklist: 3D Physics layer names are separate from 2D — mirror names, then apply bits.

sprite_plane.gd

Sprite3D billboard configuration and world-to-screen projection for placing 2D UI over 3D objects.

vector_mapping.gd

Vector2↔Vector3 mapping helpers (Y-up vs Z-forward pitfalls).

crisp_projected_ui.gd

Diegetic / projected UI sharpness patterns.

adapt_2d_to_3d_patterns.gd

Billboards, mouse→3D rays, CanvasLayer overlay helpers.

navigation_bridge_2d5d.gd

Projects NavigationServer3D paths to 2D screen/gameplay plane for 2.5D sprite actors.

massive_crowd_manager.gd

MultiMesh + billboard shader crowd (GPU orientation; not per-node Sprite3D).

Do NOT Load lighting deep-dives here — route to godot-3d-lighting. Add a DirectionalLight3D + ambient only; GI/cascades live there.

Node Conversion Matrix

Migration Steps (script-first)

1. Physics layers — MANDATORY physics_layer_migration_checklist.gd. Project Settings → Layer Names → 3D Physics.
2. Camera — MANDATORY spring_arm_camera_setup.gd. Never copy Camera2D follow onto Camera3D.
3. Movement — MANDATORY characterbody3d_migration_movement.gd. Camera-relative XZ; jump on Y.

Art Pipeline: Sprites → 3D Models

Option 1: Billboard Sprites (2.5D)

# Use Sprite3D for quick conversion
extends Sprite3D
 
func _ready() -> void:
    texture = load(

Option 2: Quad Meshes (Floating Sprites)

Option 3: Full 3D Models (Blender/Asset Library)

Lighting Considerations

Minimum: one DirectionalLight3D + WorldEnvironment ambient so the scene is not black. Do NOT Load cascade/GI/bake tutorials in this skill — godot-3d-lighting.

UI Adaptation

Performance Budgeting (profiler gates)

Speculative "2D vs 3D budget" tables lie. Gate on measured data:

1. Open Profiler / Debugger → Monitors after the port runs on target hardware.
2. Draw calls / primitives — if MeshInstance count explodes, add Mesh LOD / Visibility Ranges before guessing vertex caps.
3. Shadow cost — lower directional_shadow_max_distance and shadowed Omni/Spot count until frame time recovers (tune in godot-3d-lighting).
4. LOD procedure — set visibility_range_* on distant GeometryInstance3D; unlit/simplified materials past the near band.
5. Fail gate — ship only when 95th-percentile frame time meets the platform target (e.g. ≤16.6 ms for 60 FPS), not when a spreadsheet says "50–100 draw calls".

Input Scheme Changes

2D → 3D Input Mapping

Edge Cases

Physics Not Working

Camera Clipping Through Walls

Use MANDATORY spring_arm_camera_setup.gd — set spring_arm.collision_mask to the World layer so the boom retracts instead of clipping.

Player Falling Through Floor

Decision Tree: When to Go 3D

Expert Techniques & Optimizations

1. Vector Math over Euler Angles

When moving a 3D character, rely heavily on Transform3D basis vectors rather than calculating trigonometric angles. To move forward locally, extract the negative Z-axis of your transform's basis: velocity = transform.basis.z * speed.

2. Understanding Coordinate Discrepancies

In 2D, the Y-axis points down. In 3D, Godot uses a right-handed system where Y-axis points UP, and forward is -Z. Translating 2D jumps to 3D requires inverting the Y velocity logic (e.g., velocity.y = JUMP_SPEED instead of -JUMP_SPEED).

3. 2.5D Navigation (Camera-Projected Paths)

For 2.5D games where actors move on a 3D floor but are displayed as 2D sprites, query the NavigationServer3D directly and project the resulting PackedVector3Array into 2D screen space (or a flattened gameplay plane) using Camera3D.unproject_position.

4. Shader-Based Billboarding (Massive Crowd Rendering)

To render millions of instances, use MultiMeshInstance3D paired with a custom Visual Shader. Use VisualShaderNodeBillboard with BILLBOARD_TYPE_FIXED_Y to ensure sprites stay upright on flat terrain.

5. Lighting Migration

PointLight2D→OmniLight3D conversion is one-shot editor work — keep a project tool if needed. Ongoing lighting quality belongs in godot-3d-lighting.

Deep recipes (on demand)

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 3D — Coordinate system, Node3D, and camera basics you must adopt when leaving the CanvasItem/Y-down 2D world.
• Using transforms — Basis/Transform3D/Quaternion patterns that replace Euler-angle Camera2D follow and 2D rotation habits.
• CharacterBody3D — Destination move_and_slide API after CharacterBody2D → CharacterBody3D conversion (no dedicated 3D tutorial page).
• Physics introduction — Separate 2D/3D layer systems, units (1 unit ≈ 1 m), and gravity vectors that invalidate copied 2D masks.
• Collision shapes (3D) — Shape3D equivalents for BoxShape2D/CapsuleShape2D when rebuilding CollisionShape3D stacks.
• SpringArm3D — Third-person boom + occlusion pull-in that must replace direct Camera2D position copying.
• 3D lights and shadows — Minimum DirectionalLight3D/OmniLight3D setup; 3D scenes are black without lights or unlit materials.
• Environment and post-processing — WorldEnvironment ambient fill so ports are not pitch-black between key lights.
• Standard Material 3D — Billboard, transparency, and shading modes for Sprite3D/QuadMesh sprite→plane art paths.
• Using GridMaps — MeshLibrary/GridMap replacement for TileMapLayer-style level layouts in 3D.
• Importing 3D scenes — GLB/FBX scale and animation import when leaving the sprite pipeline for real meshes.
• Physics interpolation introduction — Why camera follow in _process needs interpolated transforms after physics-step movement.

Related Skills

Prerequisites

• godot-gdscript-mastery — Typed Vector2/Vector3 and Transform3D fluency before applying Y→Z mapping helpers.
• godot-characterbody-2d — Source platformer/top-down movement semantics you are lifting into CharacterBody3D.
• godot-2d-physics — Existing 2D layer/mask design that must be recreated under the separate 3D physics layer table.
• godot-input-handling — Input.get_vector plus mouse-capture look so 2D left/right maps become camera-relative XZ.

Complements

• godot-camera-systems — SpringArm3D / orbit / first-person rigs that replace Camera2D follow after the port.
• godot-3d-lighting — DirectionalLight3D, shadows, and ambient environments required once sprites become lit meshes.
• godot-3d-materials — PBR/billboard/alpha materials for QuadMesh and Sprite3D art migration.
• godot-3d-world-building — GridMap, collision generation, and LOD after TileMapLayer worlds move to 3D.
• godot-raycasting-queries — Mouse→world PhysicsRayQueryParameters3D picks used by point-and-click 3D ports.
• godot-ui-containers — CanvasLayer HUD that stays 2D while world content becomes Node3D.
• godot-navigation-pathfinding — NavigationServer3D paths for 2.5D bridges that still project to screen or gameplay planes.
• godot-adapt-3d-to-2d — Inverse adaptation lattice when deciding to flatten back or keep hybrid 2.5D.

Downstream / consumers

• godot-performance-optimization — Escalate when the 3D port blows the old 2D draw-call/vertex budget.
• godot-platform-mobile — Shipping target that forces LOD, shadow distance, and resolution tradeoffs after going 3D.

Master

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