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


int process_physics_priority = 0

  • void set_physics_process_priority ( int value )

  • int get_physics_process_priority ( )

process_priority 类似,但是作用于 NOTIFICATION_PHYSICS_PROCESS_physics_process 以及内部版本。


int process_priority = 0

  • void set_process_priority ( int value )

  • int get_process_priority ( )

处理回调(_process_physics_process、和内部处理)的节点执行顺序。无论树顺序如何,优先级值较低的节点将先调用其处理回调。


ProcessThreadGroup process_thread_group = 0

设置这个节点的处理线程组(基本上就是在主线程还是子线程中接收 NOTIFICATION_PROCESSNOTIFICATION_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_deferredcall_thread_safecall_deferred_thread_group 等方法与主线程(或其他线程组)通信。

线程组更好的理解方式是,非 PROCESS_THREAD_GROUP_INHERIT 的节点都会将设为继承的子节点(以及后续子孙节点)纳入它的处理线程组。这样该分组中的节点就会一起处理,包括包含它们的节点。


int process_thread_group_order

  • void set_process_thread_group_order ( int value )

  • int get_process_thread_group_order ( )

修改处理线程组的顺序。顺序取值较小的分组会在较大的分组前处理。例如,可以让大量的节点先在子线程中处理,然后另一组节点要在主线程中获取它们的处理结果。


BitField<ProcessThreadMessages> process_thread_messages

设置当前线程组是否会在线程中处理消息(调用 call_deferred_thread_group),以及是否需要在常规处理和物理处理回调中接收消息。


String scene_file_path

  • void set_scene_file_path ( String value )

  • String get_scene_file_path ( )

原始场景的文件路径(如果节点已从 PackedScene 文件完成实例化)。只有场景根节点包含该文件路径。


bool unique_name_in_owner = false

  • void set_unique_name_in_owner ( bool value )

  • bool is_unique_name_in_owner ( )

如果为 true,则可以从共享相同 owner 的任意节点或从 owner 本身访问该节点,并可在 get_node 中使用特殊的 %Name 语法。

注意:如果具有相同 owner 的另一个节点与该节点共享相同的 name,则另一个节点将不可再作为唯一节点名称进行访问。


方法说明

void _enter_tree ( ) virtual

当节点进入 SceneTree 时调用(例如实例化时、场景改变时、或者在脚本中调用 add_child 后)。如果节点有子节点,则首先调用它的 _enter_tree 回调函数,然后再调用子节点的回调函数。

对应于 Object._notification 中的 NOTIFICATION_ENTER_TREE 通知。


void _exit_tree ( ) virtual

当节点即将离开 SceneTree 时被调用(例如,在释放、场景改变或在脚本中调用 remove_child 后)。如果该节点有子节点,它的 _exit_tree 回调将在所有子节点离开树后被最后调用。

对应于 Object._notification 中的 NOTIFICATION_EXIT_TREE 通知和 tree_exiting 信号。要在节点已经离开活动树时得到通知,请连接到 tree_exited


PackedStringArray _get_configuration_warnings ( ) virtual const

如果覆盖这个方法的脚本是 tool 脚本,那么这个函数所返回的数组中的元素会在“场景”面板中显示为警告。

返回空数组不会生成警告。

这个节点的警告需要更新时,请调用 update_configuration_warnings

@export var energy = 0:
    set(value):
        energy = value
        update_configuration_warnings()

func _get_configuration_warnings():
    if energy < 0:
        return ["Energy 必须大于等于 0。"]
    else:
        return []

void _input ( InputEvent event ) virtual

有输入事件时会被调用。输入事件会沿节点树向上传播,直到有节点将其消耗。

只有在启用输入处理时才会被调用,如果该方法被重写则会自动启用,可以使用 set_process_input 进行切换。

要消耗输入事件,阻止它进一步传播到其他节点,可以调用 Viewport.set_input_as_handled

对于游戏输入,_unhandled_input_unhandled_key_input 通常更适合,因为它们允许 GUI 首先拦截事件。

注意:仅当该节点存在于场景树中时(即不是孤立节点),此方法才会被调用。


void _physics_process ( float delta ) virtual

在主循环的物理处理步骤中被调用。物理处理意味着帧率与物理同步,即 delta 变量应该是常量。 delta 的单位是秒。

只有当物理处理被启用时才会被调用,如果这个方法被重写,就会自动被调用,并且可以使用 set_physics_process 进行切换。

对应于 Object._notification 中的 NOTIFICATION_PHYSICS_PROCESS 通知。

注意:这个方法只有在当节点存在于场景树中时才会被调用(也就是说,如果它不是孤立节点)。


void _process ( float delta ) virtual

在主循环的处理步骤中被调用。处理发生在每一帧,并且尽可能快,所以从上一帧开始的 delta 时间不是恒定的。delta 的单位是秒。

只有在启用处理的情况下才会被调用,如果这个方法被重写,会自动进行处理,可以用 set_process 来开关。

对应于 Object._notification 中的 NOTIFICATION_PROCESS 通知。

注意:这个方法只有在节点存在于场景树中时才会被调用(也就是说,如果它不是孤立节点)。


void _ready ( ) virtual

当节点“就绪”时被调用,即当节点及其子节点都已经进入场景树时。如果该节点有子节点,将首先触发子节点的 _ready 回调,稍后父节点将收到就绪通知。

对应 Object._notification 中的 NOTIFICATION_READY 通知。另请参阅用于变量的 @onready 注解。

通常用于初始化。对于更早的初始化,可以使用 Object._init。另见 _enter_tree

注意:该方法对于每个节点可能仅调用一次。从场景树中移除一个节点后,并再次添加该节点时,将会第二次调用 _ready。这时可以通过使用 request_ready,它可以在再次添加节点之前的任何地方被调用。


void _shortcut_input ( InputEvent event ) virtual

当一个 InputEventKeyInputEventShortcut,尚未被 _input 或任何 GUI Control 项使用时调用。这是在 _unhandled_key_input_unhandled_input 之前调用的。输入事件通过节点树向上传播,直到一个节点消耗它。

它仅在启用快捷键处理时调用,如果此方法被覆盖,则会自动调用,并且可以使用 set_process_shortcut_input 进行开关。

要消耗输入事件,并阻止它进一步传播到其他节点,可以调用 Viewport.set_input_as_handled

此方法可用于处理快捷键。如果是常规的 GUI 事件,请改用 _input。游戏事件通常应该使用 _unhandled_input_unhandled_key_input 处理。

注意:仅当该节点存在于场景树中(即它不是一个孤立节点)时,此方法才会被调用。


void _unhandled_input ( InputEvent event ) virtual

当一个 InputEvent 尚未被 _input 或任何 GUI Control 项消耗时调用。这是在 _shortcut_input_unhandled_key_input 之后调用的。输入事件通过节点树向上传播,直到一个节点消耗它。

只有在未处理的输入处理被启用时,才会被调用,如果该方法被重写,则会自动被调用,并且可以使用 set_process_unhandled_input 进行切换。

要消耗输入事件,并阻止它进一步传播到其他节点,可以调用 Viewport.set_input_as_handled

对于游戏输入,这个方法通常比 _input 更合适,因为 GUI 事件需要更高的优先级。对于键盘快捷键,请考虑改用 _shortcut_input,因为是在这个方法之前调用的。最后,如果要处理键盘事件,那么出于性能方面的原因请考虑使用 _unhandled_key_input

注意:仅当该节点存在于场景树中(即不是孤立节点)时,该方法才会被调用。


void _unhandled_key_input ( InputEvent event ) virtual

InputEventKey 没有被 _input 或任何 GUI Control 项目消耗时调用。这是在 _shortcut_input 之后、_unhandled_input 之前调用的。输入事件通过节点树向上传播,直到某个节点将其消耗。

只有在启用了未处理按键输入处理时才会被调用,如果覆盖了这个方法就会自动启用,并且可以用 set_process_unhandled_key_input 来开关。

要消耗输入事件并阻止它进一步传播到其他节点,可以调用 Viewport.set_input_as_handled

在处理快捷键后,此方法可用于使用 AltAlt + CtrlAlt + Shift 修饰符处理 Unicode 字符输入。

对于游戏输入,这和 _unhandled_input 通常比 _input 更适合,因为应该先处理 GUI 事件。该方法的性能也比 _unhandled_input 更好,因为 InputEventMouseMotion 等无关事件会被自动过滤。

注意:只有当节点存在于场景树中(即不是孤立节点)时,该方法才会被调用。


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

node 添加为子节点。节点可以有任意数量的子节点,但子节点的名称必须唯一。删除父节点时会自动删除子节点,因此可以通过删除最顶层的节点来删除整个场景。

如果 force_readable_nametrue,则将提高所添加的 node 的可读性。如果尚未命名,node 将重命名为它的类型,如果存在 name 相同的兄弟节点,则会添加合适的数字后缀。这个操作很慢。因此,建议将其保留为 false,在这两种情况下会分配包含 @ 的虚拟名称。

如果 internal 不同于 INTERNAL_MODE_DISABLED,则该子节点将被添加为内部节点。get_children 等方法会忽略这些节点,除非它们的参数 include_internaltrue。这种功能的设计初衷是对用户隐藏内部节点,这样用户就不会意外删除或修改这些节点。部分 GUI 节点会使用这个功能,例如 ColorPicker。可用的模式见 InternalMode

注意:如果 node 已经有父节点,则该方法会失败。请先使用 remove_childnode 从其当前父节点中移除。例如:

var child_node = get_child(0)
if child_node.get_parent():
    child_node.get_parent().remove_child(child_node)
add_child(child_node)

如果你需要将子节点添加到子节点列表中特定节点的下方,请使用 add_sibling 而不是该方法。

注意:如果想让子节点持久化到某个 PackedScene 的,除了调用 add_child 之外,还必须设置 owner。通常在工具脚本编辑器插件中会用到。如果在没有设置 owner,只调用了 add_child,则新添加的 Node 在场景树中将不可见,但在 2D/3D 视图中却是可见的。


void add_sibling ( Node sibling, bool force_readable_name=false )

将一个 sibling 节点添加到该节点的父节点,并将该添加的同级节点移动到该节点的正下方。

如果 force_readable_nametrue,则提高添加的 sibling 的可读性。如果没有命名,sibling 将被重命名为它的类型,如果它与一个同级节点共享 name,则添加一个更合适的数字后缀。这个操作很慢。因此,建议将其保留为 false,这会在两种情况下分配一个以 @ 为特色的虚拟名称。

如果不需要将该子节点添加到子列表中特定节点的下方,请使用 add_child 而不是该方法。

注意:如果这个节点是内部的,则添加的同级节点也将是内部的(参见 add_childinternal 参数)。


void add_to_group ( StringName group, bool persistent=false )

将该节点加入 group 分组。使用分组可以很方便地组织部分节点,例如将敌人加入 "enemies" 分组、将收集品加入 "collectables" 分组。注意事项见下文,以及 SceneTree 中相关的分组方法。

如果 persistenttrue,则保存 PackedScene 时会存储该分组。在“节点”面板中创建、显示的分组都能够进行持久化。

注意:为了提升性能,并不保证分组名称的顺序,每次运行项目可能会不同。因此请不要依赖分组的顺序。

注意:不再场景树中时,SceneTree 的分组方法无法正常工作(见 is_inside_tree)。


Variant call_deferred_thread_group ( StringName method, ... ) vararg

这个函数类似于 Object.call_deferred,但是会在处理节点线程组时进行调用。如果节点线程组在子线程中处理,那么调用就会在该线程中进行,时机为 NOTIFICATION_PROCESSNOTIFICATION_PHYSICS_PROCESS_process_physics_process,或者对应的内部版本之前。


Variant call_thread_safe ( StringName method, ... ) vararg

这个函数能够确保调用成功,无论是否从线程中调用。如果是从不允许调用该函数的线程中调用的,那么调用就会变成延迟调用。否则就会直接调用。


bool can_process ( ) const

如果节点可以从 SceneTreeViewport 接收处理通知和输入回调(NOTIFICATION_PROCESS_input 等),则返回 true。该值取决于当前的 process_modeSceneTree.paused。如果节点不在树内,则返回 false


Tween create_tween ( )

新建 Tween 并将其绑定到这个节点。

与如下操作等价:

get_tree().create_tween().bind_node(self)

该 Tween 将在下一个处理帧或物理帧时自动开始(取决于 TweenProcessMode)。


Node duplicate ( int flags=15 ) const

复制该节点,返回一个新节点,其中包含从原始节点复制的所有属性、信号和组。可以通过 flags 调整该行为(请参阅 DuplicateFlags)。

注意:对于附带有 Script 的节点,如果 Object._init 已使用所需参数定义,则复制的节点将不会有 Script


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

查找该节点的后代节点中,其 namepattern 匹配的第一个节点。如果找不到匹配项,则返回 null。匹配是通过 String.match 针对节点名称完成的,而是针对其路径。因此,它区分大小写,"*" 匹配零个或多个字符,"?" 匹配任意单个字符。

如果 recursivefalse,则仅检查该节点的直接子节点。节点按树顺序检查,因此首先检查该节点的第一个直接子节点,然后检查它自己的直接子节点,依此类推;然后移动到第二个直接子节点,依此类推。内部子级也包含在该搜索中(请参阅 add_child 中的 internal 参数)。

如果 ownedtrue,则仅检查具有有效 owner 节点的后代。

注意:该方法可能非常慢。考虑将找到的节点的引用存储在变量中。或者,使用唯一名称调用 get_node(请参阅 unique_name_in_owner)。

注意:要查找匹配一个模式或类类型的所有后代节点,请参阅 find_children


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

查找该节点的后代节点中,其名称与 pattern 匹配的所有节点。如果找不到匹配项,则返回空 Array。匹配是通过 String.match 针对节点名称完成的,而是针对其路径。因此,它区分大小写,"*" 匹配零个或多个字符,"?" 匹配任意单个字符。

如果 type 不为空,则仅包含从 type 继承的后代节点(请参阅 Object.is_class)。

如果 recursivefalse,则仅检查该节点的直接子节点。节点按树顺序检查,因此首先检查该节点的第一个直接子节点,然后检查它自己的直接子节点,依此类推;然后移动到第二个直接子节点,依此类推。内部子级也包含在该搜索中(请参阅 add_child 中的 internal 参数)。

如果 ownedtrue,则仅检查具有有效 owner 节点的后代。

注意:该方法可能非常慢。考虑将找到的节点的引用存储在变量中。

注意:如果只想查找匹配一个模式的单个后代节点,请参阅 find_child


Node find_parent ( String pattern ) const

查找该节点的祖先节点中,其 namepattern 匹配的第一个节点。如果找不到匹配项,则返回 null。匹配是通过 String.match 完成的。因此,它区分大小写,"*" 匹配零个或多个字符,"?" 匹配任意单个字符。另见 find_childfind_children

注意: 由于该方法在场景树中向上遍历,因此在大型、深度嵌套的节点中可能会很慢。考虑将找到的节点的引用存储在变量中。或者,使用唯一名称调用 get_node(请参阅 unique_name_in_owner)。


Node get_child ( int idx, bool include_internal=false ) const

通过索引获取子节点。每个子节点都有一个相对于其同级节点的索引(请参阅 get_index)。第一个子节点位于索引 0 处。负值也可用于从列表末尾开始。该方法可以与 get_child_count 结合使用来迭代该节点的子节点。如果给定索引处不存在子节点,则该方法返回 null 并生成一个错误。

如果 include_internalfalse,则忽略内部子节点(请参阅 add_childinternal 参数)。

# 假设以下是该节点的子节点(按顺序):
# 第一、中间、最后。

var a = get_child(0).name  # a 是 “第一”
var b = get_child(1).name  # b 是 “中间”
var b = get_child(2).name  # b 是 “最后”
var c = get_child(-1).name # c 是 “最后”

注意:要通过 NodePath 获取节点,请使用 get_node


int get_child_count ( bool include_internal=false ) const

返回该节点的子节点的数量。

如果 include_internalfalse ,则不计算内部子节点(见 add_childinternal 参数)。


Node[] get_children ( bool include_internal=false ) const

返回该节点的所有子节点到一个 Array 内。

如果 include_internalfalse,则从返回的数组中排除内部子节点(见 add_childinternal 参数)。


StringName[] get_groups ( ) const

返回该节点已被添加到的分组的名称的 Array

注意:为了提高性能,保证分组名称的顺序,并且在项目运行之间可能会有所不同。因此,不要依赖分组顺序。

注意:该方法还可能返回一些以下划线(_)开头的分组名称。这些名称被引擎内部使用。为避免冲突,请勿使用以下划线开头的自定义分组。要排除内部分组,请参阅以下代码片段:

# 仅存储节点的非内部分组(作为一个 StringNames 数组)。
var non_internal_groups = []
for group in get_groups():
    if not str(group).begins_with("_"):
        non_internal_groups.push_back(group)

int get_index ( bool include_internal=false ) const

返回该节点在其同级节点中的顺序。第一个节点的索引是 0。另见 get_child

如果 include_internalfalse,则返回的索引会忽略内部子节点。第一个非内部子节点的索引为 0(见 add_childinternal 参数)。


Window get_last_exclusive_window ( ) const

返回包含该节点的 Window,或者是从包含该节点的窗口开始的窗口链中最近的独占子项。


int get_multiplayer_authority ( ) const

返回这个节点多人游戏控制者的对等体 ID。见 set_multiplayer_authority


Node get_node ( NodePath path ) const

获取一个节点。NodePath 可以是到一个节点的相对路径(从该节点开始)或绝对路径(从 SceneTree.root 开始)。如果 path 未指向一个有效节点,则会生成错误并返回 null。尝试访问返回值上的方法将导致“尝试在一个 null 实例上调用 <method>。”错误。

注意:通过绝对路径获取,仅在节点位于场景树内部时有效(参见 is_inside_tree)。

示例:假设从以下树内的 Character 节点调用该方法:

┖╴root
   ┠╴Character (you are here!)
     ┠╴Sword
     ┖╴Backpack
        ┖╴Dagger
   ┠╴MyGame
   ┖╴Swamp
      ┠╴Alligator
      ┠╴Mosquito
      ┖╴Goblin

以下调用将返回一个有效节点:

get_node("Sword")
get_node("Backpack/Dagger")
get_node("../Swamp/Alligator")
get_node("/root/MyGame")

Array get_node_and_resource ( NodePath path )

获取节点及其由 NodePath 子名指定的嵌套最深的资源。返回一个大小为 3Array,其中:

  • 元素 0Node,如果找不到,则为 null

  • 元素 1 是子名中最后嵌套的 Resource,如果找不到,则为 null

  • 元素 2 是剩余的 NodePath,引用一个已有的非 Resource 属性(请参阅 Object.get_indexed)。

示例:假设子节点的 Sprite2D.texture 已被分配了一个AtlasTexture

var a = get_node_and_resource("Area2D/Sprite2D")
print(a[0].name) # 打印 Sprite2D
print(a[1])      # 打印 <null>
print(a[2])      # 打印 ^""

var b = get_node_and_resource("Area2D/Sprite2D:texture:atlas")
print(b[0].name)        # 打印 Sprite2D
print(b[1].get_class()) # 打印 AtlasTexture
print(b[2])             # 打印 ^""

var c = get_node_and_resource("Area2D/Sprite2D:texture:atlas:region")
print(c[0].name)        # 打印 Sprite2D
print(c[1].get_class()) # 打印 AtlasTexture
print(c[2])             # 打印 ^":region"

Node get_node_or_null ( NodePath path ) const

通过 NodePath 获取节点。类似于 get_node,但在 path 没有指向有效节点时不会生成错误。


Node get_parent ( ) const

返回该节点的父节点,如果该节点没有父节点,则返回 null


NodePath get_path ( ) const

返回该节点相对于 SceneTree.root 的绝对路径。如果该节点不在场景树内部,则该方法失败并返回空的 NodePath


NodePath get_path_to ( Node node, bool use_unique_path=false ) const

返回从该节点到指定节点 node 的相对 NodePath。这两个节点都必须在同一个 SceneTree 中,否则该方法将失败并返回一个空的 NodePath

如果 use_unique_pathtrue,则返回考虑该节点唯一名称的最短路径(请参阅 unique_name_in_owner)。

注意:如果你获取了从唯一节点开始的相对路径,则由于添加了唯一节点的名称,该路径可能比普通的相对路径长。


float get_physics_process_delta_time ( ) const

返回自上次物理回调以来经过的时间(单位为秒)。该值与 _physics_processdelta 参数相同,并且除非 Engine.physics_ticks_per_second 被更改,否则这在运行时通常是恒定的。另请参阅 NOTIFICATION_PHYSICS_PROCESS


float get_process_delta_time ( ) const

返回自上次处理回调以来经过的时间(单位为秒)。该值与 _processdelta 参数相同,并且可能因帧而异。另请参阅 NOTIFICATION_PROCESS


bool get_scene_instance_load_placeholder ( ) const

如果该节点是一个实例加载占位符,则返回 true。见 InstancePlaceholderset_scene_instance_load_placeholder


SceneTree get_tree ( ) const

返回包含该节点的 SceneTree。如果该节点不在场景树内,则会生成错误并返回 null。另见 is_inside_tree


String get_tree_string ( )

将树以 String 的形式返回。主要用于调试。这个版本显示相对于当前节点的路径,适合复制/粘贴到 get_node 函数中。也可以用于游戏中的 UI/UX。

示例输出:

TheGame
TheGame/Menu
TheGame/Menu/Label
TheGame/Menu/Camera2D
TheGame/SplashScreen
TheGame/SplashScreen/Camera2D

String get_tree_string_pretty ( )

类似于 get_tree_string,会将树以 String 的形式返回。这个版本使用的是一种更加图形化的呈现方式,类似于在“场景”面板中显示的内容。非常适合检查较大的树。

输出示例:

┖╴TheGame
   ┠╴Menu
     ┠╴Label
     ┖╴Camera2D
   ┖╴SplashScreen
      ┖╴Camera2D

Viewport get_viewport ( ) const

如果节点位于场景树内部,则返回该节点最近的 Viewport 祖先。否则,返回 null


Window get_window ( ) const

返回包含该节点的 Window。如果该节点在主窗口中,则相当于获取根节点(get_tree().get_root())。


bool has_node ( NodePath path ) const

如果 path 指向一个有效节点,则返回 true。另见 get_node


bool has_node_and_resource ( NodePath path ) const

如果 path 指向一个有效的节点,并且它的子名称指向一个有效的 Resource,例如 Area2D/CollisionShape2D:shape,则返回 true。不考虑非 Resource 类型(例如节点或其他 Variant 类型)的属性。另见 get_node_and_resource


bool is_ancestor_of ( Node node ) const

如果给定的 node 是该节点的直接或间接子节点,则返回 true


bool is_displayed_folded ( ) const

如果该节点在“场景”面板中被折叠,则返回 true。该方法旨在用于编辑器插件和工具。另见 set_display_folded


bool is_editable_instance ( Node node ) const

如果 node 具有相对于该节点启用的可编辑子节点,则返回 true。该方法旨在用于编辑器插件和工具。另见 set_editable_instance


bool is_greater_than ( Node node ) const

如果给定的 node 在场景层次结构中出现得比该节点晚,则返回 true。晚出现的节点通常晚处理。


bool is_in_group ( StringName group ) const

如果该节点已被添加到给定的 group,则返回 true。请参阅 add_to_groupremove_from_group。另请参阅描述中的注释以及 SceneTree 的分组方法。


bool is_inside_tree ( ) const

如果该节点当前在 SceneTree 中,返回 true。另见 get_tree


bool is_multiplayer_authority ( ) const

如果本地系统为这个节点的多人游戏控制者,则返回 true


bool is_node_ready ( ) const

如果该节点已就绪,则返回 true,即该节点位于场景树中,并且所有子项均已初始化。

request_ready 会将其重置回 false


bool is_physics_processing ( ) const

如果启用了物理处理,返回 true(见 set_physics_process)。


bool is_physics_processing_internal ( ) const

如果内部物理处理被启用,返回 true(见 set_physics_process_internal)。


bool is_processing ( ) const

如果开启了处理,返回 true(见 set_process)。


bool is_processing_input ( ) const

如果节点正在处理输入,则返回 true(见 set_process_input)。


bool is_processing_internal ( ) const

如果启用了内部处理,则返回 true(见 set_process_internal)。


bool is_processing_shortcut_input ( ) const

如果节点正在处理快捷键,则返回 true(见 set_process_shortcut_input)。


bool is_processing_unhandled_input ( ) const

如果节点正在处理未被处理的输入,则返回 true(见 set_process_unhandled_input)。


bool is_processing_unhandled_key_input ( ) const

如果节点正在处理未被处理的键输入,则返回 true(见 set_process_unhandled_key_input)。


void move_child ( Node child_node, int to_index )

child_node 移动到给定索引。节点的索引是其同级节点之间的顺序。如果 to_index 为负,则索引从列表末尾开始计数。另见 get_childget_index

注意:几个引擎回调(_ready_process 等)和通过 propagate_notification 发送的通知的处理顺序受树顺序的影响。CanvasItem 节点也按树顺序渲染。另见process_priority


void notify_deferred_thread_group ( int what )

类似于 call_deferred_thread_group,但针对的是通知。


void notify_thread_safe ( int what )

类似于 call_thread_safe,但针对的是通知。


void print_orphan_nodes ( ) static

输出所有孤立节点(SceneTree 之外的节点)。利于调试。

注意:该方法仅适用于调试构建版本。在以发布模式导出的项目中不执行任何操作。


void print_tree ( )

将该节点及其子节点打印到标准输出,会进行递归操作。该节点可以不在树中。这个方法输出的是相对于当前节点的路径,适合复制/粘贴到 get_node 函数中。另见 print_tree_pretty

示例输出:

.
Menu
Menu/Label
Menu/Camera2D
SplashScreen
SplashScreen/Camera2D

void print_tree_pretty ( )

递归地将节点及其子节点打印到控制台。节点不必位于场景树中。类似于 print_tree,但图形表示看起来像编辑器的场景面板中显示的内容。利于检查较大的树。

输出示例:

┖╴TheGame
   ┠╴Menu
     ┠╴Label
     ┖╴Camera2D
   ┖╴SplashScreen
      ┖╴Camera2D

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

在该节点上并递归地在其所有子节点上,调用给定的 method 名称,并将 args 作为参数传递。

如果 parent_first 参数为 true,则该方法将首先在该节点上调用,然后在其所有子节点上调用。如果为 false,则子节点的方法将首先被调用。


void propagate_notification ( int what )

在该节点上并递归地在其所有子节点上,使用 what 调用 Object.notification


void queue_free ( )

将该节点加入队列以在当前帧末尾删除。被删除时,其所有子节点也将被删除,并且对该节点及其子节点的所有引用都将变得无效。

Object.free 不同,该节点不会被立即删除,并且它在被删除前仍然可以访问。多次调用 queue_free 也是安全的。使用 Object.is_queued_for_deletion 检查节点是否会在该帧末尾删除。

注意:该节点只会在所有其他已延迟的调用完成后释放。使用该方法并不总会和通过 Object.call_deferred 调用 Object.free 相同。


void remove_child ( Node node )

移除一个子 node。该 node 及其子节点不会被删除。要删除节点,见 queue_free

注意:当该节点位于场景树中时,如果被移除的 node(或其后代)的 owner 不再是祖先(参见 is_ancestor_of),则该方法将它们的 owner 设置为 null


void remove_from_group ( StringName group )

从给定的 group 中移除该节点。如果该节点不在 group 中,则不执行任何操作。另请参阅描述中的注释以及 SceneTree 的分组方法。


void reparent ( Node new_parent, bool keep_global_transform=true )

将这个 Node 的父节点更改为 new_parent。该节点需要拥有父节点。

如果 keep_global_transformtrue,则会在支持时保持该节点的全局变换。Node2DNode3DControl 支持这个参数(但 Control 只会保留位置)。


void replace_by ( Node node, bool keep_groups=false )

将该节点替换为给定的 node。该节点的所有子节点都会被移动到 node

如果 keep_groupstrue,则 node 将被添加到被替换节点所在的相同分组中(请参阅 add_to_group)。

警告:被替换的节点已从树中移除,但被删除。为了防止内存泄漏,请将该节点的引用存储在变量中,或使用 Object.free


void request_ready ( )

请求在该节点下次进入树时再次调用 _ready会立即调用 _ready

注意:该方法只影响当前节点。如果该节点的子节点也需要请求就绪,则需要为每个子节点调用该方法。当节点及其子节点再次进入树时,_ready 回调的顺序将与正常情况相同。


Error rpc ( StringName method, ... ) vararg

将给定 method 的远程过程调用请求发送到网络(和本地)上的对等体,并将额外参数发送给 RPC 调用的方法。该调用请求只会被具有相同 NodePath 的节点接收,该节点包括完全相同的 name。行为取决于给定 method 的 RPC 配置(请参阅 rpc_config@GDScript.@rpc)。默认情况下,方法不会暴露给 RPC。

如果调用成功,则返回 @GlobalScope.OK;如果 method 中传递的参数不匹配,则返回 @GlobalScope.ERR_INVALID_PARAMETER;如果无法获取节点的 multiplayer(例如当该节点不在树中),则返回 @GlobalScope.ERR_UNCONFIGURED;如果 multiplayer 的连接不可用,则返回 @GlobalScope.ERR_CONNECTION_ERROR

注意:只有在收到来自 MultiplayerAPIMultiplayerAPI.connected_to_server 信号后,才能在客户端上安全地使用 RPC。还需要跟踪连接状态,可通过 MultiplayerAPI 信号(如 MultiplayerAPI.server_disconnected)或通过检查(get_multiplayer().peer.get_connection_status() == CONNECTION_CONNECTED)来跟踪。


void rpc_config ( StringName method, Variant config )

更改给定 method 的 RPC 配置。config 应该是 null 以禁用该功能(默认情况下),或者是包含以下条目的 Dictionary

  • rpc_mode:见 RPCMode

  • transfer_mode:见 TransferMode

  • call_local:如果为 true,该方法也将会在本地调用;

  • channel:一个 int 表示启用了发送 RPC 的通道。

注意:在 GDScript 中,该方法对应 @GDScript.@rpc 注解,并传递各种参数(@rpc(any)@rpc(authority)……)。 另请参阅 高级多人游戏 教程。


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

rpc 发送到由 peer_id 标识的特定对等体(请参阅 MultiplayerPeer.set_target_peer)。

如果调用成功,则返回 @GlobalScope.OK;如果 method 中传递的参数不匹配,则返回 @GlobalScope.ERR_INVALID_PARAMETER;如果无法获取节点的 multiplayer(例如当节点不在场景树中),则返回 @GlobalScope.ERR_UNCONFIGURED;如果 multiplayer 的连接不可用,则返回 @GlobalScope.ERR_CONNECTION_ERROR


void set_deferred_thread_group ( StringName property, Variant value )

类似于 call_deferred_thread_group,但针对的是设置属性。


void set_display_folded ( bool fold )

如果设置为 true,则节点将在场景面板中显示为被折叠。结果,它的所有子节点都被隐藏了。该方法旨在用于编辑器插件和工具脚本,但它也适用于发布构建版本。另请参阅 is_displayed_folded


void set_editable_instance ( Node node, bool is_editable )

设置为 true 以允许 node 拥有的所有节点在场景面板中可用且可编辑,即使它们的 owner 不是场景根。该方法旨在用于编辑器插件和工具脚本,但它也适用于发布构建版本。另见 is_editable_instance


void set_multiplayer_authority ( int id, bool recursive=true )

将该节点的多人游戏控制方设置为具有给定对等体 id 的对等体。多人游戏控制方是对网络上的节点具有控制权限的对等体。默认为对等体 ID 1(服务器)。利于与 rpc_configMultiplayerAPI 结合使用。

如果 recursivetrue,则该节点的所有子节点将递归地将给定的对等体设置为控制方。

警告:不会自动将新的控制方复制给其他对等体。是否这样做由开发者负责。可以使用 MultiplayerSpawner.spawn_function、RPC、或 MultiplayerSynchronizer 复制新控制方的信息。此外,父节点的控制方不会传播给新添加的子节点。


void set_physics_process ( bool enable )

如果设置为 true,则启用物理(固定帧率)处理。当一个节点正在被处理时,它将以固定的(通常是 60 FPS,请参阅 Engine.physics_ticks_per_second 以更改)时间间隔,接收一个 NOTIFICATION_PHYSICS_PROCESS(如果存在 _physics_process 回调,该回调将被调用)。如果 _physics_process 被重写,则会自动启用该属性。


void set_physics_process_internal ( bool enable )

如果设置为 true,则启用该节点的内部物理。内部物理处理独立于正常的 _physics_process 调用而发生,并且由某些节点内部使用以确保正常工作,即使节点暂停或物理处理因脚本而禁用(set_physics_process)也是如此。

警告:内置节点依靠内部处理来实现其内部逻辑。禁用它是不安全的,并且可能会导致意外行为。请在你知道自己正在做什么时使用该方法。


void set_process ( bool enable )

如果设置为 true,则启用帧处理。当一个节点正在被处理时,它将在每个绘制的帧上收到一个 NOTIFICATION_PROCESS(如果存在 _process 回调,该回调将被调用)。如果 _process 被重写,则会自动启用该属性。


void set_process_input ( bool enable )

如果设置为 true,则启用输入处理。它对于 GUI 控件来说不是必需的!如果 _input 被重写,则会自动启用该属性。


void set_process_internal ( bool enable )

如果设置为 true,则启用该节点的内部处理。内部处理独立于正常的 _process 调用而发生,并且由某些节点在内部使用以保证正常运行,即使节点已暂停或处理因脚本而禁用(set_process)也是如此。

警告:内置节点依靠内部处理来实现其内部逻辑。禁用它是不安全的,并且可能会导致意外行为。请在你知道自己正在做什么时使用该方法。


void set_process_shortcut_input ( bool enable )

如果设置为 true,则启用该节点的快捷键处理。如果 _shortcut_input 被重写,则会自动启用该属性。


void set_process_unhandled_input ( bool enable )

如果设置为 true,则启用未处理的输入处理。这对 GUI 控件来说是不需要的!它使节点能够接收所有以前没有处理的输入(通常是由 Control 处理的)。如果 _unhandled_input 被重写,则会自动启用该属性。


void set_process_unhandled_key_input ( bool enable )

如果设置为 true,则启用未处理的按键输入处理。如果 _unhandled_key_input 被重写,则会自动启用该属性。


void set_scene_instance_load_placeholder ( bool load_placeholder )

如果设置为 true,则当从 PackedScene 打包和实例化时,节点将变为 InstancePlaceholder。另见 get_scene_instance_load_placeholder


void set_thread_safe ( StringName property, Variant value )

类似于 call_thread_safe,但用于设置属性。


void update_configuration_warnings ( )

刷新场景面板中为该节点显示的警告。使用 _get_configuration_warnings 自定义要显示的警告消息。