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.freequeue_free 释放时,它也将释放它的所有子节点。

分组:节点可以被添加到很多的组中,以方便管理,你可以根据自己游戏的需要来创建类似“敌人”或“收集品”这样的组。见 add_to_groupis_in_groupremove_from_group。加入组后,你可以检索这些组中的所有节点,对它们进行迭代,甚至通过 SceneTree 中的方法调用组内方法。

节点的网络编程:在连接到服务器(或制作服务器,见 ENetMultiplayerPeer)之后,可以使用内置的 RPC(远程过程调用)系统在网络上进行通信。在调用 rpc 时传入方法名,将在本地和所有已连接的对等体中调用对应的方法(对等体=客户端和接受连接的服务器)。为了识别哪个节点收到 RPC 调用,Godot 将使用它的 NodePath(请确保所有对等体上的节点名称相同)。另外,请参阅高级网络教程和相应的演示。

注意:script 属性是 Object 类的一部分,不属于 Node。这个属性暴露的方式和其他属性不同,但提供了 setter 和 getter(见 Object.set_scriptObject.get_script)。

教程

属性

String

editor_description

""

MultiplayerAPI

multiplayer

StringName

name

Node

owner

ProcessMode

process_mode

0

int

process_physics_priority

0

int

process_priority

0

ProcessThreadGroup

process_thread_group

0

int

process_thread_group_order

BitField<ProcessThreadMessages>

process_thread_messages

String

scene_file_path

bool

unique_name_in_owner

false

方法

void

_enter_tree ( ) virtual

void

_exit_tree ( ) virtual

PackedStringArray

_get_configuration_warnings ( ) virtual const

void

_input ( InputEvent event ) virtual

void

_physics_process ( float delta ) virtual

void

_process ( float delta ) virtual

void

_ready ( ) virtual

void

_shortcut_input ( InputEvent event ) virtual

void

_unhandled_input ( InputEvent event ) virtual

void

_unhandled_key_input ( InputEvent event ) virtual

void

add_child ( Node node, bool force_readable_name=false, InternalMode internal=0 )

void

add_sibling ( Node sibling, bool force_readable_name=false )

void

add_to_group ( StringName group, bool persistent=false )

Variant

call_deferred_thread_group ( StringName method, ... ) vararg

Variant

call_thread_safe ( StringName method, ... ) vararg

bool

can_process ( ) const

Tween

create_tween ( )

Node

duplicate ( int flags=15 ) const

Node

find_child ( String pattern, bool recursive=true, bool owned=true ) const

Node[]

find_children ( String pattern, String type="", bool recursive=true, bool owned=true ) const

Node

find_parent ( String pattern ) const

Node

get_child ( int idx, bool include_internal=false ) const

int

get_child_count ( bool include_internal=false ) const

Node[]

get_children ( bool include_internal=false ) const

StringName[]

get_groups ( ) const

int

get_index ( bool include_internal=false ) const

Window

get_last_exclusive_window ( ) const

int

get_multiplayer_authority ( ) const

Node

get_node ( NodePath path ) const

Array

get_node_and_resource ( NodePath path )

Node

get_node_or_null ( NodePath path ) const

Node

get_parent ( ) const

NodePath

get_path ( ) const

NodePath

get_path_to ( Node node, bool use_unique_path=false ) const

float

get_physics_process_delta_time ( ) const

float

get_process_delta_time ( ) const

bool

get_scene_instance_load_placeholder ( ) const

SceneTree

get_tree ( ) const

String

get_tree_string ( )

String

get_tree_string_pretty ( )

Viewport

get_viewport ( ) const

Window

get_window ( ) const

bool

has_node ( NodePath path ) const

bool

has_node_and_resource ( NodePath path ) const

bool

is_ancestor_of ( Node node ) const

bool

is_displayed_folded ( ) const

bool

is_editable_instance ( Node node ) const

bool

is_greater_than ( Node node ) const

bool

is_in_group ( StringName group ) const

bool

is_inside_tree ( ) const

bool

is_multiplayer_authority ( ) const

bool

is_node_ready ( ) const

bool

is_physics_processing ( ) const

bool

is_physics_processing_internal ( ) const

bool

is_processing ( ) const

bool

is_processing_input ( ) const

bool

is_processing_internal ( ) const

bool

is_processing_shortcut_input ( ) const

bool

is_processing_unhandled_input ( ) const

bool

is_processing_unhandled_key_input ( ) const

void

move_child ( Node child_node, int to_index )

void

notify_deferred_thread_group ( int what )

void

notify_thread_safe ( int what )

void

print_orphan_nodes ( ) static

void

