godot-adapt-2d-to-3d
Expert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
thedivergentai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/GD-Agentic-Skills --skill godot-adapt-2d-to-3d技能说明
name: godot-adapt-2d-to-3d description: "Expert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion."
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
Quaternionfor 3D rotation interpolation or theBasismatrix 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
_processto follow a body moving in_physics_processcauses jitter. UseNode3D.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
| 2D Node | 3D Equivalent | Notes |
|---|---|---|
| CharacterBody2D | CharacterBody3D | MANDATORY characterbody3d_migration_movement.gd |
| RigidBody2D | RigidBody3D | Gravity Vector3(0, -9.8, 0) |
| StaticBody2D | StaticBody3D | Shape3D resources (no auto-convert) |
| Area2D | Area3D | Same trigger idea; new layers |
| Sprite2D | MeshInstance3D / Sprite3D | Billboard vs mesh art choice |
| Camera2D | Camera3D | MANDATORY spring_arm_camera_setup.gd |
| CollisionShape2D | CollisionShape3D | Re-author shapes |
| RayCast2D | RayCast3D | target_position is Vector3 |
Migration Steps (script-first)
- Physics layers — MANDATORY
physics_layer_migration_checklist.gd. Project Settings → Layer Names → 3D Physics. - Camera — MANDATORY
spring_arm_camera_setup.gd. Never copy Camera2D follow onto Camera3D. - 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("res://sprites/character.png")
billboard = BaseMaterial3D.BILLBOARD_ENABLED # Always face camera
pixel_size = 0.01 # Scale sprite in 3D space
Option 2: Quad Meshes (Floating Sprites)
# Create textured quads
var mesh_instance := MeshInstance3D.new()
var quad := QuadMesh.new()
quad.size = Vector2(1, 1)
mesh_instance.mesh = quad
var material := StandardMaterial3D.new()
material.albedo_texture = load("res://sprites/character.png")
material.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
material.cull_mode = BaseMaterial3D.CULL_DISABLED # Show both sides
mesh_instance.material_override = material
Option 3: Full 3D Models (Blender/Asset Library)
# Import .glb, .fbx models
var character := load("res://models/character.glb").instantiate()
add_child(character)
# Access animations
var anim_player := character.get_node("AnimationPlayer")
anim_player.play("idle")
Lighting Considerations
Minimum: one DirectionalLight3D + WorldEnvironment am