node.h 34 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864
  1. /**************************************************************************/
  2. /* node.h */
  3. /**************************************************************************/
  4. /* This file is part of: */
  5. /* GODOT ENGINE */
  6. /* https://godotengine.org */
  7. /**************************************************************************/
  8. /* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
  9. /* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
  10. /* */
  11. /* Permission is hereby granted, free of charge, to any person obtaining */
  12. /* a copy of this software and associated documentation files (the */
  13. /* "Software"), to deal in the Software without restriction, including */
  14. /* without limitation the rights to use, copy, modify, merge, publish, */
  15. /* distribute, sublicense, and/or sell copies of the Software, and to */
  16. /* permit persons to whom the Software is furnished to do so, subject to */
  17. /* the following conditions: */
  18. /* */
  19. /* The above copyright notice and this permission notice shall be */
  20. /* included in all copies or substantial portions of the Software. */
  21. /* */
  22. /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
  23. /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
  24. /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
  25. /* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
  26. /* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
  27. /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
  28. /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
  29. /**************************************************************************/
  30. #pragma once
  31. #include "core/string/node_path.h"
  32. #include "core/variant/typed_array.h"
  33. #include "scene/main/scene_tree.h"
  34. #include "scene/scene_string_names.h"
  35. class Viewport;
  36. class Window;
  37. class SceneState;
  38. class Tween;
  39. class PropertyTweener;
  40. SAFE_FLAG_TYPE_PUN_GUARANTEES
  41. SAFE_NUMERIC_TYPE_PUN_GUARANTEES(uint32_t)
  42. class Node : public Object {
  43. GDCLASS(Node, Object);
  44. protected:
  45. // During group processing, these are thread-safe.
  46. // Outside group processing, these avoid the cost of sync by working as plain primitive types.
  47. union MTFlag {
  48. SafeFlag mt;
  49. bool st;
  50. MTFlag() :
  51. mt{} {}
  52. };
  53. template <typename T>
  54. union MTNumeric {
  55. SafeNumeric<T> mt;
  56. T st;
  57. MTNumeric() :
  58. mt{} {}
  59. };
  60. public:
  61. // N.B. Any enum stored as a bitfield should be specified as UNSIGNED to work around
  62. // some compilers trying to store it as signed, and requiring 1 more bit than necessary.
  63. enum ProcessMode : unsigned int {
  64. PROCESS_MODE_INHERIT, // same as parent node
  65. PROCESS_MODE_PAUSABLE, // process only if not paused
  66. PROCESS_MODE_WHEN_PAUSED, // process only if paused
  67. PROCESS_MODE_ALWAYS, // process always
  68. PROCESS_MODE_DISABLED, // never process
  69. };
  70. enum ProcessThreadGroup {
  71. PROCESS_THREAD_GROUP_INHERIT,
  72. PROCESS_THREAD_GROUP_MAIN_THREAD,
  73. PROCESS_THREAD_GROUP_SUB_THREAD,
  74. };
  75. enum ProcessThreadMessages {
  76. FLAG_PROCESS_THREAD_MESSAGES = 1,
  77. FLAG_PROCESS_THREAD_MESSAGES_PHYSICS = 2,
  78. FLAG_PROCESS_THREAD_MESSAGES_ALL = 3,
  79. };
  80. enum PhysicsInterpolationMode : unsigned int {
  81. PHYSICS_INTERPOLATION_MODE_INHERIT,
  82. PHYSICS_INTERPOLATION_MODE_ON,
  83. PHYSICS_INTERPOLATION_MODE_OFF,
  84. };
  85. enum DuplicateFlags {
  86. DUPLICATE_SIGNALS = 1,
  87. DUPLICATE_GROUPS = 2,
  88. DUPLICATE_SCRIPTS = 4,
  89. DUPLICATE_USE_INSTANTIATION = 8,
  90. #ifdef TOOLS_ENABLED
  91. DUPLICATE_FROM_EDITOR = 16,
  92. #endif
  93. };
  94. enum NameCasing {
  95. NAME_CASING_PASCAL_CASE,
  96. NAME_CASING_CAMEL_CASE,
  97. NAME_CASING_SNAKE_CASE
  98. };
  99. enum InternalMode {
  100. INTERNAL_MODE_DISABLED,
  101. INTERNAL_MODE_FRONT,
  102. INTERNAL_MODE_BACK,
  103. };
  104. enum AutoTranslateMode {
  105. AUTO_TRANSLATE_MODE_INHERIT,
  106. AUTO_TRANSLATE_MODE_ALWAYS,
  107. AUTO_TRANSLATE_MODE_DISABLED,
  108. };
  109. struct Comparator {
  110. bool operator()(const Node *p_a, const Node *p_b) const { return p_b->is_greater_than(p_a); }
  111. };
  112. static int orphan_node_count;
  113. void _update_process(bool p_enable, bool p_for_children);
  114. private:
  115. struct GroupData {
  116. bool persistent = false;
  117. SceneTree::Group *group = nullptr;
  118. };
  119. struct ComparatorByIndex {
  120. bool operator()(const Node *p_left, const Node *p_right) const {
  121. static const uint32_t order[3] = { 1, 0, 2 };
  122. uint32_t order_left = order[p_left->data.internal_mode];
  123. uint32_t order_right = order[p_right->data.internal_mode];
  124. if (order_left == order_right) {
  125. return p_left->data.index < p_right->data.index;
  126. }
  127. return order_left < order_right;
  128. }
  129. };
  130. struct ComparatorWithPriority {
  131. bool operator()(const Node *p_a, const Node *p_b) const { return p_b->data.process_priority == p_a->data.process_priority ? p_b->is_greater_than(p_a) : p_b->data.process_priority > p_a->data.process_priority; }
  132. };
  133. struct ComparatorWithPhysicsPriority {
  134. bool operator()(const Node *p_a, const Node *p_b) const { return p_b->data.physics_process_priority == p_a->data.physics_process_priority ? p_b->is_greater_than(p_a) : p_b->data.physics_process_priority > p_a->data.physics_process_priority; }
  135. };
  136. // This Data struct is to avoid namespace pollution in derived classes.
  137. struct Data {
  138. String scene_file_path;
  139. Ref<SceneState> instance_state;
  140. Ref<SceneState> inherited_state;
  141. Node *parent = nullptr;
  142. Node *owner = nullptr;
  143. HashMap<StringName, Node *> children;
  144. mutable bool children_cache_dirty = true;
  145. mutable LocalVector<Node *> children_cache;
  146. HashMap<StringName, Node *> owned_unique_nodes;
  147. bool unique_name_in_owner = false;
  148. InternalMode internal_mode = INTERNAL_MODE_DISABLED;
  149. mutable int internal_children_front_count_cache = 0;
  150. mutable int internal_children_back_count_cache = 0;
  151. mutable int external_children_count_cache = 0;
  152. mutable int index = -1; // relative to front, normal or back.
  153. int depth = -1;
  154. int blocked = 0; // Safeguard that throws an error when attempting to modify the tree in a harmful way while being traversed.
  155. StringName name;
  156. SceneTree *tree = nullptr;
  157. #ifdef TOOLS_ENABLED
  158. NodePath import_path; // Path used when imported, used by scene editors to keep tracking.
  159. #endif
  160. String editor_description;
  161. Viewport *viewport = nullptr;
  162. HashMap<StringName, GroupData> grouped;
  163. List<Node *>::Element *OW = nullptr; // Owned element.
  164. List<Node *> owned;
  165. Node *process_owner = nullptr;
  166. ProcessThreadGroup process_thread_group = PROCESS_THREAD_GROUP_INHERIT;
  167. Node *process_thread_group_owner = nullptr;
  168. int process_thread_group_order = 0;
  169. BitField<ProcessThreadMessages> process_thread_messages;
  170. void *process_group = nullptr; // to avoid cyclic dependency
  171. int multiplayer_authority = 1; // Server by default.
  172. Variant rpc_config = Dictionary();
  173. // Variables used to properly sort the node when processing, ignored otherwise.
  174. int process_priority = 0;
  175. int physics_process_priority = 0;
  176. // Keep bitpacked values together to get better packing.
  177. ProcessMode process_mode : 3;
  178. PhysicsInterpolationMode physics_interpolation_mode : 2;
  179. bool physics_process : 1;
  180. bool process : 1;
  181. bool physics_process_internal : 1;
  182. bool process_internal : 1;
  183. bool input : 1;
  184. bool shortcut_input : 1;
  185. bool unhandled_input : 1;
  186. bool unhandled_key_input : 1;
  187. // Physics interpolation can be turned on and off on a per node basis.
  188. // This only takes effect when the SceneTree (or project setting) physics interpolation
  189. // is switched on.
  190. bool physics_interpolated : 1;
  191. // We can auto-reset physics interpolation when e.g. adding a node for the first time.
  192. bool physics_interpolation_reset_requested : 1;
  193. // Most nodes need not be interpolated in the scene tree, physics interpolation
  194. // is normally only needed in the RenderingServer. However if we need to read the
  195. // interpolated transform of a node in the SceneTree, it is necessary to duplicate
  196. // the interpolation logic client side, in order to prevent stalling the RenderingServer
  197. // by reading back.
  198. bool physics_interpolated_client_side : 1;
  199. // For certain nodes (e.g. CPU particles in global mode)
  200. // it can be useful to not send the instance transform to the
  201. // RenderingServer, and specify the mesh in world space.
  202. bool use_identity_transform : 1;
  203. bool use_placeholder : 1;
  204. bool display_folded : 1;
  205. bool editable_instance : 1;
  206. bool inside_tree : 1;
  207. bool ready_notified : 1;
  208. bool ready_first : 1;
  209. AutoTranslateMode auto_translate_mode = AUTO_TRANSLATE_MODE_INHERIT;
  210. mutable bool is_auto_translating = true;
  211. mutable bool is_auto_translate_dirty = true;
  212. mutable bool is_translation_domain_inherited = true;
  213. mutable bool is_translation_domain_dirty = true;
  214. mutable NodePath *path_cache = nullptr;
  215. } data;
  216. Ref<MultiplayerAPI> multiplayer;
  217. String _get_tree_string_pretty(const String &p_prefix, bool p_last);
  218. String _get_tree_string(const Node *p_node);
  219. Node *_get_child_by_name(const StringName &p_name) const;
  220. void _replace_connections_target(Node *p_new_target);
  221. void _validate_child_name(Node *p_child, bool p_force_human_readable = false);
  222. void _generate_serial_child_name(const Node *p_child, StringName &name) const;
  223. void _propagate_reverse_notification(int p_notification);
  224. void _propagate_deferred_notification(int p_notification, bool p_reverse);
  225. void _propagate_enter_tree();
  226. void _propagate_ready();
  227. void _propagate_exit_tree();
  228. void _propagate_after_exit_tree();
  229. void _propagate_physics_interpolated(bool p_interpolated);
  230. void _propagate_physics_interpolation_reset_requested(bool p_requested);
  231. void _propagate_process_owner(Node *p_owner, int p_pause_notification, int p_enabled_notification);
  232. void _propagate_groups_dirty();
  233. void _propagate_translation_domain_dirty();
  234. Array _get_node_and_resource(const NodePath &p_path);
  235. void _duplicate_properties(const Node *p_root, const Node *p_original, Node *p_copy, int p_flags) const;
  236. void _duplicate_signals(const Node *p_original, Node *p_copy) const;
  237. Node *_duplicate(int p_flags, HashMap<const Node *, Node *> *r_duplimap = nullptr) const;
  238. TypedArray<StringName> _get_groups() const;
  239. Error _rpc_bind(const Variant **p_args, int p_argcount, Callable::CallError &r_error);
  240. Error _rpc_id_bind(const Variant **p_args, int p_argcount, Callable::CallError &r_error);
  241. friend class SceneTree;
  242. void _set_tree(SceneTree *p_tree);
  243. void _propagate_pause_notification(bool p_enable);
  244. void _propagate_suspend_notification(bool p_enable);
  245. _FORCE_INLINE_ bool _can_process(bool p_paused) const;
  246. _FORCE_INLINE_ bool _is_enabled() const;
  247. void _release_unique_name_in_owner();
  248. void _acquire_unique_name_in_owner();
  249. void _clean_up_owner();
  250. _FORCE_INLINE_ void _update_children_cache() const {
  251. if (unlikely(data.children_cache_dirty)) {
  252. _update_children_cache_impl();
  253. }
  254. }
  255. void _update_children_cache_impl() const;
  256. // Process group management
  257. void _add_process_group();
  258. void _remove_process_group();
  259. void _add_to_process_thread_group();
  260. void _remove_from_process_thread_group();
  261. void _remove_tree_from_process_thread_group();
  262. void _add_tree_to_process_thread_group(Node *p_owner);
  263. static thread_local Node *current_process_thread_group;
  264. Variant _call_deferred_thread_group_bind(const Variant **p_args, int p_argcount, Callable::CallError &r_error);
  265. Variant _call_thread_safe_bind(const Variant **p_args, int p_argcount, Callable::CallError &r_error);
  266. // Editor only signal to keep the SceneTreeEditor in sync.
  267. #ifdef TOOLS_ENABLED
  268. void _emit_editor_state_changed();
  269. #else
  270. void _emit_editor_state_changed() {}
  271. #endif
  272. protected:
  273. void _block() { data.blocked++; }
  274. void _unblock() { data.blocked--; }
  275. void _notification(int p_notification);
  276. virtual void _physics_interpolated_changed();
  277. virtual void add_child_notify(Node *p_child);
  278. virtual void remove_child_notify(Node *p_child);
  279. virtual void move_child_notify(Node *p_child);
  280. virtual void owner_changed_notify();
  281. void _propagate_replace_owner(Node *p_owner, Node *p_by_owner);
  282. static void _bind_methods();
  283. static String _get_name_num_separator();
  284. friend class SceneState;
  285. void _add_child_nocheck(Node *p_child, const StringName &p_name, InternalMode p_internal_mode = INTERNAL_MODE_DISABLED);
  286. void _set_owner_nocheck(Node *p_owner);
  287. void _set_name_nocheck(const StringName &p_name);
  288. void _set_physics_interpolated_client_side(bool p_enable) { data.physics_interpolated_client_side = p_enable; }
  289. bool _is_physics_interpolated_client_side() const { return data.physics_interpolated_client_side; }
  290. void _set_physics_interpolation_reset_requested(bool p_enable) { data.physics_interpolation_reset_requested = p_enable; }
  291. bool _is_physics_interpolation_reset_requested() const { return data.physics_interpolation_reset_requested; }
  292. void _set_use_identity_transform(bool p_enable) { data.use_identity_transform = p_enable; }
  293. bool _is_using_identity_transform() const { return data.use_identity_transform; }
  294. //call from SceneTree
  295. void _call_input(const Ref<InputEvent> &p_event);
  296. void _call_shortcut_input(const Ref<InputEvent> &p_event);
  297. void _call_unhandled_input(const Ref<InputEvent> &p_event);
  298. void _call_unhandled_key_input(const Ref<InputEvent> &p_event);
  299. void _validate_property(PropertyInfo &p_property) const;
  300. protected:
  301. virtual void input(const Ref<InputEvent> &p_event);
  302. virtual void shortcut_input(const Ref<InputEvent> &p_key_event);
  303. virtual void unhandled_input(const Ref<InputEvent> &p_event);
  304. virtual void unhandled_key_input(const Ref<InputEvent> &p_key_event);
  305. GDVIRTUAL1(_process, double)
  306. GDVIRTUAL1(_physics_process, double)
  307. GDVIRTUAL0(_enter_tree)
  308. GDVIRTUAL0(_exit_tree)
  309. GDVIRTUAL0(_ready)
  310. GDVIRTUAL0RC(Vector<String>, _get_configuration_warnings)
  311. GDVIRTUAL1(_input, Ref<InputEvent>)
  312. GDVIRTUAL1(_shortcut_input, Ref<InputEvent>)
  313. GDVIRTUAL1(_unhandled_input, Ref<InputEvent>)
  314. GDVIRTUAL1(_unhandled_key_input, Ref<InputEvent>)
  315. public:
  316. enum {
  317. // You can make your own, but don't use the same numbers as other notifications in other nodes.
  318. NOTIFICATION_ENTER_TREE = 10,
  319. NOTIFICATION_EXIT_TREE = 11,
  320. NOTIFICATION_MOVED_IN_PARENT = 12,
  321. NOTIFICATION_READY = 13,
  322. NOTIFICATION_PAUSED = 14,
  323. NOTIFICATION_UNPAUSED = 15,
  324. NOTIFICATION_PHYSICS_PROCESS = 16,
  325. NOTIFICATION_PROCESS = 17,
  326. NOTIFICATION_PARENTED = 18,
  327. NOTIFICATION_UNPARENTED = 19,
  328. NOTIFICATION_SCENE_INSTANTIATED = 20,
  329. NOTIFICATION_DRAG_BEGIN = 21,
  330. NOTIFICATION_DRAG_END = 22,
  331. NOTIFICATION_PATH_RENAMED = 23,
  332. NOTIFICATION_CHILD_ORDER_CHANGED = 24,
  333. NOTIFICATION_INTERNAL_PROCESS = 25,
  334. NOTIFICATION_INTERNAL_PHYSICS_PROCESS = 26,
  335. NOTIFICATION_POST_ENTER_TREE = 27,
  336. NOTIFICATION_DISABLED = 28,
  337. NOTIFICATION_ENABLED = 29,
  338. NOTIFICATION_RESET_PHYSICS_INTERPOLATION = 2001, // A GodotSpace Odyssey.
  339. // Keep these linked to Node.
  340. NOTIFICATION_WM_MOUSE_ENTER = 1002,
  341. NOTIFICATION_WM_MOUSE_EXIT = 1003,
  342. NOTIFICATION_WM_WINDOW_FOCUS_IN = 1004,
  343. NOTIFICATION_WM_WINDOW_FOCUS_OUT = 1005,
  344. NOTIFICATION_WM_CLOSE_REQUEST = 1006,
  345. NOTIFICATION_WM_GO_BACK_REQUEST = 1007,
  346. NOTIFICATION_WM_SIZE_CHANGED = 1008,
  347. NOTIFICATION_WM_DPI_CHANGE = 1009,
  348. NOTIFICATION_VP_MOUSE_ENTER = 1010,
  349. NOTIFICATION_VP_MOUSE_EXIT = 1011,
  350. NOTIFICATION_WM_POSITION_CHANGED = 1012,
  351. NOTIFICATION_OS_MEMORY_WARNING = MainLoop::NOTIFICATION_OS_MEMORY_WARNING,
  352. NOTIFICATION_TRANSLATION_CHANGED = MainLoop::NOTIFICATION_TRANSLATION_CHANGED,
  353. NOTIFICATION_WM_ABOUT = MainLoop::NOTIFICATION_WM_ABOUT,
  354. NOTIFICATION_CRASH = MainLoop::NOTIFICATION_CRASH,
  355. NOTIFICATION_OS_IME_UPDATE = MainLoop::NOTIFICATION_OS_IME_UPDATE,
  356. NOTIFICATION_APPLICATION_RESUMED = MainLoop::NOTIFICATION_APPLICATION_RESUMED,
  357. NOTIFICATION_APPLICATION_PAUSED = MainLoop::NOTIFICATION_APPLICATION_PAUSED,
  358. NOTIFICATION_APPLICATION_FOCUS_IN = MainLoop::NOTIFICATION_APPLICATION_FOCUS_IN,
  359. NOTIFICATION_APPLICATION_FOCUS_OUT = MainLoop::NOTIFICATION_APPLICATION_FOCUS_OUT,
  360. NOTIFICATION_TEXT_SERVER_CHANGED = MainLoop::NOTIFICATION_TEXT_SERVER_CHANGED,
  361. // Editor specific node notifications
  362. NOTIFICATION_EDITOR_PRE_SAVE = 9001,
  363. NOTIFICATION_EDITOR_POST_SAVE = 9002,
  364. NOTIFICATION_SUSPENDED = 9003,
  365. NOTIFICATION_UNSUSPENDED = 9004
  366. };
  367. /* NODE/TREE */
  368. StringName get_name() const;
  369. String get_description() const;
  370. void set_name(const String &p_name);
  371. InternalMode get_internal_mode() const;
  372. void add_child(Node *p_child, bool p_force_readable_name = false, InternalMode p_internal = INTERNAL_MODE_DISABLED);
  373. void add_sibling(Node *p_sibling, bool p_force_readable_name = false);
  374. void remove_child(Node *p_child);
  375. int get_child_count(bool p_include_internal = true) const;
  376. Node *get_child(int p_index, bool p_include_internal = true) const;
  377. TypedArray<Node> get_children(bool p_include_internal = true) const;
  378. bool has_node(const NodePath &p_path) const;
  379. Node *get_node(const NodePath &p_path) const;
  380. Node *get_node_or_null(const NodePath &p_path) const;
  381. Node *find_child(const String &p_pattern, bool p_recursive = true, bool p_owned = true) const;
  382. TypedArray<Node> find_children(const String &p_pattern, const String &p_type = "", bool p_recursive = true, bool p_owned = true) const;
  383. bool has_node_and_resource(const NodePath &p_path) const;
  384. Node *get_node_and_resource(const NodePath &p_path, Ref<Resource> &r_res, Vector<StringName> &r_leftover_subpath, bool p_last_is_property = true) const;
  385. virtual void reparent(Node *p_parent, bool p_keep_global_transform = true);
  386. Node *get_parent() const;
  387. Node *find_parent(const String &p_pattern) const;
  388. Window *get_window() const;
  389. Window *get_last_exclusive_window() const;
  390. _FORCE_INLINE_ SceneTree *get_tree() const {
  391. ERR_FAIL_NULL_V(data.tree, nullptr);
  392. return data.tree;
  393. }
  394. _FORCE_INLINE_ bool is_inside_tree() const { return data.inside_tree; }
  395. bool is_internal() const { return data.internal_mode != INTERNAL_MODE_DISABLED; }
  396. bool is_ancestor_of(const Node *p_node) const;
  397. bool is_greater_than(const Node *p_node) const;
  398. NodePath get_path() const;
  399. NodePath get_path_to(const Node *p_node, bool p_use_unique_path = false) const;
  400. Node *find_common_parent_with(const Node *p_node) const;
  401. void add_to_group(const StringName &p_identifier, bool p_persistent = false);
  402. void remove_from_group(const StringName &p_identifier);
  403. bool is_in_group(const StringName &p_identifier) const;
  404. struct GroupInfo {
  405. StringName name;
  406. bool persistent = false;
  407. };
  408. void get_groups(List<GroupInfo> *p_groups) const;
  409. int get_persistent_group_count() const;
  410. void move_child(Node *p_child, int p_index);
  411. void _move_child(Node *p_child, int p_index, bool p_ignore_end = false);
  412. void set_owner(Node *p_owner);
  413. Node *get_owner() const;
  414. void get_owned_by(Node *p_by, List<Node *> *p_owned);
  415. void set_unique_name_in_owner(bool p_enabled);
  416. bool is_unique_name_in_owner() const;
  417. _FORCE_INLINE_ int get_index(bool p_include_internal = true) const {
  418. // p_include_internal = false doesn't make sense if the node is internal.
  419. ERR_FAIL_COND_V_MSG(!p_include_internal && data.internal_mode != INTERNAL_MODE_DISABLED, -1, "Node is internal. Can't get index with 'include_internal' being false.");
  420. if (!data.parent) {
  421. return data.index;
  422. }
  423. data.parent->_update_children_cache();
  424. if (!p_include_internal) {
  425. return data.index;
  426. } else {
  427. switch (data.internal_mode) {
  428. case INTERNAL_MODE_DISABLED: {
  429. return data.parent->data.internal_children_front_count_cache + data.index;
  430. } break;
  431. case INTERNAL_MODE_FRONT: {
  432. return data.index;
  433. } break;
  434. case INTERNAL_MODE_BACK: {
  435. return data.parent->data.internal_children_front_count_cache + data.parent->data.external_children_count_cache + data.index;
  436. } break;
  437. }
  438. return -1;
  439. }
  440. }
  441. Ref<Tween> create_tween();
  442. void print_tree();
  443. void print_tree_pretty();
  444. String get_tree_string();
  445. String get_tree_string_pretty();
  446. void set_scene_file_path(const String &p_scene_file_path);
  447. String get_scene_file_path() const;
  448. void set_editor_description(const String &p_editor_description);
  449. String get_editor_description() const;
  450. void set_editable_instance(Node *p_node, bool p_editable);
  451. bool is_editable_instance(const Node *p_node) const;
  452. Node *get_deepest_editable_node(Node *p_start_node) const;
  453. #ifdef TOOLS_ENABLED
  454. void set_property_pinned(const String &p_property, bool p_pinned);
  455. bool is_property_pinned(const StringName &p_property) const;
  456. virtual StringName get_property_store_alias(const StringName &p_property) const;
  457. bool is_part_of_edited_scene() const;
  458. #else
  459. bool is_part_of_edited_scene() const { return false; }
  460. #endif
  461. void get_storable_properties(HashSet<StringName> &r_storable_properties) const;
  462. virtual String to_string() override;
  463. /* NOTIFICATIONS */
  464. void propagate_notification(int p_notification);
  465. void propagate_call(const StringName &p_method, const Array &p_args = Array(), const bool p_parent_first = false);
  466. /* PROCESSING */
  467. void set_physics_process(bool p_process);
  468. double get_physics_process_delta_time() const;
  469. bool is_physics_processing() const;
  470. void set_process(bool p_process);
  471. double get_process_delta_time() const;
  472. bool is_processing() const;
  473. void set_physics_process_internal(bool p_process_internal);
  474. bool is_physics_processing_internal() const;
  475. void set_process_internal(bool p_process_internal);
  476. bool is_processing_internal() const;
  477. void set_process_priority(int p_priority);
  478. int get_process_priority() const;
  479. void set_process_thread_group_order(int p_order);
  480. int get_process_thread_group_order() const;
  481. void set_physics_process_priority(int p_priority);
  482. int get_physics_process_priority() const;
  483. void set_process_input(bool p_enable);
  484. bool is_processing_input() const;
  485. void set_process_shortcut_input(bool p_enable);
  486. bool is_processing_shortcut_input() const;
  487. void set_process_unhandled_input(bool p_enable);
  488. bool is_processing_unhandled_input() const;
  489. void set_process_unhandled_key_input(bool p_enable);
  490. bool is_processing_unhandled_key_input() const;
  491. _FORCE_INLINE_ bool _is_any_processing() const {
  492. return data.process || data.process_internal || data.physics_process || data.physics_process_internal;
  493. }
  494. _FORCE_INLINE_ bool is_accessible_from_caller_thread() const {
  495. if (current_process_thread_group == nullptr) {
  496. // No thread processing.
  497. // Only accessible if node is outside the scene tree
  498. // or access will happen from a node-safe thread.
  499. return !data.inside_tree || is_current_thread_safe_for_nodes();
  500. } else {
  501. // Thread processing.
  502. return current_process_thread_group == data.process_thread_group_owner;
  503. }
  504. }
  505. _FORCE_INLINE_ bool is_readable_from_caller_thread() const {
  506. if (current_process_thread_group == nullptr) {
  507. // No thread processing.
  508. // Only accessible if node is outside the scene tree
  509. // or access will happen from a node-safe thread.
  510. return is_current_thread_safe_for_nodes() || unlikely(!data.inside_tree);
  511. } else {
  512. // Thread processing.
  513. return true;
  514. }
  515. }
  516. _FORCE_INLINE_ static bool is_group_processing() { return current_process_thread_group; }
  517. void set_process_thread_messages(BitField<ProcessThreadMessages> p_flags);
  518. BitField<ProcessThreadMessages> get_process_thread_messages() const;
  519. Node *duplicate(int p_flags = DUPLICATE_GROUPS | DUPLICATE_SIGNALS | DUPLICATE_SCRIPTS) const;
  520. #ifdef TOOLS_ENABLED
  521. Node *duplicate_from_editor(HashMap<const Node *, Node *> &r_duplimap) const;
  522. Node *duplicate_from_editor(HashMap<const Node *, Node *> &r_duplimap, const HashMap<Ref<Resource>, Ref<Resource>> &p_resource_remap) const;
  523. void remap_node_resources(Node *p_node, const HashMap<Ref<Resource>, Ref<Resource>> &p_resource_remap) const;
  524. void remap_nested_resources(Ref<Resource> p_resource, const HashMap<Ref<Resource>, Ref<Resource>> &p_resource_remap) const;
  525. #endif
  526. // used by editors, to save what has changed only
  527. void set_scene_instance_state(const Ref<SceneState> &p_state);
  528. Ref<SceneState> get_scene_instance_state() const;
  529. void set_scene_inherited_state(const Ref<SceneState> &p_state);
  530. Ref<SceneState> get_scene_inherited_state() const;
  531. void set_scene_instance_load_placeholder(bool p_enable);
  532. bool get_scene_instance_load_placeholder() const;
  533. template <typename... VarArgs>
  534. Vector<Variant> make_binds(VarArgs... p_args) {
  535. Vector<Variant> binds = { p_args... };
  536. return binds;
  537. }
  538. void replace_by(Node *p_node, bool p_keep_groups = false);
  539. void set_process_mode(ProcessMode p_mode);
  540. ProcessMode get_process_mode() const;
  541. bool can_process() const;
  542. bool can_process_notification(int p_what) const;
  543. void set_physics_interpolation_mode(PhysicsInterpolationMode p_mode);
  544. PhysicsInterpolationMode get_physics_interpolation_mode() const { return data.physics_interpolation_mode; }
  545. _FORCE_INLINE_ bool is_physics_interpolated() const { return data.physics_interpolated; }
  546. _FORCE_INLINE_ bool is_physics_interpolated_and_enabled() const { return is_inside_tree() && get_tree()->is_physics_interpolation_enabled() && is_physics_interpolated(); }
  547. void reset_physics_interpolation();
  548. bool is_enabled() const;
  549. bool is_ready() const;
  550. void request_ready();
  551. void set_process_thread_group(ProcessThreadGroup p_mode);
  552. ProcessThreadGroup get_process_thread_group() const;
  553. static void print_orphan_nodes();
  554. #ifdef TOOLS_ENABLED
  555. String validate_child_name(Node *p_child);
  556. String prevalidate_child_name(Node *p_child, StringName p_name);
  557. void get_argument_options(const StringName &p_function, int p_idx, List<String> *r_options) const override;
  558. #endif
  559. static String adjust_name_casing(const String &p_name);
  560. void queue_free();
  561. //hacks for speed
  562. static void init_node_hrcr();
  563. void set_import_path(const NodePath &p_import_path); //path used when imported, used by scene editors to keep tracking
  564. NodePath get_import_path() const;
  565. bool is_owned_by_parent() const;
  566. void clear_internal_tree_resource_paths();
  567. _FORCE_INLINE_ Viewport *get_viewport() const { return data.viewport; }
  568. virtual PackedStringArray get_configuration_warnings() const;
  569. void update_configuration_warnings();
  570. void set_display_folded(bool p_folded);
  571. bool is_displayed_folded() const;
  572. /* NETWORK */
  573. virtual void set_multiplayer_authority(int p_peer_id, bool p_recursive = true);
  574. int get_multiplayer_authority() const;
  575. bool is_multiplayer_authority() const;
  576. void rpc_config(const StringName &p_method, const Variant &p_config); // config a local method for RPC
  577. Variant get_rpc_config() const;
  578. template <typename... VarArgs>
  579. Error rpc(const StringName &p_method, VarArgs... p_args);
  580. template <typename... VarArgs>
  581. Error rpc_id(int p_peer_id, const StringName &p_method, VarArgs... p_args);
  582. Error rpcp(int p_peer_id, const StringName &p_method, const Variant **p_arg, int p_argcount);
  583. Ref<MultiplayerAPI> get_multiplayer() const;
  584. /* INTERNATIONALIZATION */
  585. void set_auto_translate_mode(AutoTranslateMode p_mode);
  586. AutoTranslateMode get_auto_translate_mode() const;
  587. bool can_auto_translate() const;
  588. virtual StringName get_translation_domain() const override;
  589. virtual void set_translation_domain(const StringName &p_domain) override;
  590. void set_translation_domain_inherited();
  591. _FORCE_INLINE_ String atr(const String &p_message, const StringName &p_context = "") const { return can_auto_translate() ? tr(p_message, p_context) : p_message; }
  592. _FORCE_INLINE_ String atr_n(const String &p_message, const StringName &p_message_plural, int p_n, const StringName &p_context = "") const {
  593. if (can_auto_translate()) {
  594. return tr_n(p_message, p_message_plural, p_n, p_context);
  595. }
  596. return p_n == 1 ? p_message : String(p_message_plural);
  597. }
  598. /* THREADING */
  599. void call_deferred_thread_groupp(const StringName &p_method, const Variant **p_args, int p_argcount, bool p_show_error = false);
  600. template <typename... VarArgs>
  601. void call_deferred_thread_group(const StringName &p_method, VarArgs... p_args) {
  602. Variant args[sizeof...(p_args) + 1] = { p_args..., Variant() }; // +1 makes sure zero sized arrays are also supported.
  603. const Variant *argptrs[sizeof...(p_args) + 1];
  604. for (uint32_t i = 0; i < sizeof...(p_args); i++) {
  605. argptrs[i] = &args[i];
  606. }
  607. call_deferred_thread_groupp(p_method, sizeof...(p_args) == 0 ? nullptr : (const Variant **)argptrs, sizeof...(p_args));
  608. }
  609. void set_deferred_thread_group(const StringName &p_property, const Variant &p_value);
  610. void notify_deferred_thread_group(int p_notification);
  611. void call_thread_safep(const StringName &p_method, const Variant **p_args, int p_argcount, bool p_show_error = false);
  612. template <typename... VarArgs>
  613. void call_thread_safe(const StringName &p_method, VarArgs... p_args) {
  614. Variant args[sizeof...(p_args) + 1] = { p_args..., Variant() }; // +1 makes sure zero sized arrays are also supported.
  615. const Variant *argptrs[sizeof...(p_args) + 1];
  616. for (uint32_t i = 0; i < sizeof...(p_args); i++) {
  617. argptrs[i] = &args[i];
  618. }
  619. call_deferred_thread_groupp(p_method, sizeof...(p_args) == 0 ? nullptr : (const Variant **)argptrs, sizeof...(p_args));
  620. }
  621. void set_thread_safe(const StringName &p_property, const Variant &p_value);
  622. void notify_thread_safe(int p_notification);
  623. // These inherited functions need proper multithread locking when overridden in Node.
  624. #ifdef DEBUG_ENABLED
  625. virtual void set_script(const Variant &p_script) override;
  626. virtual Variant get_script() const override;
  627. virtual bool has_meta(const StringName &p_name) const override;
  628. virtual void set_meta(const StringName &p_name, const Variant &p_value) override;
  629. virtual void remove_meta(const StringName &p_name) override;
  630. virtual Variant get_meta(const StringName &p_name, const Variant &p_default = Variant()) const override;
  631. virtual void get_meta_list(List<StringName> *p_list) const override;
  632. virtual Error emit_signalp(const StringName &p_name, const Variant **p_args, int p_argcount) override;
  633. virtual bool has_signal(const StringName &p_name) const override;
  634. virtual void get_signal_list(List<MethodInfo> *p_signals) const override;
  635. virtual void get_signal_connection_list(const StringName &p_signal, List<Connection> *p_connections) const override;
  636. virtual void get_all_signal_connections(List<Connection> *p_connections) const override;
  637. virtual int get_persistent_signal_connection_count() const override;
  638. virtual void get_signals_connected_to_this(List<Connection> *p_connections) const override;
  639. virtual Error connect(const StringName &p_signal, const Callable &p_callable, uint32_t p_flags = 0) override;
  640. virtual void disconnect(const StringName &p_signal, const Callable &p_callable) override;
  641. virtual bool is_connected(const StringName &p_signal, const Callable &p_callable) const override;
  642. virtual bool has_connections(const StringName &p_signal) const override;
  643. #endif
  644. Node();
  645. ~Node();
  646. };
  647. VARIANT_ENUM_CAST(Node::DuplicateFlags);
  648. VARIANT_ENUM_CAST(Node::ProcessMode);
  649. VARIANT_ENUM_CAST(Node::ProcessThreadGroup);
  650. VARIANT_BITFIELD_CAST(Node::ProcessThreadMessages);
  651. VARIANT_ENUM_CAST(Node::InternalMode);
  652. VARIANT_ENUM_CAST(Node::PhysicsInterpolationMode);
  653. VARIANT_ENUM_CAST(Node::AutoTranslateMode);
  654. typedef HashSet<Node *, Node::Comparator> NodeSet;
  655. // Template definitions must be in the header so they are always fully initialized before their usage.
  656. // See this StackOverflow question for more information: https://stackoverflow.com/questions/495021/why-can-templates-only-be-implemented-in-the-header-file
  657. template <typename... VarArgs>
  658. Error Node::rpc(const StringName &p_method, VarArgs... p_args) {
  659. return rpc_id(0, p_method, p_args...);
  660. }
  661. template <typename... VarArgs>
  662. Error Node::rpc_id(int p_peer_id, const StringName &p_method, VarArgs... p_args) {
  663. Variant args[sizeof...(p_args) + 1] = { p_args..., Variant() }; // +1 makes sure zero sized arrays are also supported.
  664. const Variant *argptrs[sizeof...(p_args) + 1];
  665. for (uint32_t i = 0; i < sizeof...(p_args); i++) {
  666. argptrs[i] = &args[i];
  667. }
  668. return rpcp(p_peer_id, p_method, sizeof...(p_args) == 0 ? nullptr : (const Variant **)argptrs, sizeof...(p_args));
  669. }
  670. #ifdef DEBUG_ENABLED
  671. #define ERR_THREAD_GUARD ERR_FAIL_COND_MSG(!is_accessible_from_caller_thread(), vformat("Caller thread can't call this function in this node (%s). Use call_deferred() or call_thread_group() instead.", get_description()));
  672. #define ERR_THREAD_GUARD_V(m_ret) ERR_FAIL_COND_V_MSG(!is_accessible_from_caller_thread(), (m_ret), vformat("Caller thread can't call this function in this node (%s). Use call_deferred() or call_thread_group() instead.", get_description()));
  673. #define ERR_MAIN_THREAD_GUARD ERR_FAIL_COND_MSG(is_inside_tree() && !is_current_thread_safe_for_nodes(), vformat("This function in this node (%s) can only be accessed from the main thread. Use call_deferred() instead.", get_description()));
  674. #define ERR_MAIN_THREAD_GUARD_V(m_ret) ERR_FAIL_COND_V_MSG(is_inside_tree() && !is_current_thread_safe_for_nodes(), (m_ret), vformat("This function in this node (%s) can only be accessed from the main thread. Use call_deferred() instead.", get_description()));
  675. #define ERR_READ_THREAD_GUARD ERR_FAIL_COND_MSG(!is_readable_from_caller_thread(), vformat("This function in this node (%s) can only be accessed from either the main thread or a thread group. Use call_deferred() instead.", get_description()));
  676. #define ERR_READ_THREAD_GUARD_V(m_ret) ERR_FAIL_COND_V_MSG(!is_readable_from_caller_thread(), (m_ret), vformat("This function in this node (%s) can only be accessed from either the main thread or a thread group. Use call_deferred() instead.", get_description()));
  677. #else
  678. #define ERR_THREAD_GUARD
  679. #define ERR_THREAD_GUARD_V(m_ret)
  680. #define ERR_MAIN_THREAD_GUARD
  681. #define ERR_MAIN_THREAD_GUARD_V(m_ret)
  682. #define ERR_READ_THREAD_GUARD
  683. #define ERR_READ_THREAD_GUARD_V(m_ret)
  684. #endif
  685. // Add these macro to your class's 'get_configuration_warnings' function to have warnings show up in the scene tree inspector.
  686. #define DEPRECATED_NODE_WARNING warnings.push_back(RTR("This node is marked as deprecated and will be removed in future versions.\nPlease check the Godot documentation for information about migration."));
  687. #define EXPERIMENTAL_NODE_WARNING warnings.push_back(RTR("This node is marked as experimental and may be subject to removal or major changes in future versions."));