游戏引擎 / 系统课时
把脚本挂到节点并驱动场景
把脚本挂到节点并驱动场景
本课在 Godot 4 中把一段 GDScript 绑定到 3D 节点,让方块持续旋转,并在按住左右方向键时移动。完成后你不仅能看到效果,还能判断脚本运行在哪个节点、何时被调用,以及为什么更新位置时必须考虑帧间时间。
学习目标
- 建立可独立运动的节点层级,并把脚本正确附加到
Node3D。 - 用
_ready()与_process(delta)分别完成初始化和逐帧更新。 - 结合
Input.get_axis()和delta实现可验证的移动与旋转。
搭建可见的 3D 场景
使用 Godot 4.x 新建 3D 场景,按下列步骤建立最小结构:
- 以
Node3D为根节点并命名Main,保存为res://Main.tscn。 - 在
Main下添加Pivot(Node3D);在Pivot下添加MeshInstance3D,将其Mesh设为新建的BoxMesh。可将 BoxMesh 的大小改为(1.5, 0.8, 0.6),使旋转更容易辨认。 - 在
Main下添加Camera3D,位置设为(0, 2, 6)、X 旋转约-15°,让镜头朝向原点;将它设为当前相机。 - 在
Main下添加DirectionalLight3D并适当倾斜,使方块表面具有明暗层次。
Pivot、相机和灯光是同级节点。脚本只控制 Pivot,它的子级方块便跟随运动,但镜头不会一起移动。

把脚本附加到 Pivot
选中 Pivot,使用“附加脚本(Attach Script)”创建 res://Pivot.gd。脚本的 extends Node3D 必须与被附加节点的类型兼容。将代码替换为以下完整示例:
extends Node3D
@export var move_speed: float = 2.0
@export var turn_speed: float = 1.0
func _ready() -> void:
print("Pivot ready")
func _process(delta: float) -> void:
# 工程默认的 UI 左右动作可由方向键触发
var axis: float = Input.get_axis("ui_left", "ui_right")
position.x += axis * move_speed * delta
# 没有按键时仍按时间持续旋转
rotate_y(turn_speed * delta)预期输出:运行 Main.tscn 后,编辑器的“输出(Output)”面板打印一次:
Pivot ready游戏视图中,方块持续绕 Y 轴旋转;按住左方向键向左移动,按住右方向键向右移动,松开后停止平移但仍旋转。若只看到日志而没有方块,先检查 MeshInstance3D 的 Mesh 和相机朝向。
看懂每次更新发生了什么
_ready() 在节点连入正在运行的场景树并准备好后调用,适合初始化;_process(delta) 则随渲染帧重复调用。delta 是距离上一帧经过的秒数,而非固定的 1。把速度乘以 delta,才能让不同帧率下的每秒位移和转角大体一致。
Input.get_axis("ui_left", "ui_right") 汇总两个输入动作,通常得到 -1、0 或 1;新工程默认可用左右方向键触发。如果修改过按键映射,应在“项目 → 项目设置 → 输入映射(Input Map)”中检查动作名称与按键绑定。position.x 是相对父节点的坐标,rotate_y() 的角度单位是弧度,因此 turn_speed 表示每秒旋转多少弧度。
@export 让两个速度显示在检查器中;修改后重新运行,可直接对比效果,不必改代码。若改为移动 CharacterBody3D 等物理角色,应改在 _physics_process() 中处理速度与碰撞,而不是直接套用这里的位置更新方式。
运行验收与排错
按 F6 运行当前场景,确认输出只在启动时出现一次;按左右方向键观察平移,放开后仍能看到旋转,再把 move_speed 从 2.0 改为 4.0 比较移动速度。看不到变化时先确认运行的是 Main.tscn、脚本图标位于 Pivot、输入动作存在;看不到模型时再检查 Mesh、相机和灯光。
脚本与节点之间的绑定关系是本例关键:场景提供对象层级,脚本读取输入和时间并改变节点属性,渲染系统才把这些变化显示出来。