print_tree ( )

void

print_tree_pretty ( )

void

propagate_call ( StringName method, Array args=[], bool parent_first=false )

void

propagate_notification ( int what )

void

queue_free ( )

void

remove_child ( Node node )

void

remove_from_group ( StringName group )

void

reparent ( Node new_parent, bool keep_global_transform=true )

void

replace_by ( Node node, bool keep_groups=false )

void

request_ready ( )

Error

rpc ( StringName method, ... ) vararg

void

rpc_config ( StringName method, Variant config )

Error

rpc_id ( int peer_id, StringName method, ... ) vararg

void

set_deferred_thread_group ( StringName property, Variant value )

void

set_display_folded ( bool fold )

void

set_editable_instance ( Node node, bool is_editable )

void

set_multiplayer_authority ( int id, bool recursive=true )

void

set_physics_process ( bool enable )

void

set_physics_process_internal ( bool enable )

void

set_process ( bool enable )

void

set_process_input ( bool enable )

void

set_process_internal ( bool enable )

void

set_process_shortcut_input ( bool enable )

void

set_process_unhandled_input ( bool enable )

void

set_process_unhandled_key_input ( bool enable )

void

set_scene_instance_load_placeholder ( bool load_placeholder )

void

set_thread_safe ( StringName property, Variant value )

void

update_configuration_warnings ( )


信号

child_entered_tree ( Node node )

当子节点 node 进入 SceneTree 时触发,通常是因为该节点进入了树(参见 tree_entered),或者 add_child 已被调用。

该信号在子节点自己的 NOTIFICATION_ENTER_TREEtree_entered 之后触发。


child_exiting_tree ( Node node )

当子节点 node 即将退出 SceneTree 时发出,通常是因为该节点正在退出树(请参阅 tree_exiting),或者因为子节点 node 正在被移除或释放。

当收到该信号时,子节点 node 仍然可以在树内访问。该信号在子节点自己的 tree_exitingNOTIFICATION_EXIT_TREE 之后触发。


child_order_changed ( )

子节点列表发生改变时发出。发生在添加、移动、移除子节点时。


ready ( )

_ready 被调用后,当节点被视为就绪时发出。


renamed ( )

节点位于场景树中,在节点的 name 更改时发出。


replacing_by ( Node node )

当该节点被 node 替换时触发,见 replace_by

这个信号的触发时机在 node 被添加为原父节点的子节点之后,但是在所有原子节点重设父节点为 node 之前


tree_entered ( )

当该节点进入树时触发。

这个信号会在相关的 NOTIFICATION_ENTER_TREE 通知之后触发。


tree_exited ( )

节点退出树并且不再活动后发出。

该信号会在相关的 NOTIFICATION_EXIT_TREE 通知之后发出。


tree_exiting ( )

当节点即将退出树时发出。节点仍然有效。因此,这是反初始化(如果愿意,也可以称之为“析构函数”)的正确位置。

该信号会在节点的 _exit_tree 之后和相关的 NOTIFICATION_EXIT_TREE 之前发出。


枚举

enum ProcessMode:

ProcessMode PROCESS_MODE_INHERIT = 0

从该节点的父节点继承 process_mode。对于根节点来说,这相当于 PROCESS_MODE_PAUSABLE。这是任何新创建的节点的默认设置。

ProcessMode PROCESS_MODE_PAUSABLE = 1

SceneTree.pausedtrue 时停止处理。与 PROCESS_MODE_WHEN_PAUSED 相反。

ProcessMode PROCESS_MODE_WHEN_PAUSED = 2

SceneTree.pausedtrue 时处理。与 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

复制该节点的脚本(与 DUPLICATE_USE_INSTANTIATION 组合时包括祖级脚本)。

DuplicateFlags DUPLICATE_USE_INSTANTIATION = 8

使用 PackedScene.instantiate 进行复制。如果该节点来自磁盘上保存的场景,则会重用 PackedScene.instantiate 作为该节点及其子节点副本的基础。


enum InternalMode:

InternalMode INTERNAL_MODE_DISABLED = 0

该节点不是内部节点。

InternalMode INTERNAL_MODE_FRONT = 1

该节点将被放置在父节点的子节点列表开头,位于所有非内部兄弟节点之前。

InternalMode INTERNAL_MODE_BACK = 2

该节点将被放置在父节点的子节点列表末尾,位于所有非内部兄弟节点之后。


常量

NOTIFICATION_ENTER_TREE = 10

当节点进入 SceneTree 时收到的通知。请参阅 _enter_tree

该通知会在相关 tree_entered 信号之前收到。

NOTIFICATION_EXIT_TREE = 11

