跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

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 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

2D Node3D EquivalentNotes
CharacterBody2DCharacterBody3DMANDATORY characterbody3d_migration_movement.gd
RigidBody2DRigidBody3DGravity Vector3(0, -9.8, 0)
StaticBody2DStaticBody3DShape3D resources (no auto-convert)
Area2DArea3DSame trigger idea; new layers
Sprite2DMeshInstance3D / Sprite3DBillboard vs mesh art choice
Camera2DCamera3DMANDATORY spring_arm_camera_setup.gd
CollisionShape2DCollisionShape3DRe-author shapes
RayCast2DRayCast3Dtarget_position is Vector3

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("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

阅读完整来源 ↗