{"slug":"jame581-addon-development","name":"addon-development","description":"Use when creating Godot editor plugins — EditorPlugin, @tool scripts, custom inspectors, and dock panels","long_description":"---\nname: addon-development\ndescription: Use when creating Godot editor plugins — EditorPlugin, @tool scripts, custom inspectors, and dock panels\n---\n\n# Addon Development in Godot 4.3+\n\nEditor plugins extend the Godot editor itself: custom node types, inspector panels, dock widgets, 3D gizmos, and toolbar buttons. All examples target Godot 4.3+ with no deprecated APIs.\n\n> **Related skills:** **resource-pattern** for custom Resource editors, **godot-ui** for editor panel UI, **csharp-godot** for C# plugin development.\n\n---\n\n## 1. Plugin Structure\n\nEvery plugin lives inside `addons/` at the project root. Godot discovers plugins by scanning for `plugin.cfg` files.\n\n```\nres://\n└── addons/\n └── my_plugin/\n ├── plugin.cfg # required — plugin metadata\n ├── plugin.gd # main EditorPlugin script (named in plugin.cfg)\n ├── my_inspector.gd # optional — EditorInspectorPlugin\n ├── my_dock.tscn # optional — dock panel scene\n └── icons/\n └── my_node.svg # optional — custom node icons\n```\n\n`plugin.cfg` is a plain INI file. Godot reads it when scanning `addons/`. The `script` key must point to the main plugin script relative to the plugin folder.\n\nEnable the plugin: **Project → Project Settings → Plugins** → tick the checkbox next to your plugin name.\n\n---\n\n## 2. @tool Annotation\n\n`@tool` makes a GDScript (or its C# equivalent) run inside the editor process as well as at runtime. Without it, the script only runs when the game is playing.\n\n### GDScript\n\n```gdscript\n@tool\nextends Sprite2D\n\n# Engine.is_editor_hint() is true when running inside the editor,\n# false during a running game. Use it to guard editor-only logic.\nfunc _process(delta: float) -> void:\n if Engine.is_editor_hint():\n # This block runs in the editor viewport — safe to call editor APIs.\n update_configuration_warnings()\n else:\n # Normal game logic here.\n pass\n\n\n# _get_configuration_warnings() returns an array of strings shown as\n# yellow warning icons on the node in the Scene panel.\nfunc _get_configuration_warnings() -> PackedStringArray:\n var warnings := PackedStringArray()\n if texture == null:\n warnings.append(\"Texture is not set. Assign a Texture2D in the Inspector.\")\n return warnings\n```\n\n### C#\n\n```csharp\n#if TOOLS\nusing Godot;\n\n[Tool]\npublic partial class MyToolSprite : Sprite2D\n{\n public override void _Process(double delta)\n {\n if (Engine.IsEditorHint())\n {\n // Editor-only logic — safe to call editor APIs here.\n UpdateConfigurationWarnings();\n }\n else\n {\n // Normal game logic.\n }\n }\n\n public override string[] _GetConfigurationWarnings()\n {\n if (Texture == null)\n return new[] { \"Texture is not set. Assign a Texture2D in the Inspector.\" };\n return System.Array.Empty();\n }\n}\n#endif\n```\n\n> Wrap C# tool scripts in `#if TOOLS` / `#endif` to prevent the class from being included in exported builds. GDScript `@tool` scripts are excluded from exports automatically.\n\n**Key rules:**\n- Add `@tool` / `[Tool]` at the top of every script that needs editor access.\n- Always guard runtime-only code with `Engine.is_editor_hint()` to avoid crashing the editor when processing begins before the scene is fully loaded.\n- Call `update_configuration_warnings()` whenever a property changes that might affect the warning state.\n\n---\n\n## 3. EditorPlugin Base\n\nThe main plugin script extends `EditorPlugin`. Godot calls `_enter_tree()` when the plugin is enabled and `_exit_tree()` when it is disabled or the project is closed. **Everything added in `_enter_tree()` must be removed in `_exit_tree()`.**\n\n### GDScript\n\n```gdscript\n# plugin.gd\n@tool\nextends EditorPlugin\n\n\nfunc _enter_tree() -> void:\n # Register a custom node type. The editor shows MyNode in the\n # \"Add Node\" dialog under the chosen base class, with a custom icon.\n add_custom_type(\n \"MyNode\", # name shown in editor\n \"Node2D\", # base class to extend\n preload(\"res://addons/my_plugin/my_node.gd\"),\n preload(\"res://addons/my_plugin/icons/my_node.svg\")\n )\n\n # Add a menu item to the Project menu (top toolbar).\n add_tool_menu_item(\"My Plugin Action\", _on_tool_menu_item)\n\n\nfunc _exit_tree() -> void:\n remove_custom_type(\"MyNode\")\n remove_tool_menu_item(\"My Plugin Action\")\n\n\nfunc _on_tool_menu_item() -> void:\n print(\"My Plugin Action triggered\")\n```\n\n### C#\n\n```csharp\n// Plugin.cs\n#if TOOLS\nusing Godot;\n\n[Tool]\npublic partial class MyPlugin : EditorPlugin\n{\n public override void _EnterTree()\n {\n AddCustomType(\n \"MyNode\",\n \"Node2D\",\n GD.Load