Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
Node¶
继承： Object
派生： AnimationMixer, AudioStreamPlayer, CanvasItem, CanvasLayer, EditorFileSystem, EditorPlugin, EditorResourcePreview, HTTPRequest, InstancePlaceholder, MissingNode, MultiplayerSpawner, MultiplayerSynchronizer, NavigationAgent2D, NavigationAgent3D, Node3D, ResourcePreloader, ShaderGlobalsOverride, SkeletonIK3D, Timer, Viewport, WorldEnvironment
所有场景对象的基类。
描述¶
节点是 Godot 的构建模块。它们可以被指定为另一个节点的子节点，从而形成树状排列。一个给定的节点可以包含任意数量的节点作为子节点，要求所有的兄弟节点（即该节点的直接子节点）的名字唯一。
节点树被称为场景。场景可以被保存到磁盘上，然后被实例化到其他场景中。这使得 Godot 项目的架构和数据模型具有非常高的灵活性。
场景树：SceneTree 包含活动的节点树。当一个节点被添加到场景树中时，它将收到 NOTIFICATION_ENTER_TREE 通知，并触发其 _enter_tree 回调。子节点总是在其父节点之后被添加，即父节点的 _enter_tree 回调将在其子节点的之前被触发。
一旦所有的节点被添加到场景树中，它们就会收到 NOTIFICATION_READY 通知，其各自的 _ready 回调被触发。对于一组节点，_ready 回调是按相反的顺序调用的，从子节点开始，向上移动到父节点。
这意味着，当把一个节点添加到场景树中时，将使用下面的顺序进行回调：父节点的 _enter_tree、子节点的 _enter_tree、子节点的 _ready，最后是父节点的 _ready（对整个场景树进行递归）。
处理：节点可以覆盖“处理”状态，以便它们在每一帧上都收到回调，要求它们进行处理（做一些事情）。普通处理（回调 _process，可以使用 set_process 开关）会尽可能快地发生，并且取决于帧率，所以处理时间 delta（单位为秒）会作为参数传入。物理处理（回调 _physics_process，可以使用 set_physics_process 开关）每秒发生固定次数（默认为 60），对物理引擎相关的代码很有用。
节点也可以处理输入事件。存在 _input 函数时，程序每收到一次输入都会去调用它。在许多情况下，这么做是大材小用了（除非是用于简单的项目），用 _unhandled_input 函数可能更合适；当输入事件没有被其他节点（通常是 GUI Control 节点）处理时，才会调用这个函数，可以确保节点只接收到它该收到的事件。
为了记录场景的层次结构（尤其是在将场景实例化到其他场景时）可以用 owner 属性为节点设置一个“所有者”。它记录的是谁实例化了什么。这在编写编辑器和工具时非常有用。
最后，当一个节点被 Object.free 或 queue_free 释放时，它也将释放它的所有子节点。
分组：节点可以被添加到很多的组中，以方便管理，你可以根据自己游戏的需要来创建类似“敌人”或“收集品”这样的组。见 add_to_group、is_in_group 和 remove_from_group。加入组后，你可以检索这些组中的所有节点，对它们进行迭代，甚至通过 SceneTree 中的方法调用组内方法。
节点的网络编程：在连接到服务器（或制作服务器，见 ENetMultiplayerPeer）之后，可以使用内置的 RPC（远程过程调用）系统在网络上进行通信。在调用 rpc 时传入方法名，将在本地和所有已连接的对等体中调用对应的方法（对等体=客户端和接受连接的服务器）。为了识别哪个节点收到 RPC 调用，Godot 将使用它的 NodePath（请确保所有对等体上的节点名称相同）。另外，请参阅高级网络教程和相应的演示。
注意：script 属性是 Object 类的一部分，不属于 Node。这个属性暴露的方式和其他属性不同，但提供了 setter 和 getter（set_script() 和 get_script()）。
教程¶
属性¶
|
||
|
||
|
||
|
||
|
||
BitField<ProcessThreadMessages> |
||
|
方法¶
信号¶
child_entered_tree ( Node node )
在子节点进入场景树时触发，可以是因为该子节点自行进入，也可以是因为本节点带着该子节点一起进入。
这个信号会在该子节点自身的 NOTIFICATION_ENTER_TREE 和 tree_entered 之后触发。
child_exiting_tree ( Node node )
当一个子节点即将退出场景树时发出，要么是因为它正在被移除或直接释放，要么是因为该节点正在退出树。
当收到这个信号时，子 node 仍然在树中并且有效。该信号在子节点自己的 tree_exiting 和 NOTIFICATION_EXIT_TREE 之后发出。
child_order_changed ( )
子节点列表发生改变时发出。发生在添加、移动、移除子节点时。
ready ( )
当该节点就绪时发出。在 _ready 回调之后发出，遵循相同的规则。
renamed ( )
当该节点被重命名时触发。
replacing_by ( Node node )
当该节点被 node 替换时触发，见 replace_by。
这个信号的触发时机在 node 被添加为原父节点的子节点之后，但是在所有原子节点重设父节点为 node 之前。
tree_entered ( )
当该节点进入树时触发。
这个信号会在相关的 NOTIFICATION_ENTER_TREE 通知之后触发。
tree_exited ( )
当该节点退出树之后触发，并且不再处于活动状态。
tree_exiting ( )
当该节点仍处于活动状态但即将退出树时发出。这是反初始化的正确位置（如果愿意，也可以称之为“析构函数”）。
这个信号会在相关的 NOTIFICATION_EXIT_TREE 通知之前触发。
枚举¶
enum ProcessMode:
ProcessMode PROCESS_MODE_INHERIT = 0
从该节点的父节点继承处理模式。如果是根节点，则等价于 PROCESS_MODE_PAUSABLE。默认值。
ProcessMode PROCESS_MODE_PAUSABLE = 1
SceneTree 暂停时停止处理（取消暂停时处理）。与 PROCESS_MODE_WHEN_PAUSED 相反。
ProcessMode PROCESS_MODE_WHEN_PAUSED = 2
仅在 SceneTree 暂停时处理（取消暂停时不处理）。与 PROCESS_MODE_PAUSABLE 相反。
ProcessMode PROCESS_MODE_ALWAYS = 3
始终处理。始终继续处理，忽略 SceneTree 的 paused 属性。与 PROCESS_MODE_DISABLED 相反。
ProcessMode PROCESS_MODE_DISABLED = 4
从不处理。完全禁用处理，忽略 SceneTree 的 paused 属性。与 PROCESS_MODE_ALWAYS 相反。
enum ProcessThreadGroup:
ProcessThreadGroup PROCESS_THREAD_GROUP_INHERIT = 0
如果 process_thread_group 属性设为这个值，该节点会属于线程组不是继承的父节点（或祖父节点）。详见 process_thread_group。
ProcessThreadGroup PROCESS_THREAD_GROUP_MAIN_THREAD = 1
在主线程上处理该节点（以及设为继承的子节点）。详见 process_thread_group。
ProcessThreadGroup PROCESS_THREAD_GROUP_SUB_THREAD = 2
在子线程上处理该节点（以及设为继承的子节点）。详见 process_thread_group。
flags ProcessThreadMessages:
ProcessThreadMessages FLAG_PROCESS_THREAD_MESSAGES = 1
ProcessThreadMessages FLAG_PROCESS_THREAD_MESSAGES_PHYSICS = 2
ProcessThreadMessages FLAG_PROCESS_THREAD_MESSAGES_ALL = 3
enum DuplicateFlags:
DuplicateFlags DUPLICATE_SIGNALS = 1
复制该节点的信号。
DuplicateFlags DUPLICATE_GROUPS = 2
复制节点的组。
DuplicateFlags DUPLICATE_SCRIPTS = 4
复制该节点的脚本。
DuplicateFlags DUPLICATE_USE_INSTANTIATION = 8
使用实例化进行复制。
实例与原件保持链接，因此当原件发生变化时，实例也会发生变化。
enum InternalMode:
InternalMode INTERNAL_MODE_DISABLED = 0
该节点不是内部节点。
InternalMode INTERNAL_MODE_FRONT = 1
该节点将被放置在父节点的节点列表开头，在所有非内部兄弟节点之前。
InternalMode INTERNAL_MODE_BACK = 2
该节点将被放置在父节点的节点列表末尾，在所有非内部兄弟节点之后。
常量¶
NOTIFICATION_ENTER_TREE = 10
当该节点进入 SceneTree 时收到的通知。
这个通知会在相关的 tree_entered 之前发出。
NOTIFICATION_EXIT_TREE = 11
当该节点即将退出 SceneTree 时收到的通知。
这个通知会在相关的 tree_exiting 之后发出。
NOTIFICATION_MOVED_IN_PARENT = 12
已废弃。不会再发出这个通知。请改用 NOTIFICATION_CHILD_ORDER_CHANGED。
NOTIFICATION_READY = 13
当该节点就绪时接收到通知。见 _ready。
NOTIFICATION_PAUSED = 14
当该节点被暂停时接收到的通知。
NOTIFICATION_UNPAUSED = 15
当该节点被取消暂停时收到的通知。
NOTIFICATION_PHYSICS_PROCESS = 16
当设置了 physics process 标志时，每一帧都会收到的通知（见 set_physics_process）。
NOTIFICATION_PROCESS = 17
当设置了 process 标志时，每一帧都会收到的通知（见 set_process）。
NOTIFICATION_PARENTED = 18
当一个节点被设置为另一个节点的子节点时收到该通知。
注意：这并不意味着一个节点进入了 SceneTree。
NOTIFICATION_UNPARENTED = 19
当该节点失去父节点时收到的通知（父节点将其从子节点列表中删除）。
NOTIFICATION_SCENE_INSTANTIATED = 20
当场景被实例化时，该场景的所有者收到的通知。
NOTIFICATION_DRAG_BEGIN = 21
当拖拽操作开始时收到的通知。所有节点都会收到此通知，而不仅仅是被拖动的节点。
可以通过拖动提供拖动数据的 Control（见 Control._get_drag_data），或使用 Control.force_drag 来触发。
请使用 Viewport.gui_get_drag_data 获取拖动数据。
NOTIFICATION_DRAG_END = 22
当拖拽操作结束时收到的通知。
请使用 Viewport.gui_is_drag_successful 检查拖放是否成功。
NOTIFICATION_PATH_RENAMED = 23
当该节点或其祖级的名称被更改时收到的通知。当节点从场景树中移除，稍后被添加到另一个父节点时，不会收到此通知。
NOTIFICATION_CHILD_ORDER_CHANGED = 24
子节点列表发生更改时收到的通知。子节点发生添加、移动、删除时列表会发生更改。
NOTIFICATION_INTERNAL_PROCESS = 25
当设置了内部处理标志时，每一帧都会收到的通知（见 set_process_internal）。
NOTIFICATION_INTERNAL_PHYSICS_PROCESS = 26
当设置了内部物理处理标志时，每一帧都会收到的通知（见 set_physics_process_internal）。
NOTIFICATION_POST_ENTER_TREE = 27
当该节点就绪，在收到 NOTIFICATION_READY 之前收到的通知。与后者不同，该节点每次进入树时都会发送，而不是只发送一次。
NOTIFICATION_DISABLED = 28
当该节点被禁用时收到的通知。见 PROCESS_MODE_DISABLED。
NOTIFICATION_ENABLED = 29
当该节点被禁用后又再次被启用时收到的通知。见 PROCESS_MODE_DISABLED。
NOTIFICATION_EDITOR_PRE_SAVE = 9001
在编辑器中保存有节点的场景之前收到的通知。这个通知只在 Godot 编辑器中发送，不会出现在导出的项目中。
NOTIFICATION_EDITOR_POST_SAVE = 9002
在编辑器中保存有节点的场景后立即收到通知。这个通知只在 Godot 编辑器中发送，在导出的项目中不会出现。
NOTIFICATION_WM_MOUSE_ENTER = 1002
鼠标进入窗口时收到的通知。
为内嵌窗口实现，并在桌面和 Web 平台上实现。
NOTIFICATION_WM_MOUSE_EXIT = 1003
鼠标离开窗口时收到的通知。
为内嵌窗口实现，并在桌面和 Web 平台上实现。
NOTIFICATION_WM_WINDOW_FOCUS_IN = 1004
当该节点的父 Window 获得焦点时收到的通知。可能是在同一引擎实例的两个窗口之间的焦点变化，也可能是从操作系统桌面或第三方应用程序切换到游戏的某个窗口（在这种情况下，还会发出 NOTIFICATION_APPLICATION_FOCUS_IN）。
Window 节点会在获得焦点时收到该通知。
NOTIFICATION_WM_WINDOW_FOCUS_OUT = 1005
当该节点的父 Window 失去焦点时收到的通知。可能是在同一引擎实例的两个窗口之间的焦点变化，也可能是从游戏的某个窗口切换到操作系统桌面或第三方应用程序（在这种情况下，还会发出 NOTIFICATION_APPLICATION_FOCUS_OUT）。
Window 节点会在失去焦点时收到该通知。
NOTIFICATION_WM_CLOSE_REQUEST = 1006
当发出关闭请求时，从操作系统收到的通知（例如使用“关闭”按钮或按下 Alt + F4 关闭窗口时）。
在桌面平台上实现。
NOTIFICATION_WM_GO_BACK_REQUEST = 1007
当发出返回请求时，从操作系统收到的通知（例如在 Android 系统上按下“返回”按钮）。
仅限 Android 平台。
NOTIFICATION_WM_SIZE_CHANGED = 1008
当窗口大小发生改变时，从操作系统收到的通知。
NOTIFICATION_WM_DPI_CHANGE = 1009
当屏幕的 DPI 发生更改时，从操作系统受到的通知。仅在 macOS 上实现。
NOTIFICATION_VP_MOUSE_ENTER = 1010
当鼠标指针进入 Viewport 的可见区域时收到的通知，可见区域指没有被其他 Control 和 Window 遮挡的区域，并且需要 Viewport.gui_disable_input 为 false，与当前是否持有焦点无关。
NOTIFICATION_VP_MOUSE_EXIT = 1011
当鼠标指针离开 Viewport 的可见区域时收到的通知，可见区域指没有被其他 Control 和 Window 遮挡的区域，并且需要 Viewport.gui_disable_input 为 false，与当前是否持有焦点无关。
NOTIFICATION_OS_MEMORY_WARNING = 2009
当应用程序超过其分配的内存时，从操作系统收到的通知。
仅限 iOS 平台。
NOTIFICATION_TRANSLATION_CHANGED = 2010
当翻译可能发生变化时收到的通知。会在用户改变区域设置时触发。可以用来响应语言的变化，例如实时改变 UI 字符串。可配合内置的翻译支持使用，比如 Object.tr。
NOTIFICATION_WM_ABOUT = 2011
当发出“关于”信息请求时，从操作系统收到的通知。
仅限 macOS 平台。
NOTIFICATION_CRASH = 2012
当引擎即将崩溃时，从Godot的崩溃处理程序收到的通知。
如果崩溃处理程序被启用，这只会在桌面平台上实现。
NOTIFICATION_OS_IME_UPDATE = 2013
当输入法引擎发生更新时，从操作系统收到的通知（例如，IME 光标位置或组成字符串的变化）。
仅限 macOS 平台。
NOTIFICATION_APPLICATION_RESUMED = 2014
当应用程序恢复时，从操作系统收到的通知。
仅限 Android 平台。
NOTIFICATION_APPLICATION_PAUSED = 2015
当应用程序暂停时，从操作系统收到的通知。
仅限 Android 平台。
NOTIFICATION_APPLICATION_FOCUS_IN = 2016
当应用程序获得焦点时从操作系统收到的通知，即焦点将从操作系统桌面或第三方应用程序更改为 Godot 实例的任何一个打开窗口时。
在桌面平台上被实现。
NOTIFICATION_APPLICATION_FOCUS_OUT = 2017
当应用程序失去焦点时从操作系统收到通知，即焦点将从 Godot 实例的任何一个打开窗口，更改为操作系统桌面或第三方应用程序时。
在桌面平台上被实现。
NOTIFICATION_TEXT_SERVER_CHANGED = 2018
文本服务器被更改时，收到的通知。
属性说明¶
String editor_description = ""
为该节点添加自定义描述。该节点在编辑器的场景树中处于悬停状态时，该描述将显示在工具提示中。
MultiplayerAPI multiplayer
MultiplayerAPI get_multiplayer ( )
与该节点关联的 MultiplayerAPI 实例。见 SceneTree.get_multiplayer。
注意：将节点重命名或者在树中移动都不会将 MultiplayerAPI 移动至新的路径，你需要手动进行更新。
StringName name
void set_name ( StringName value )
StringName get_name ( )
该节点的名称。这个名称在兄弟节点（来自同一父节点的其他子节点）中是唯一的。当设置为现有名称时，节点将自动重命名。
注意：自动生成的名称可能包含 @ 字符，在使用 add_child 时保留该字符用于唯一名称。手动设置名称时，将删除任何 @。
Node owner
该节点的所有者。节点的所有者可以是任何祖先节点（即父节点、祖父节点等沿场景树向上的节点）。也就是说，应该在设置所有者之前调用 add_child，这样才能存在父子关系。（通过 PackedScene）保存节点时，它拥有的所有节点也会随之保存。这样就可以创建复杂的场景树，能够进行实例化和子实例化。
注意：如果想要将子节点持久化进 PackedScene，除了调用 add_child 之外还必须设置 owner。通常在工具脚本和编辑器插件中会用到。如果将新节点添加到了场景树中但没有将场景树中的祖先设置为所有者，那么这个节点在 2D/3D 视图中可见，但在场景树中不可见（也不会在打包或保存时进行持久化）。
ProcessMode process_mode = 0
void set_process_mode ( ProcessMode value )
ProcessMode get_process_mode ( )
可用于暂停或取消暂停该节点，也可以让该节点根据 SceneTree 来暂停，还可以让它继承父级的处理模式（默认）。
int process_physics_priority = 0
与 process_priority 类似，但是作用于 NOTIFICATION_PHYSICS_PROCESS、_physics_process 以及内部版本。
int process_priority = 0
该节点在已启用的处理回调（即 NOTIFICATION_PROCESS、NOTIFICATION_PHYSICS_PROCESS 及其内部对应物）的执行顺序中的优先级。进程优先级值较低的节点将首先执行其处理回调。
ProcessThreadGroup process_thread_group = 0
void set_process_thread_group ( ProcessThreadGroup value )
ProcessThreadGroup get_process_thread_group ( )
设置这个节点的处理线程组（基本上就是在主线程还是子线程中接收 NOTIFICATION_PROCESS、NOTIFICATION_PHYSICS_PROCESS、_process、_physics_process 以及这些回调的内部版本）。
默认情况下线程组为 PROCESS_THREAD_GROUP_INHERIT，表示这个节点属于和父节点一样的线程组。同一线程组中的节点会一起处理，独立于其他线程组（由 process_thread_group_order 决定）。如果设为 PROCESS_THREAD_GROUP_SUB_THREAD，则该线程组会在子线程（非主线程）中执行，否则设为 PROCESS_THREAD_GROUP_MAIN_THREAD 就会在主线程中处理。如果父节点和先祖节点都没有设置为非继承，则该节点属于默认线程组。默认分组在主线程中处理，分组顺序为 0。
在子线程中处理时，线程组之外的大多数函数都禁止访问（调试模式下会报错）。请使用 Object.call_deferred、call_thread_safe、call_deferred_thread_group 等方法与主线程（或其他线程组）通信。
线程组更好的理解方式是，非 PROCESS_THREAD_GROUP_INHERIT 的节点都会将设为继承的子节点（以及后续子孙节点）纳入它的处理线程组。这样该分组中的节点就会一起处理，包括包含它们的节点。
int process_thread_group_order
修改处理线程组的顺序。顺序取值较小的分组会在较大的分组前处理。例如，可以让大量的节点先在子线程中处理，然后另一组节点要在主线程中获取它们的处理结果。
BitField<ProcessThreadMessages> process_thread_messages
void set_process_thread_messages ( BitField<ProcessThreadMessages> value )