From 209af20763f89e0692a4f84e508ca99f7733fdba Mon Sep 17 00:00:00 2001 From: "Andrii Doroshenko (Xrayez)" Date: Tue, 2 Jul 2019 21:55:49 +0300 Subject: [PATCH] Describe the process of creating editor icons globally and per module Also created a new `Editor development` chapter/section to encompass C++ editor development side specifically which is not necessarily related to pure core development, generic types and patterns. --- development/cpp/custom_modules_in_cpp.rst | 29 +++++++ development/editor/creating_icons.rst | 98 +++++++++++++++++++++++ development/editor/index.rst | 9 +++ development/editor/introduction.rst | 9 +++ index.rst | 1 + 5 files changed, 146 insertions(+) create mode 100644 development/editor/creating_icons.rst create mode 100644 development/editor/index.rst create mode 100644 development/editor/introduction.rst diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst index 4b9697843..41eadd1e2 100644 --- a/development/cpp/custom_modules_in_cpp.rst +++ b/development/cpp/custom_modules_in_cpp.rst @@ -410,6 +410,35 @@ the docs will become accessible within the engine's built-in documentation syste In order to keep documentation up-to-date, all you'll have to do is simply modify one of the ``ClassName.xml`` files and recompile the engine from now on. +.. _doc_custom_module_icons: + +Adding custom editor icons +-------------------------- + +Similarly to how you can write self-contained documentation within a module, +you can also create your own custom icons for classes to appear in the editor. + +For the actual process of creating editor icons to be integrated within the engine, +please refer to :ref:`doc_editor_icons` first. + +Once you've created your icon(s), proceed with the following steps: + +1. Make a new directory in the root of the module named ``icons``. This is the + default path for the engine to look for module's editor icons. + +2. Move your newly created ``svg`` icons (optimized or not) into that folder. + +3. Recompile the engine and run the editor. Now the icon(s) will appear in + editor's interface where appropriate. + +If you'd like to store your icons somewhere else within your module, +add the following code snippet to ``config.py`` to override the default path: + + .. code:: python + + def get_icons_path(): + return "path/to/icons" + Summing up ---------- diff --git a/development/editor/creating_icons.rst b/development/editor/creating_icons.rst new file mode 100644 index 000000000..e10f5582e --- /dev/null +++ b/development/editor/creating_icons.rst @@ -0,0 +1,98 @@ +.. _doc_editor_icons: + +Editor icons +============ + +When a new class is created and exposed to scripting, the editor's interface +will display it with a default icon representing the base class it inherits +from. Yet in most cases it is recommended to create icons for new classes +to improve the user experience. + +Creating icons +~~~~~~~~~~~~~~ + +In order to create new icons, you first need a vector graphics editor installed. +For instance, you can use the open-source `Inkscape `_ editor. + +Clone the ``godot-design`` repository containing all the original editor icons: + + .. code:: bash + + git clone https://github.com/godotengine/godot-design + +The icons must be created in a vector graphics editor in ``svg`` format. You +can use ``engine/icons/inkscape_template.svg`` with default icon properties +already set up. + +Once you're satisfied with the icon's design, save the icon in +``engine/icons/svg/`` folder. But in order for the engine to automatically +pick up the icons, each icon's filename: + +1. Must be prefixed with ``icon_``. + +2. ``PascalCase`` name should be converted to ``snake_case``, so words + are separated by ``_`` whenever case changes, and uppercase acronyms must + also have all letters, numbers, and special characters separated as distinct + words. Some examples: + + +--------------------+----------------------------------+ + | Name | Filename | + +====================+==================================+ + | ``Polygon2D`` | ``icon_polygon_2_d.svg`` | + +--------------------+----------------------------------+ + | ``CSGPolygon`` | ``icon_c_s_g_polygon.svg`` | + +--------------------+----------------------------------+ + | ``CPUParticles2D`` | ``icon_c_p_u_particles_2_d.svg`` | + +--------------------+----------------------------------+ + | ``C#`` | ``icon_c_#.svg`` | + +--------------------+----------------------------------+ + +Icon optimization +~~~~~~~~~~~~~~~~~ + +Because the editor renders the ``svg``'s at runtime, they need to be small +in size, so they can be efficiently parsed. Editor icons must be first +optimized before being added to the engine, to do so: + +1. Add them to the ``engine/icons/svg`` folder. + +2. Run the ``optimize.py`` script. You must have the ``scour`` package installed: + + .. code:: bash + + pip install scour + cd godot-design/engine/icons && ./optimize.py + +The optimized icons will be generated in the ``engine/icons/optimized`` folder. + +Integrating and sharing the icons +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're contributing to the engine itself, you should make a pull request to +add optimized icons to ``godot/editor/icons`` in the main repository. Recompile +the engine to make sure it does pick up new icons for classes. Once merged, +don't forget to add the original version of the icons to the ``godot-design`` +repository so that the icon can be improved upon by other contributors. + +It's also possible to create custom icons within a module. If you're creating +your own module and don't plan to integrate it with Godot, you don't need to +make a separate pull request for your icons to be available within the editor +as they can be self-contained. + +For specific instructions on how to create module icons, refer to +:ref:`Creating custom module icons`. + +Troubleshooting +~~~~~~~~~~~~~~~ + +If icons don't appear in the editor make sure that: + +1. Each icon's filename matches the naming requirement as described previously. + +2. ``modules/svg`` is enabled (should be enabled by default). Without it, icons + won't appear in the editor at all. + +References: +~~~~~~~~~~~ + +- `editor/icons `__ diff --git a/development/editor/index.rst b/development/editor/index.rst new file mode 100644 index 000000000..b54f1c7c3 --- /dev/null +++ b/development/editor/index.rst @@ -0,0 +1,9 @@ +Editor development +================== + +.. toctree:: + :maxdepth: 1 + :name: toc-devel-editor + + introduction + creating_icons diff --git a/development/editor/introduction.rst b/development/editor/introduction.rst new file mode 100644 index 000000000..bd8ea0aaa --- /dev/null +++ b/development/editor/introduction.rst @@ -0,0 +1,9 @@ +.. _doc_editor_intro: + +Introduction +============ + +As the engine is constantly evolving and new features are being added, it is +important to familiarize yourself with the editor and tools development in C++. +Without the editor, some of the engine's internal functionality would become +unaccessible and make the development not intuitive. diff --git a/index.rst b/index.rst index e31bb99be..b1a5d4c41 100644 --- a/index.rst +++ b/index.rst @@ -111,6 +111,7 @@ The main documentation for the site is organized into the following sections: development/compiling/index development/cpp/index + development/editor/index development/file_formats/index