creating_icons.rst 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990
  1. .. _doc_editor_icons:
  2. Editor icons
  3. ============
  4. When a new class is created and exposed to scripting, the editor's interface
  5. will display it with a default icon representing the base class it inherits
  6. from. In most cases, it's still recommended to create icons for new classes to
  7. improve the user experience.
  8. Creating icons
  9. ~~~~~~~~~~~~~~
  10. To create new icons, you first need a vector graphics editor installed.
  11. For instance, you can use the open source `Inkscape <https://inkscape.org/>`_ editor.
  12. Clone the ``godot`` repository containing all the editor icons:
  13. .. code-block:: bash
  14. git clone https://github.com/godotengine/godot.git
  15. The icons must be created in a vector graphics editor in SVG format. There are
  16. two main requirements to follow:
  17. - Icons must be 16×16. In Inkscape, you can configure the document size in
  18. **File > Document Properties**.
  19. - Lines should be snapped to pixels whenever possible to remain crisp at lower DPI.
  20. You can create a 16×16 grid in Inkscape to make this easier.
  21. Once you're satisfied with the icon's design, save the icon in the cloned
  22. repository's ``editor/icons`` folder. The icon name should match the intended
  23. name in a case-sensitive manner. For example, to create an icon for
  24. CPUParticles2D, name the file ``CPUParticles2D.svg``.
  25. Color conversion for light editor themes
  26. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  27. If the user has configured their editor to use a light theme, Godot will
  28. convert the icon's colors based on a
  29. `set of predefined color mappings <https://github.com/godotengine/godot/blob/4.0.2-stable/editor/editor_themes.cpp#L60-L160>`__.
  30. This is to ensure the icon always displays with a sufficient contrast rate.
  31. Try to restrict your icon's color palette to colors found in the list above.
  32. Otherwise, your icon may become difficult to read on a light background.
  33. Icon optimization
  34. ~~~~~~~~~~~~~~~~~
  35. Because the editor renders SVGs once at load time, they need to be small
  36. in size so they can be efficiently parsed. When the
  37. :ref:`pre-commit hook <doc_code_style_guidelines_pre_commit_hook>` runs, it automatically optimizes
  38. the SVG using `svgo <https://github.com/svg/svgo>`_.
  39. .. note::
  40. While this optimization step won't impact the icon's quality noticeably, it
  41. will still remove editor-only information such as guides. Therefore, it's
  42. recommended to keep the source SVG around if you need to make further
  43. changes.
  44. Integrating and sharing the icons
  45. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  46. If you're contributing to the engine itself, you should make a pull request to
  47. add optimized icons to ``editor/icons`` in the main repository. Recompile the
  48. engine to make it pick up new icons for classes.
  49. It's also possible to create custom icons within a module. If you're creating
  50. your own module and don't plan to integrate it with Godot, you don't need to
  51. make a separate pull request for your icons to be available within the editor
  52. as they can be self-contained.
  53. For specific instructions on how to create module icons, refer to
  54. :ref:`Creating custom module icons<doc_custom_module_icons>`.
  55. Troubleshooting
  56. ~~~~~~~~~~~~~~~
  57. If icons don't appear in the editor, make sure that:
  58. 1. Each icon's filename matches the naming requirement as described previously.
  59. 2. ``modules/svg`` is enabled (it should be enabled by default). Without it,
  60. icons won't appear in the editor at all.
  61. References
  62. ~~~~~~~~~~
  63. - `editor/icons <https://github.com/godotengine/godot/tree/master/editor/icons>`__