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

3d-essentials

Use when working with 3D-specific systems — materials, lighting, shadows, environment, global illumination, fog, LOD, occlusion culling, and decals in Godot 4.3+

jame581 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add jame581/GodotPrompter --skill 3d-essentials

技能说明


name: 3d-essentials description: Use when working with 3D-specific systems — materials, lighting, shadows, environment, global illumination, fog, LOD, occlusion culling, and decals in Godot 4.3+

3D Essentials in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.

Related skills: player-controller for CharacterBody3D movement, physics-system for 3D collision shapes and raycasting, camera-system for Camera3D follow and transitions, shader-basics for spatial shaders and post-processing, godot-optimization for 3D performance tuning, animation-system for AnimationTree and 3D animation blending.


1. 3D Coordinate System & Core Nodes

Coordinate System

Godot uses a right-handed coordinate system with metric units (1 unit = 1 meter):

AxisDirectionColor
XRightRed
YUpGreen
ZOut of screen (+Z toward viewer)Blue

Cameras and lights point along -Z by default. When a character "faces forward," they look along -Z.

Essential 3D Nodes

NodePurpose
Node3DBase transform node — position, rotation, scale
MeshInstance3DDisplays a mesh with a material
Camera3DRequired to render 3D — perspective or orthogonal
DirectionalLight3DSun/moon — parallel rays, cheapest light
OmniLight3DPoint light — emits in all directions
SpotLight3DCone light — flashlights, spotlights
WorldEnvironmentSky, fog, tonemap, post-processing
DecalProjected texture onto surfaces
GPUParticles3DGPU-driven particle effects
CSGBox3D etc.Constructive Solid Geometry — prototyping
GridMap3D tile-based level building

Godot 4.7+: GridMap exposes its internal octants for spatial queries (cell_octant_size, get_used_octants(), get_octants_in_bounds() and friends) so you can scope work to a region instead of walking every cell. CSGShape3D gains autosmooth / smoothing_angle for automatic face smoothing. Full method table and semantics: references/godot-4.7-additions.md

Minimal 3D Scene

World (Node3D)
├── Camera3D
├── DirectionalLight3D
├── WorldEnvironment
├── MeshInstance3D (floor)
└── MeshInstance3D (player model)

2. Materials

StandardMaterial3D vs ShaderMaterial

MaterialUse ForNotes
StandardMaterial3DMost 3D objects — PBR workflowNo code; Inspector-driven
ORMMaterial3DSame as Standard but with packed ORM textureOcclusion+Roughness+Metallic in one texture
ShaderMaterialCustom effects — toon, water, dissolveRequires spatial shader code

Key StandardMaterial3D Properties

The PBR core: albedo_color / albedo_texture (base color), metallic (0 dielectric → 1 metal), roughness (0 mirror → 1 matte), normal_map (surface detail), ao_texture (ambient occlusion). Add emission + emission_energy_multiplier for self-illumination, heightmap_texture for parallax, rim / clearcoat for material flair.

Transparency Modes

Prefer Alpha Scissor (fast, shadowed cutouts) or Alpha Hash (dithered — hair) over plain Alpha (slow, no shadows); Depth Pre-Pass suits mostly-opaque meshes with transparent edges.

See references/materials-and-lighting-recipes.md for the comparison table.

Setting Materials from Code & Material Instancing

Create a StandardMaterial3D at runtime, assign to mesh.material_override, and drive emissive flashes via Tween. Use .duplicate() to make per-instance copies so changing one mesh's material doesn't affect others.

See references/materials-and-lighting-recipes.md for the full GDScript and C# recipes (basic material setup, emissive flash, per-instance duplicate, dynamic OmniLight3D explosion).


3. Lighting

Light Types Comparison

LightShapeShadowsCostMax Visible
DirectionalLight3DParallel raysPSSMCheapest8 (Forward+)
OmniLight3DSphereCube/Dual ParaboloidMedium512 clustered*
SpotLight3DConeSingle textureCheap512 clustered*
AreaLight3D (4.7+)RectanglePCSS softMost expensive—

*Forward+ shares 512 clustered element slots among omni lights, spot lights, decals, and reflection probes.

Light Properties

Key knobs: light_color, light_energy (HDR — values >1 are valid), shadow_enabled (big perf hit), directional_shadow_mode, directional_shadow_max_distance (lower = sharper shadows).

See references/materials-and-lighting-recipes.md for the properties table and the GDScript + C# sun setup snippet.

AreaLight3D (Godot 4.7+)

AreaLight3D emits light from a rectangle along the node's -Z — neon tubes, screens, softbox panels — with PCSS soft shadows driven by light_size. Key properties: area_size = Vector2(1, 1) (meters), area_range = 5.0, area_attenuation = 1.0 (2.0 = physically accurate inverse square), area_normalize_energy = true (resizing keeps total output stable), optional area_texture for textured emission (Forward+/Mobile only). Mobile support is limited and Compatibility cannot cast area-light shadows; in Forward+, a single visible area light adds clustered-lighting cost to all rendered objects — reserve for cinematics or high-end targets.

See references/materials-and-lighting-recipes.md for the full property table and the GDScript + C# setup recipe

阅读完整来源 ↗