Godot 3D

3D 场景用哪个节点、哪个资源、哪个项目设置，以及照直觉会写错的地方。

范围

先查内置

做法

角色移动

extends CharacterBody3D

@export var speed: float = 5.0
@export var jump_velocity: float = 4.5

func _physics_process(delta: float) -> void:
	if not is_on_floor():
		velocity += get_gravity() * delta
	elif Input.is_action_just_pressed("jump"):
		velocity.y = jump_velocity

	var input: Vector2 = Input.get_vector("move_left", "move_right", "move_forward", "move_back")
	var direction: Vector3 = global_basis * Vector3(input.x, 0.0, input.y)
	velocity.x = direction.x * speed
	velocity.z = direction.z * speed
	move_and_slide()

• velocity 是每秒速度，不乘 delta
• get_vector 长度已限制为 1，不再 normalized()，摇杆轻推保持慢速
• is_on_floor() 读的是上一次 move_and_slide() 的结果
• 相机相对移动时用相机的 yaw 基底代替 global_basis
• 没有内置台阶，用斜面碰撞体，或 ShapeCast3D 自己检测
• 重力方向不是 Y 时改 up_direction
• 坡度、贴地、撞墙等属性默认值见 references/physics-3d.md

物理引擎

[physics]

3d/physics_engine="Jolt Physics"

• 4.5 及更早升级的项目手动改，改完重启编辑器
• Jolt 与 GodotPhysics3D 的差异见 references/physics-3d.md

碰撞层

先列碰撞对再分层，在 layer_names/3d_physics/layer_1 到 layer_32 里起名。

extends CharacterBody3D

const LAYER_WORLD: int = 1 << 0
const LAYER_PLAYER: int = 1 << 1
const LAYER_ENEMY: int = 1 << 2

@export_flags_3d_physics var hit_mask: int = LAYER_ENEMY

func _ready() -> void:
	collision_layer = LAYER_PLAYER
	collision_mask = LAYER_WORLD | LAYER_ENEMY

• collision_layer 是我在哪层，collision_mask 是我扫描哪层
• 位掩码第 n 层是 1 << (n - 1)，单层开关 set_collision_mask_value(n, true)
• Area3D 检测不到谁，先查对方 layer 是否在自己的 mask 里

空间查询

extends Camera3D

const RAY_LENGTH: float = 1000.0

func pick(mouse_position: Vector2) -> Dictionary:
	var space: PhysicsDirectSpaceState3D = get_world_3d().direct_space_state
	var from: Vector3 = project_ray_origin(mouse_position)
	var to: Vector3 = from + project_ray_normal(mouse_position) * RAY_LENGTH
	var query: PhysicsRayQueryParameters3D = PhysicsRayQueryParameters3D.create(from, to, 1 << 2)
	query.collide_with_areas = true
	return space.intersect_ray(query)

• 结果是字典，没命中为空，有 position normal collider rid shape
• direct_space_state 只在 _physics_process() 里访问，_input() 里只记鼠标位置

第三人称相机

节点结构：Node3D 枢轴，下面 SpringArm3D，下面 Camera3D。

extends Node3D

@export var mouse_sensitivity: float = 0.003

@onready var _arm: SpringArm3D = $SpringArm3D

func _ready() -> void:
	var body: CollisionObject3D = get_parent() as CollisionObject3D
	if body != null:
		_arm.add_excluded_object(body.get_rid())

func _unhandled_input(event: InputEvent) -> void:
	var motion: InputEventMouseMotion = event as InputEventMouseMotion
	if motion == null or Input.mouse_mode != Input.MOUSE_MODE_CAPTURED:
		return
	rotate_y(-motion.screen_relative.x * mouse_sensitivity)
	_arm.rotation.x = clampf(_arm.rotation.x - motion.screen_relative.y * mouse_sensitivity, -1.2, 1.2)

• shape 留空且相机是直接子节点时，用相机近平面做形状
• collision_mask 默认第 1 层，玩家层在内又没排除时被自己顶短
• 第一人称不用弹簧臂，yaw 转身体，pitch 转相机所在的头节点

