游戏引擎 / 系统课时
场景组件迁移到三维角色节点
场景组件迁移到三维角色节点
本节把角色生命值逻辑从二维对象迁移到三维角色,重点不是把 Node2D 全部替换成 Node3D,而是识别真正可共享的配置与生命组件,并为三维碰撞重建适配层。使用相同的两次伤害输入,对比二维和三维对象的生命变化及死亡通知。
学习目标
- 区分与空间维度无关的生命规则和需要重写的碰撞、表现代码。
- 将共享配置与生命组件装配到
CharacterBody3D。 - 用相同伤害用例验证状态变化、信号和死亡次数一致。
把生命规则留在共享层
最大生命值属于只读角色配置 CharacterConfig,当前生命值属于每个角色独立的 HealthComponent。受伤接口 take_damage(amount) 接收非负伤害,计算生命值并发出 health_changed;它不访问 Vector2、Vector3、动画树或碰撞节点。
二维角色可由 Area2D 把命中转换为受伤调用;三维角色必须用 Area3D、CollisionShape3D 和三维空间规则重新实现命中入口。两个适配层遵守相同的受伤契约,但不共享维度专属的形状与空间查询。

用相同输入执行迁移回归
在 Godot 4 新建根节点为 Node3D 的场景,附加以下 main.gd 并运行。脚本生成一个用于逻辑对照的二维对象和一个带胶囊碰撞体、网格的三维角色;两个对象引用同一配置,但各自拥有独立生命状态。三维 Hurtbox3D 是示范命中入口,本次由测试代码直接触发,不依赖实际弹丸。
extends Node3D
class CharacterConfig extends Resource:
@export var max_hp: int = 100
class HealthComponent extends Node:
signal health_changed(previous: int, current: int)
signal died
var hp := 0
func setup(config: CharacterConfig) -> void:
hp = config.max_hp # 从共享配置初始化实例状态
func take_damage(amount: int) -> void:
if amount <= 0 or hp == 0:
return
var previous := hp
hp = maxi(0, hp - amount)
health_changed.emit(previous, hp)
if hp == 0:
died.emit() # 死亡事件只在首次归零时触发
class Hurtbox3D extends Area3D:
var health: HealthComponent
func _ready() -> void:
var hitbox := CollisionShape3D.new()
var capsule := CapsuleShape3D.new()
capsule.radius = 0.42
capsule.height = 1.85
hitbox.shape = capsule
add_child(hitbox)
func receive_hit(amount: int) -> void:
health.take_damage(amount)
func _ready() -> void:
var config := CharacterConfig.new()
var actor_2d := Node2D.new()
add_child(actor_2d)
var hp_2d := HealthComponent.new()
actor_2d.add_child(hp_2d)
hp_2d.setup(config)
var actor_3d := CharacterBody3D.new()
actor_3d.position = Vector3(0, 1, 0)
add_child(actor_3d)
var hitbox := CollisionShape3D.new()
var shape := CapsuleShape3D.new()
shape.radius = 0.4
shape.height = 1.8
hitbox.shape = shape
actor_3d.add_child(hitbox)
var visual := MeshInstance3D.new()
var mesh := CapsuleMesh.new()
mesh.radius = 0.4
mesh.height = 1.8
visual.mesh = mesh
actor_3d.add_child(visual)
var hp_3d := HealthComponent.new()
actor_3d.add_child(hp_3d)
hp_3d.setup(config)
var hurtbox := Hurtbox3D.new()
hurtbox.health = hp_3d
actor_3d.add_child(hurtbox)
hp_2d.health_changed.connect(func(a: int, b: int): print("2D: %d -> %d" % [a, b]))
hp_3d.health_changed.connect(func(a: int, b: int): print("3D: %d -> %d" % [a, b]))
hp_2d.died.connect(func(): print("2D: died"))
hp_3d.died.connect(func(): print("3D: died"))
var camera := Camera3D.new()
camera.position = Vector3(0, 2, 5)
add_child(camera)
camera.look_at(Vector3(0, 1, 0))
camera.current = true
var light := DirectionalLight3D.new()
light.rotation_degrees = Vector3(-40, 30, 0)
add_child(light)
# 使用同一回归用例;只有三维侧经由 Hurtbox3D
for damage in [30, 90]:
hp_2d.take_damage(damage)
hurtbox.receive_hit(damage)预期输出(Godot 输出面板):
2D: 100 -> 70
3D: 100 -> 70
2D: 70 -> 0
2D: died
3D: 70 -> 0
3D: died三维视图可看到胶囊网格;二维对照对象仅用于行为测试,不含二维渲染或碰撞表现。两侧状态互不影响,死亡各触发一次;再次调用 take_damage(10) 不会重复发出 died。
重建空间适配,不复制二维实现
三维角色除了使用 CharacterBody3D,还应单独处理 Vector3 位移、重力与地面检测、三维碰撞层、射线查询和朝向;不能把二维 Area2D 的形状、坐标和检测逻辑直接换一个节点名。真实命中系统应由三维攻击区域或物理查询确认目标后调用 receive_hit(),并检查碰撞层与掩码,避免一个攻击重复记伤。
迁移验收的标准是外部行为契约:给定相同配置、相同伤害序列,生命值变化和死亡通知一致;画面、碰撞与空间查询允许使用完全不同的实现。共享 Resource 只保存配置,绝不把 hp 写回配置,否则两个角色会意外共享运行状态。