Editor icons: SVG, import and palette
Plugin and core icons: integration, scale, color and troubleshooting.
Editor icons
Choose the integration path first. A plugin button icon and a built-in class icon reach the editor through different mechanisms.
| Task | Solution |
|---|---|
| Standard icon on a plugin button | Read it through EditorInterface.Singleton.GetEditorTheme() under the EditorIcons theme type; check HasIcon first. Working example. |
| Custom SVG in a project or plugin | Add the file to the project, configure import and use it as Texture2D. No engine rebuild is needed. |
| Built-in icon for a new C++ class | Add SVG to editor or module sources and build a separate editor. Importing a project file does not register a built-in icon. |
Prepare the SVG
For an ordinary panel icon, use a 16×16 canvas, transparent background and a simple readable shape. This is a design size, not a ban on larger images: thumbnails and other specialized icons can use different sizes.
Align straight boundaries to the pixel grid and inspect at 1×. Do not shrink a complex illustration to 16 pixels. Convert text to paths; do not depend on a font installed only on the author's machine.
Save the following file as asset://addons/my_tool/icons/CreateItem.svg:
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
<path fill="#e0e0e0" d="M7 2h2v5h5v2H9v5H7V9H2V7h5z"/>
</svg>The #e0e0e0 color belongs to the editor palette. The current light-theme conversion table replaces it with #5a5a5a; white #ffffff becomes #414141. These are mappings from Source/editor/themes/editor_color_map.cpp, not automatic contrast repair for arbitrary SVG. Other colors may remain unchanged. Do not enable conversion blindly for branded artwork.
Import a plugin icon
- Select the SVG in the project resource browser and open the Import panel.
- For a tool icon, enable Editor → Scale with Editor Scale. Its exact setting key is
editor/scale_with_editor_scale. - If the icon uses the editor palette, enable Editor → Convert Colors with Editor Theme:
editor/convert_colors_with_editor_theme. - Click Reimport. SVG also has the base multiplier
svg/scale; usually leave it at 1.0 to avoid scaling twice. - Assign the imported Texture2D to your button's Icon property or use it in another plugin control. The panel lifecycle guide covers creating and removing controls.
These options produce a separate editor texture variant; they do not globally recolor the original game image. Leave editor options disabled for ordinary game artwork. If the options are absent, check that the selected source is SVG, rather than PNG or an already imported resource.
Add a built-in icon
This path is for engine-core development. Shared icons in the current source tree live in Source/editor/icons/. The SVG filename without extension becomes a theme key: for a class, use its exact name and case. Do not introduce another file with the same name from a different module.
editor/icons/SCsub collects SVG from the shared directory and module paths; editor_icons_builders.py generates editor/themes/editor_icons.gen.h. Do not edit the generated header manually. A module can supply a directory through get_icons_path() in its config.py; modules/voxel/config.py contains an implementation example.
After editing, build a separate target=editor using the build guide. Reimporting a project cannot add source icons to an already installed binary. Preserve the original SVG before optimization: an optimizer can remove image-editor authoring data.
Diagnose an incorrect result
| Symptom | Check |
|---|---|
| Missing icon | Path, filename case and import result; for a built-in icon, the binary actually launched and SVG support in that build. |
| Dark icon disappears on a light theme | Palette and conversion option; for a button also inspect disabled, hover and focus states. |
| Icon is too large | svg/scale, editor scale, control minimum size and any extra manual scaling. |
| Blurry lines at 1× | Pixel-grid alignment and drawing complexity; enlarging PNG does not restore vector boundaries. |
The published SVG was checked in the installed engine: loading, 16×16 and 32×32 rasterization, transparency, fill color and explicit palette replacement through DPITexture. Manual import configuration, theme/DPI switching and integrating a new icon into a C++ build were not performed in this run. This is a resource example, not an interface screenshot.