godot-adapt-3d-to-2d

Files (15)

• SKILL.md
• 2d_lighting_normals.gd · scripts/
• adapt_3d_to_2d_patterns.gd · scripts/
• billboard_sprite_manager.gd · scripts/
• depth_sorting_y_sort.gd · scripts/
• directional_sprite_resolver.gd · scripts/
• fake_3d_shadows.gd · scripts/
• hitbox_depth_manager.gd · scripts/
• isometric_math_core.gd · scripts/
• jump_z_axis_sim.gd · scripts/
• nav_region_flattening.gd · scripts/
• ortho_simulation.gd · scripts/
• ortho_to_perspective_fx.gdshader · scripts/
• parallax_depth_camera.gd · scripts/
• projection_utils.gd · scripts/

SKILL.md (first lines)

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# Adapt: 3D to 2D

Expert guidance for simplifying 3D games into 2D (or 2.5D).

## 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"** — Use actual Camera2D for proper 2D rendering pipeline and performance.
- **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.

---

## Available Scripts

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

### [ortho_simulation.gd](scripts/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](scripts/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](scripts/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](scripts/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](scripts/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](scripts/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](scripts/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](scripts/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](scripts/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](scripts/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.gdshader](scripts/ortho_to_perspective_fx.gdshader)
Screen space CanvasItem warp Shader simulating a Mode 7 / tabletop perspective pitch. Maps top screen coordinates via division pinching.

### [2d_lighting_normals.gd](scripts/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.


---

## Why Go from 3D to 2D?

| Reason | Benefit |
|--------|---------|
| **Mobile performance** | 5-10x faster on low-end devices |
| **Simpler art pipeline** | Sprites easier to create than 3D models |
| **Faster iteration** | 2D level design is quicker |
| **Accessibility** | Lower hardware requirements |
| **Clarity** | Reduce visual clutter for puzzle/strategy games |

---

## Dimension Reduction Strategies

### Strategy 1: True 2D (Remove Z-axis)

```gdscript
# Top-down or side-view
# Example: 3D isometric → 2D top-down

# Before (3D):
var velocity := Vector3(input.x, 0, input.y) * speed

# After (2D):
var velocity := Vector2(input.x, input.y) * speed

# Use case: Top-down shooters, RTS, turn-based strategy
```

### Strategy 2: 2.5D (Fake depth with layers)

```gdscript
# Keep visual depth perception without Z-axis gameplay
# Use ParallaxBackground for depth layers

# Scene structure:
# ParallaxBackground
#   ├─ ParallaxLayer (far mountains, scroll slow)
#   ├─ ParallaxLayer (mid buildings, scroll medium)
#   └─ ParallaxLayer (near trees, scroll fast)

# player.gd
extends CharacterBody2D

func _ready() -> void:
    var parallax := get_node("../ParallaxBackground")
    parallax.scroll_base_scale = Vector2(0.5, 0.5)  # Parallax strength
```

### Strategy 3: Fixed Perspective (Isometric Stay)

```gdscript
# Keep isometric/dimetric view but use 2D physics
# Use rotated sprites to simulate 3D angles

const ISO_ANGLE := deg_to_rad(-30)  # Isometric tilt

From bgrenat/godot-game-dev-studio, LGPL-3.0.

More from bgrenat/godot-game-dev-studio