渲染器

• 导出到网页只能用 Compatibility，切换后场景和环境要重调
• 能力差异表见 references/rendering-lighting.md

光照与 GI

• 桌面项目先开 SDFGI，不够再换
• 手机只能 LightmapGI 加 ReflectionProbe
• 由快到慢：ReflectionProbe、LightmapGI、VoxelGI、SSIL、SDFGI
• 小型动态物体 gi_mode 设 Disabled，大型设 Dynamic，只对 VoxelGI 有效
• gi_mode、灯的烘焙模式见 references/rendering-lighting.md

环境与相机属性

• WorldEnvironment 每个场景树只放一个，Camera3D.environment 优先
• Environment.tonemap_mode 默认 Linear，亮部截断，换 Filmic、ACES 或 AgX 4.4+
• Camera3D.attributes 优先于 WorldEnvironment 上的 CameraAttributes
• CameraAttributesPhysical 覆盖相机 fov near far，拿不准用 CameraAttributesPractical
• tonemap_white 取值、泛光阈值见 references/rendering-lighting.md

场景导入与关卡

• 格式优先 glTF 2.0，.glb 单文件；OBJ 没有骨骼、动画、PBR、UV2
• Blender 对象名后缀决定导入结果，如 -col -colonly -rigid -navmesh
• 动画名以 loop 或 cycle 开头或结尾自动循环
• 改材质先 Extract Materials，加节点用继承场景
• 网格拼装用 GridMap 加 MeshLibrary，CSG 只做灰盒
• 后缀全表、MeshLibrary、CSG、运行时加载 glTF 见 references/import-and-levels.md

剔除与 LOD

• 远处降面：导入的 glTF 默认生成 mesh LOD
• 手做多级模型：visibility_range_begin visibility_range_end
• 室内遮挡：开 rendering/occlusion_culling/use_occlusion_culling，加 OccluderInstance3D 烘焙
• 完整做法与 MultiMesh 见 references/culling-and-instancing.md

导航

extends CharacterBody3D

@export var speed: float = 4.0

@onready var _agent: NavigationAgent3D = $NavigationAgent3D

func go_to(target: Vector3) -> void:
	_agent.target_position = target

func _physics_process(_delta: float) -> void:
	if NavigationServer3D.map_get_iteration_id(_agent.get_navigation_map()) == 0:
		return
	if _agent.is_navigation_finished():
		return
	var next: Vector3 = _agent.get_next_path_position()
	velocity = global_position.direction_to(next) * speed
	move_and_slide()

• 场景放 NavigationRegion3D 加 NavigationMesh，下面放参与烘焙的网格，点 Bake
• NavigationMesh.cell_size 与 navigation/3d/default_cell_size 一致
• 运行时烘焙用 bake_navigation_mesh(true)
• 地图后台同步，进场头几帧 map_get_iteration_id() 为 0，先判断
• get_next_path_position() 每物理帧调一次，到达后不再调
• 避让：开 avoidance_enabled，连 velocity_computed，给 velocity 赋值，且设过 target_position

骨骼修改器

作为 Skeleton3D 的子节点，在动画之后运行。influence 做淡入淡出，active 开关。

• SkeletonIK3D 已弃用
• 全部修改器与版本见 references/skeleton-modifiers.md

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法
• references/physics-3d.md：Jolt 差异、范围查询、ShapeCast3D
• references/rendering-lighting.md：渲染器差异、灯、阴影、GI 烘焙
• references/import-and-levels.md：导入、后缀全表、GridMap、CSG、继承场景
• references/culling-and-instancing.md：LOD、遮挡、MultiMesh、Decal
• references/skeleton-modifiers.md：骨骼修改器与版本
• https://docs.godotengine.org/en/stable/tutorials/3d/index.html
• https://docs.godotengine.org/en/stable/tutorials/physics/using_jolt_physics.html
• https://docs.godotengine.org/en/stable/tutorials/rendering/renderers.html