running_code_in_the_editor.rst 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627
  1. .. _doc_running_code_in_the_editor:
  2. Running code in the editor
  3. ==========================
  4. What is ``@tool``?
  5. ------------------
  6. ``@tool`` is a powerful line of code that, when added at the top of your script,
  7. makes it execute in the editor. You can also decide which parts of the script
  8. execute in the editor, which in game, and which in both.
  9. You can use it for doing many things, but it is mostly useful in level design
  10. for visually presenting things that are hard to predict ourselves. Here are some
  11. use cases:
  12. - If you have a cannon that shoots cannonballs affected by physics (gravity),
  13. you can draw the cannonball's trajectory in the editor, making level design a
  14. lot easier.
  15. - If you have jumppads with varying jump heights, you can draw the maximum jump
  16. height a player would reach if it jumped on one, also making level design
  17. easier.
  18. - If your player doesn't use a sprite, but draws itself using code, you can make
  19. that drawing code execute in the editor to see your player.
  20. .. danger::
  21. ``@tool`` scripts run inside the editor, and let you access the scene tree
  22. of the currently edited scene. This is a powerful feature which also comes
  23. with caveats, as the editor does not include protections for potential
  24. misuse of ``@tool`` scripts.
  25. Be **extremely** cautious when manipulating the scene tree, especially via
  26. :ref:`Node.queue_free<class_Node_method_queue_free>`, as it can cause
  27. crashes if you free a node while the editor runs logic involving it.
  28. How to use ``@tool``
  29. --------------------
  30. To turn a script into a tool, add the ``@tool`` annotation at the top of your code.
  31. To check if you are currently in the editor, use: ``Engine.is_editor_hint()``.
  32. For example, if you want to execute some code only in the editor, use:
  33. .. tabs::
  34. .. code-tab:: gdscript GDScript
  35. if Engine.is_editor_hint():
  36. # Code to execute when in editor.
  37. .. code-tab:: csharp
  38. if (Engine.IsEditorHint())
  39. {
  40. // Code to execute when in editor.
  41. }
  42. On the other hand, if you want to execute code only in game, simply negate the
  43. same statement:
  44. .. tabs::
  45. .. code-tab:: gdscript GDScript
  46. if not Engine.is_editor_hint():
  47. # Code to execute when in game.
  48. .. code-tab:: csharp
  49. if (!Engine.IsEditorHint())
  50. {
  51. // Code to execute when in game.
  52. }
  53. Pieces of code that do not have either of the 2 conditions above will run both
  54. in-editor and in-game.
  55. Here is how a ``_process()`` function might look for you:
  56. .. tabs::
  57. .. code-tab:: gdscript GDScript
  58. func _process(delta):
  59. if Engine.is_editor_hint():
  60. # Code to execute in editor.
  61. if not Engine.is_editor_hint():
  62. # Code to execute in game.
  63. # Code to execute both in editor and in game.
  64. .. code-tab:: csharp
  65. public override void _Process(double delta)
  66. {
  67. if (Engine.IsEditorHint())
  68. {
  69. // Code to execute in editor.
  70. }
  71. if (!Engine.IsEditorHint())
  72. {
  73. // Code to execute in game.
  74. }
  75. // Code to execute both in editor and in game.
  76. }
  77. Important information
  78. ---------------------
  79. Any other GDScript that your tool script uses must *also* be a tool. Any
  80. GDScript without ``@tool`` used by the editor will act like an empty file!
  81. Extending a ``@tool`` script does not automatically make the extending script
  82. a ``@tool``. Omitting ``@tool`` from the extending script will disable tool
  83. behavior from the super class. Therefore the extending script should also
  84. specify the ``@tool`` annotation.
  85. Modifications in the editor are permanent. For example, in the next
  86. section when we remove the script, the node will keep its rotation. Be careful
  87. to avoid making unwanted modifications.
  88. Try ``@tool`` out
  89. -----------------
  90. Add a ``Sprite2D`` node to your scene and set the texture to Godot icon. Attach
  91. and open a script, and change it to this:
  92. .. tabs::
  93. .. code-tab:: gdscript GDScript
  94. @tool
  95. extends Sprite2D
  96. func _process(delta):
  97. rotation += PI * delta
  98. .. code-tab:: csharp
  99. using Godot;
  100. [Tool]
  101. public partial class MySprite : Sprite2D
  102. {
  103. public override void _Process(double delta)
  104. {
  105. Rotation += Mathf.Pi * (float)delta;
  106. }
  107. }
  108. Save the script and return to the editor. You should now see your object rotate.
  109. If you run the game, it will also rotate.
  110. .. warning::
  111. You may need to restart the editor. This is a known bug found in all Godot 4 versions:
  112. `GH-66381 <https://github.com/godotengine/godot/issues/66381>`_.
  113. .. image:: img/rotating_in_editor.gif
  114. .. note::
  115. If you don't see the changes, reload the scene (close it and open it again).
  116. Now let's choose which code runs when. Modify your ``_process()`` function to
  117. look like this:
  118. .. tabs::
  119. .. code-tab:: gdscript GDScript
  120. func _process(delta):
  121. if Engine.is_editor_hint():
  122. rotation += PI * delta
  123. else:
  124. rotation -= PI * delta
  125. .. code-tab:: csharp
  126. public override void _Process(double delta)
  127. {
  128. if (Engine.IsEditorHint())
  129. {
  130. Rotation += Mathf.Pi * (float)delta;
  131. }
  132. else
  133. {
  134. Rotation -= Mathf.Pi * (float)delta;
  135. }
  136. }
  137. Save the script. Now the object will spin clockwise in the editor, but if you
  138. run the game, it will spin counter-clockwise.
  139. Editing variables
  140. -----------------
  141. Add and export a variable speed to the script. To update the speed and also reset the rotation
  142. angle add a setter ``set(new_speed)`` which is executed with the input from the inspector. Modify
  143. ``_process()`` to include the rotation speed.
  144. .. tabs::
  145. .. code-tab:: gdscript GDScript
  146. @tool
  147. extends Sprite2D
  148. @export var speed = 1:
  149. # Update speed and reset the rotation.
  150. set(new_speed):
  151. speed = new_speed
  152. rotation = 0
  153. func _process(delta):
  154. rotation += PI * delta * speed
  155. .. code-tab:: csharp
  156. using Godot;
  157. [Tool]
  158. public partial class MySprite : Sprite2D
  159. {
  160. private float _speed = 1;
  161. [Export]
  162. public float Speed
  163. {
  164. get => _speed;
  165. set
  166. {
  167. // Update speed and reset the rotation.
  168. _speed = value;
  169. Rotation = 0;
  170. }
  171. }
  172. public override void _Process(double delta)
  173. {
  174. Rotation += Mathf.Pi * (float)delta * speed;
  175. }
  176. }
  177. .. note::
  178. Code from other nodes doesn't run in the editor. Your access to other nodes
  179. is limited. You can access the tree and nodes, and their default properties,
  180. but you can't access user variables. If you want to do so, other nodes have
  181. to run in the editor too. Autoload nodes cannot be accessed in the editor at
  182. all.
  183. Getting notified when resources change
  184. --------------------------------------
  185. Sometimes you want your tool to use a resource. However, when you change a
  186. property of that resource in the editor, the ``set()`` method of your tool will
  187. not be called.
  188. .. tabs::
  189. .. code-tab:: gdscript GDScript
  190. @tool
  191. class_name MyTool
  192. extends Node
  193. @export var resource: MyResource:
  194. set(new_resource):
  195. resource = new_resource
  196. _on_resource_set()
  197. # This will only be called when you create, delete, or paste a resource.
  198. # You will not get an update when tweaking properties of it.
  199. func _on_resource_set():
  200. print("My resource was set!")
  201. .. code-tab:: csharp
  202. using Godot;
  203. [Tool]
  204. public partial class MyTool : Node
  205. {
  206. private MyResource _resource;
  207. [Export]
  208. public MyResource Resource
  209. {
  210. get => _resource;
  211. set
  212. {
  213. _resource = value;
  214. OnResourceSet();
  215. }
  216. }
  217. }
  218. // This will only be called when you create, delete, or paste a resource.
  219. // You will not get an update when tweaking properties of it.
  220. private void OnResourceSet()
  221. {
  222. GD.Print("My resource was set!");
  223. }
  224. To get around this problem you first have to make your resource a tool and make it
  225. emit the ``changed`` signal whenever a property is set:
  226. .. tabs::
  227. .. code-tab:: gdscript GDScript
  228. # Make Your Resource a tool.
  229. @tool
  230. class_name MyResource
  231. extends Resource
  232. @export var property = 1:
  233. set(new_setting):
  234. property = new_setting
  235. # Emit a signal when the property is changed.
  236. changed.emit()
  237. .. code-tab:: csharp
  238. using Godot;
  239. [Tool]
  240. public partial class MyResource : Resource
  241. {
  242. private float _property = 1;
  243. [Export]
  244. public float Property
  245. {
  246. get => _property;
  247. set
  248. {
  249. _property = value;
  250. // Emit a signal when the property is changed.
  251. EmitChanged();
  252. }
  253. }
  254. }
  255. You then want to connect the signal when a new resource is set:
  256. .. tabs::
  257. .. code-tab:: gdscript GDScript
  258. @tool
  259. class_name MyTool
  260. extends Node
  261. @export var resource: MyResource:
  262. set(new_resource):
  263. resource = new_resource
  264. # Connect the changed signal as soon as a new resource is being added.
  265. resource.changed.connect(_on_resource_changed)
  266. func _on_resource_changed():
  267. print("My resource just changed!")
  268. .. code-tab:: csharp
  269. using Godot;
  270. [Tool]
  271. public partial class MyTool : Node
  272. {
  273. private MyResource _resource;
  274. [Export]
  275. public MyResource Resource
  276. {
  277. get => _resource;
  278. set
  279. {
  280. _resource = value;
  281. // Connect the changed signal as soon as a new resource is being added.
  282. _resource.Changed += OnResourceChanged;
  283. }
  284. }
  285. }
  286. private void OnResourceChanged()
  287. {
  288. GD.Print("My resource just changed!");
  289. }
  290. Lastly, remember to disconnect the signal as the old resource being used and changed somewhere else
  291. would cause unneeded updates.
  292. .. tabs::
  293. .. code-tab:: gdscript GDScript
  294. @export var resource: MyResource:
  295. set(new_resource):
  296. # Disconnect the signal if the previous resource was not null.
  297. if resource != null:
  298. resource.changed.disconnect(_on_resource_changed)
  299. resource = new_resource
  300. resource.changed.connect(_on_resource_changed)
  301. .. code-tab:: csharp
  302. [Export]
  303. public MyResource Resource
  304. {
  305. get => _resource;
  306. set
  307. {
  308. // Disconnect the signal if the previous resource was not null.
  309. if (_resource != null)
  310. {
  311. _resource.Changed -= OnResourceChanged;
  312. }
  313. _resource = value;
  314. _resource.Changed += OnResourceChanged;
  315. }
  316. }
  317. Reporting node configuration warnings
  318. -------------------------------------
  319. Godot uses a *node configuration warning* system to warn users about incorrectly
  320. configured nodes. When a node isn't configured correctly, a yellow warning sign
  321. appears next to the node's name in the Scene dock. When you hover or click on
  322. the icon, a warning message pops up. You can use this feature in your scripts to
  323. help you and your team avoid mistakes when setting up scenes.
  324. When using node configuration warnings, when any value that should affect or
  325. remove the warning changes, you need to call
  326. :ref:`update_configuration_warnings<class_Node_method_update_configuration_warnings>` .
  327. By default, the warning only updates when closing and reopening the scene.
  328. .. tabs::
  329. .. code-tab:: gdscript GDScript
  330. # Use setters to update the configuration warning automatically.
  331. @export var title = "":
  332. set(p_title):
  333. if p_title != title:
  334. title = p_title
  335. update_configuration_warnings()
  336. @export var description = "":
  337. set(p_description):
  338. if p_description != description:
  339. description = p_description
  340. update_configuration_warnings()
  341. func _get_configuration_warnings():
  342. var warnings = []
  343. if title == "":
  344. warnings.append("Please set `title` to a non-empty value.")
  345. if description.length() >= 100:
  346. warnings.append("`description` should be less than 100 characters long.")
  347. # Returning an empty array means "no warning".
  348. return warnings
  349. .. _doc_running_code_in_the_editor_editorscript:
  350. Running one-off scripts using EditorScript
  351. ------------------------------------------
  352. Sometimes, you need to run code just one time to automate a certain task that is
  353. not available in the editor out of the box. Some examples might be:
  354. - Use as a playground for GDScript or C# scripting without having to run a project.
  355. ``print()`` output is displayed in the editor Output panel.
  356. - Scale all light nodes in the currently edited scene, as you noticed your level
  357. ends up looking too dark or too bright after placing lights where desired.
  358. - Replace nodes that were copy-pasted with scene instances to make them easier
  359. to modify later.
  360. This is available in Godot by extending :ref:`class_EditorScript` in a script.
  361. This provides a way to run individual scripts in the editor without having to
  362. create an editor plugin.
  363. To create an EditorScript, right-click a folder or empty space in the FileSystem
  364. dock then choose **New > Script...**. In the script creation dialog, click the
  365. tree icon to choose an object to extend from (or enter ``EditorScript`` directly
  366. in the field on the left, though note this is case-sensitive):
  367. .. figure:: img/running_code_in_the_editor_creating_editor_script.webp
  368. :align: center
  369. :alt: Creating an editor script in the script editor creation dialog
  370. Creating an editor script in the script editor creation dialog
  371. This will automatically select a script template that is suited for
  372. EditorScripts, with a ``_run()`` method already inserted:
  373. ::
  374. @tool
  375. extends EditorScript
  376. # Called when the script is executed (using File -> Run in Script Editor).
  377. func _run():
  378. pass
  379. This ``_run()`` method is executed when you use **File > Run** or the keyboard
  380. shortcut :kbd:`Ctrl + Shift + X` while the EditorScript is the currently open
  381. script in the script editor. This keyboard shortcut is only effective when
  382. currently focused on the script editor.
  383. Scripts that extend EditorScript must be ``@tool`` scripts to function.
  384. .. danger::
  385. EditorScripts have no undo/redo functionality, so **make sure to save your
  386. scene before running one** if the script is designed to modify any data.
  387. To access nodes in the currently edited scene, use the
  388. :ref:`EditorScript.get_scene <class_EditorScript_method_get_scene>` method which
  389. returns the root Node of the currently edited scene. Here's an example that
  390. recursively gets all nodes in the currently edited scene and doubles the range
  391. of all OmniLight3D nodes:
  392. ::
  393. @tool
  394. extends EditorScript
  395. func _run():
  396. for node in get_all_children(get_scene()):
  397. if node is OmniLight3D:
  398. # Don't operate on instanced subscene children, as changes are lost
  399. # when reloading the scene.
  400. # See the "Instancing scenes" section below for a description of `owner`.
  401. var is_instanced_subscene_child = node != get_scene() and node.owner != get_scene()
  402. if not is_instanced_subscene_child:
  403. node.omni_range *= 2.0
  404. # This function is recursive: it calls itself to get lower levels of child nodes as needed.
  405. # `children_acc` is the accumulator parameter that allows this function to work.
  406. # It should be left to its default value when you call this function directly.
  407. func get_all_children(in_node, children_acc = []):
  408. children_acc.push_back(in_node)
  409. for child in in_node.get_children():
  410. children_acc = get_all_children(child, children_acc)
  411. return children_acc
  412. .. tip::
  413. You can change the currently edited scene at the top of the editor even
  414. while the Script view is open. This will affect the return value of
  415. :ref:`EditorScript.get_scene <class_EditorScript_method_get_scene>`, so make
  416. sure you've selected the scene you intend to iterate upon before running
  417. the script.
  418. Instancing scenes
  419. -----------------
  420. You can instantiate packed scenes normally and add them to the scene currently
  421. opened in the editor. By default, nodes or scenes added with
  422. :ref:`Node.add_child(node) <class_Node_method_add_child>` are **not** visible
  423. in the Scene tree dock and are **not** persisted to disk. If you wish the node
  424. or scene to be visible in the scene tree dock and persisted to disk when saving
  425. the scene, you need to set the child node's :ref:`owner <class_Node_property_owner>`
  426. property to the currently edited scene root.
  427. If you are using ``@tool``:
  428. .. tabs::
  429. .. code-tab:: gdscript GDScript
  430. func _ready():
  431. var node = Node3D.new()
  432. add_child(node) # Parent could be any node in the scene
  433. # The line below is required to make the node visible in the Scene tree dock
  434. # and persist changes made by the tool script to the saved scene file.
  435. node.owner = get_tree().edited_scene_root
  436. .. code-tab:: csharp
  437. public override void _Ready()
  438. {
  439. var node = new Node3D();
  440. AddChild(node); // Parent could be any node in the scene
  441. // The line below is required to make the node visible in the Scene tree dock
  442. // and persist changes made by the tool script to the saved scene file.
  443. node.Owner = GetTree().EditedSceneRoot;
  444. }
  445. If you are using :ref:`EditorScript<class_EditorScript>`:
  446. .. tabs::
  447. .. code-tab:: gdscript GDScript
  448. func _run():
  449. # `parent` could be any node in the scene.
  450. var parent = get_scene().get_node("Parent")
  451. var node = Node3D.new()
  452. parent.add_child(node)
  453. # The line below is required to make the node visible in the Scene tree dock
  454. # and persist changes made by the tool script to the saved scene file.
  455. node.owner = get_scene()
  456. .. code-tab:: csharp
  457. public override void _Run()
  458. {
  459. // `parent` could be any node in the scene.
  460. var parent = GetScene().GetNode("Parent");
  461. var node = new Node3D();
  462. parent.AddChild(node);
  463. // The line below is required to make the node visible in the Scene tree dock
  464. // and persist changes made by the tool script to the saved scene file.
  465. node.Owner = GetScene();
  466. }
  467. .. warning::
  468. Using ``@tool`` improperly can yield many errors. It is advised to first
  469. write the code how you want it, and only then add the ``@tool`` annotation to
  470. the top. Also, make sure to separate code that runs in-editor from code that
  471. runs in-game. This way, you can find bugs more easily.