当节点即将退出 SceneTree 时收到的通知。请参阅 _exit_tree

该通知会在相关的 tree_exiting 信号之后收到。

NOTIFICATION_MOVED_IN_PARENT = 12

已废弃。不会再发出这个通知。请改用 NOTIFICATION_CHILD_ORDER_CHANGED

NOTIFICATION_READY = 13

当该节点就绪时接收到通知。见 _ready

NOTIFICATION_PAUSED = 14

当节点暂停时收到的通知。请参阅 process_mode

NOTIFICATION_UNPAUSED = 15

当节点取消暂停时收到的通知。请参阅 process_mode

NOTIFICATION_PHYSICS_PROCESS = 16

is_physics_processing 返回 true 时,每个物理帧都会从场景树收到的通知。请参阅 _physics_process

NOTIFICATION_PROCESS = 17

is_processing 返回 true 时,每个渲染帧从场景树收到的通知。请参阅 _process

NOTIFICATION_PARENTED = 18

当节点被设置为另一个节点的子节点时收到的通知(请参阅 add_childadd_sibling)。

注意:这并意味着该节点进入了 SceneTree

NOTIFICATION_UNPARENTED = 19

当父节点在该节点上调用 remove_child 时收到的通知。

注意:这并意味着该节点退出了 SceneTree

NOTIFICATION_SCENE_INSTANTIATED = 20

PackedScene.instantiate 完成时,被新实例化的场景根节点收到的通知。

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

当该节点的 name 或其祖先节点之一的 name 更改时收到的通知。当节点从 SceneTree 中移除时,不会收到该通知。

NOTIFICATION_CHILD_ORDER_CHANGED = 24

子节点列表发生更改时收到的通知。子节点发生添加、移动、删除时列表会发生更改。

NOTIFICATION_INTERNAL_PROCESS = 25

is_processing_internal 返回 true 时,每个渲染帧都会从树中收到的通知。

NOTIFICATION_INTERNAL_PHYSICS_PROCESS = 26

is_physics_processing_internal 返回 true 时,每个物理帧都会从树中收到的通知。

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 系统上按下“返回”按钮)。

仅在 iOS 上实现。

NOTIFICATION_WM_SIZE_CHANGED = 1008

当窗口大小被调整时收到的通知。

注意:只有调整大小的 Window 节点才会收到该通知,并且不会传播到子节点。

NOTIFICATION_WM_DPI_CHANGE = 1009

当屏幕的每英寸点数(DPI)比例发生更改时,从操作系统收到的通知。仅在 macOS 上实现。

NOTIFICATION_VP_MOUSE_ENTER = 1010

当鼠标指针进入 Viewport 的可见区域时收到的通知,可见区域指没有被其他 ControlWindow 遮挡的区域,并且需要 Viewport.gui_disable_inputfalse,与当前是否持有焦点无关。

NOTIFICATION_VP_MOUSE_EXIT = 1011

当鼠标指针离开 Viewport 的可见区域时收到的通知,可见区域指没有被其他 ControlWindow 遮挡的区域,并且需要 Viewport.gui_disable_inputfalse,与当前是否持有焦点无关。

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

TextServer 被更改时收到的通知。


属性说明

String editor_description = ""

  • void set_editor_description ( String value )

  • String get_editor_description ( )

节点的可选描述。当将悬停在编辑器场景面板中的节点上时,它将显示为工具提示。


MultiplayerAPI multiplayer

与该节点关联的 MultiplayerAPI 实例。见 SceneTree.get_multiplayer

注意:将节点重命名或者在树中移动都不会将 MultiplayerAPI 移动至新的路径,你需要手动进行更新。


StringName name

该节点的名称。该名称在同级节点(来自同一父节点的其他子节点)中必须是唯一的。当设置为已有同级节点的名称时,该节点将会自动重命名。

注意:更改名称时,以下字符将被移除:(. : @ / " %)。特别是,@ 字符是为自动生成的名称保留的。另请参阅 String.validate_node_name


Node owner

  • void set_owner ( Node value )

  • Node get_owner ( )

该节点的所有者。所有者必须是该节点的祖先节点。当将所有者节点打包到 PackedScene 中时,它拥有的所有节点也会随之保存。

注意:在编辑器中,不属于场景根的节点通常不会显示在场景面板中,并且会被保存。为了防止这种情况,请记住在调用 add_child 后设置所有者。另见(参见 unique_name_in_owner


ProcessMode process_mode = 0

该节点的处理行为(请参阅 ProcessMode)。要检查该节点是否能够在当前模式和 SceneTree.paused 下进行处理,请使用 can_process