Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Node

继承: Object

派生: AnimationMixer, AudioStreamPlayer, CanvasItem, CanvasLayer, EditorFileSystem, EditorPlugin, EditorResourcePreview, HTTPRequest, InstancePlaceholder, MissingNode, MultiplayerSpawner, MultiplayerSynchronizer, NavigationAgent2D, NavigationAgent3D, Node3D, ResourcePreloader, ShaderGlobalsOverride, StatusIndicator, 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)。

教程

属性

AutoTranslateMode

auto_translate_mode

0

String

editor_description

""

MultiplayerAPI

multiplayer

StringName

name

Node

owner

PhysicsInterpolationMode

physics_interpolation_mode

0

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(event: InputEvent) virtual

void

_physics_process(delta: float) virtual

void

_process(delta: float) virtual

void

_ready() virtual

void

_shortcut_input(event: InputEvent) virtual

void

_unhandled_input(event: InputEvent) virtual

void

_unhandled_key_input(event: InputEvent) virtual

void

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

void

add_sibling(sibling: Node, force_readable_name: bool = false)

void

add_to_group(group: StringName, persistent: bool = false)

String

atr(message: String, context: StringName = "") const

String

atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") const

Variant

call_deferred_thread_group(method: StringName, ...) vararg

Variant

call_thread_safe(method: StringName, ...) vararg

bool

can_process() const

Tween

create_tween()

Node

duplicate(flags: int = 15) const

Node

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

Array[Node]

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

Node

find_parent(pattern: String) const

Node

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

int

get_child_count(include_internal: bool = false) const

Array[Node]

get_children(include_internal: bool = false) const

Array[StringName]

get_groups() const

int

get_index(include_internal: bool = false) const

Window

get_last_exclusive_window() const

int

get_multiplayer_authority() const

Node

get_node(path: NodePath) const

Array

get_node_and_resource(path: NodePath)

Node

get_node_or_null(path: NodePath) const

Node

get_parent() const

NodePath

get_path() const

NodePath

get_path_to(node: Node, use_unique_path: bool = 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(path: NodePath) const

bool

has_node_and_resource(path: NodePath) 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(group: StringName) const

bool

is_inside_tree() const

bool

is_multiplayer_authority() const

bool

is_node_ready() const

bool

is_part_of_edited_scene() const

bool

is_physics_interpolated() const

bool

is_physics_interpolated_and_enabled() 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(child_node: Node, to_index: int)

void

notify_deferred_thread_group(what: int)

void

notify_thread_safe(what: int)

void

print_orphan_nodes() static

void

print_tree()

void

print_tree_pretty()

void

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

void

propagate_notification(what: int)

void

queue_free()

void

remove_child(node: Node)

void

remove_from_group(group: StringName)

void

reparent(new_parent: Node, keep_global_transform: bool = true)

void

replace_by(node: Node, keep_groups: bool = false)

void

request_ready()

void

reset_physics_interpolation()

Error

rpc(method: StringName, ...) vararg

void

rpc_config(method: StringName, config: Variant)

Error

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

void

set_deferred_thread_group(property: StringName, value: Variant)

void

set_display_folded(fold: bool)

void

set_editable_instance(node: Node, is_editable: bool)

void

set_multiplayer_authority(id: int, recursive: bool = true)

void

set_physics_process(enable: bool)

void

set_physics_process_internal(enable: bool)

void

set_process(enable: bool)

void

set_process_input(enable: bool)

void

set_process_internal(enable: bool)

void

set_process_shortcut_input(enable: bool)

void

set_process_unhandled_input(enable: bool)

void

set_process_unhandled_key_input(enable: bool)

void

set_scene_instance_load_placeholder(load_placeholder: bool)

void

set_thread_safe(property: StringName, value: Variant)

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() 🔗

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


editor_description_changed(node: Node) 🔗

当节点的编辑器描述字段更改时发出。


ready() 🔗

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


renamed() 🔗

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


replacing_by(node: Node) 🔗

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

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