feat(godot): add godot plugin (#50)

Author: elringus

docs/.vitepress/config.ts

@@ -51,7 +51,8 @@ export default defineConfig({
                         { text: "API", link: "/guide/api" },
                         { text: "ABI", link: "/guide/abi" },
                         { text: "CLI", link: "/guide/cli" },
-                        { text: "Unity", link: "/guide/unity" }
+                        { text: "Unity", link: "/guide/unity" },
+                        { text: "Godot", link: "/guide/godot" },
                     ]
                 }
             ]

docs/guide/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-SpriteDicing comes in 3 forms: native C ABI library for embedding into other applications, such as game engines or frameworks, standalone CLI executable to use the tool directly and Unity game engine package.
+SpriteDicing comes in three forms: native C ABI library for embedding into other applications, such as game engines or frameworks, standalone CLI executable to use the tool directly and first-party plugins for the Unity and Godot game engines.
 
 Download artifacts for the latest release via the links below:
 
@@ -20,4 +20,5 @@ For more information on how to use each type of the artifact, refer to the dedic
 - [Rust crate](/guide/api)
 - [Native C ABI library](/guide/abi)
 - [CLI Tool](/guide/cli)
-- [Unity integration](/guide/unity)
+- [Unity plugin](/guide/unity)
+- [Godot plugin](/guide/godot)

docs/guide/godot.md

@@ -0,0 +1,139 @@
+# Godot
+
+SpriteDicing has a [Godot](https://godotengine.org/) integration with a full-fledged atlas editor. It communicates with the Rust libraries via C ABI and outputs sprite resources which can be rendered with a dedicated `DicedSprite2D` node.
+
+![](https://i.gyazo.com/93aaa8ed9a9aab15841c6faaf4516fa1.png)
+
+The plugin bundles pre-built binaries for Windows x64, Mac ARM and Linux x64. All the code is editor-only, so this covers all the Godot editor-supported platforms.
+
+Minimum supported Godot version: 4.6.
+
+## Installation
+
+Download the plugin from the [latest release on GitHub](https://github.com/elringus/sprite-dicing/releases/latest/download/sprite-dicing-godot.zip).
+
+Unzip it under the project's `addons` folder.
+
+![](https://i.gyazo.com/457436bd5ceedec8688ee38b4a84589f.png)
+
+Enable `SpriteDicing` in the project settings.
+
+![](https://i.gyazo.com/814b7ad9ee4c41afb1319d6088648d5b.png)
+
+## Usage
+
+Create a new **DicedSpriteAtlas** resource.
+
+![](https://i.gyazo.com/257dfb9734d26ff55b882eb3a6fd3e3d.png)
+
+Select a folder containing source sprite textures and click **Build Atlas**.
+
+![](https://i.gyazo.com/f1ab20f8caff059ec475f73707d350e5.png)
+
+Add a **DicedSprite2D** node to your scene.
+
+![](https://i.gyazo.com/82325449a7e9021577f7def108028e29.png)
+
+Set the **Atlas** and **Sprite ID** properties.
+
+![](https://i.gyazo.com/fe39ca501b88f4b7e769e6be93b73419.png)
+
+## Atlas Generation Options
+
+You can optionally configure atlas generation settings in the inspector.
+
+![](https://i.gyazo.com/7fc948fe098f8cd0b6909200162404d1.png)
+
+| Option | Description
+| --- | --- |
+| Trim Transparent | Whether to discard fully-transparent diced units on the generated mesh. Disable to preserve original texture dimensions (usable for animations). |
+| Default Pivot | Relative pivot point position in 0 to 1 range, counting from the bottom-left corner. Can be changed after build for each sprite individually. |
+| Keep Original | Whether to use pivot set on source textures (if any) instead of default. |
+| Atlas Size Limit | Maximum size of a single generated atlas texture; will generate multiple textures when the limit is reached. |
+| Square | The generated atlas textures will always be square. Less efficient, but required for PVRTC compression. |
+| POT | The generated atlas textures will always have width and height of power of two. Extremely inefficient, but may be required by some older GPUs. |
+| Pixels Per Unit | How many pixels in the sprite correspond to the unit in the world. |
+| Dice Unit Size | The size of a single diced unit. |
+| Padding | The size of a pixel border to add between adjacent diced units inside atlas. Increase to prevent texture bleeding artifacts (usually appear as thin gaps between diced units). Larger values will consume more texture space, but yield better anti-bleeding results. Minimum value of 2 is recommended in most cases. When 2 is not enough to prevent bleeding, consider adding a bit of `UV Inset` before increasing the padding. |
+| UV Inset | Relative inset of the diced units UV coordinates. Can be used in addition to (or instead of) `Padding` to prevent texture bleeding artifacts. Won't consume any texture space, but higher values could visually distort the final result. |
+| Input Folder | Asset folder with source sprite textures. |
+| Include Subfolders | Whether to recursively search for textures inside the input folder. |
+| Separator | When sprite is from a sub-folder(s), the separator will be used to join the folder name(s) and the sprite name. |
+
+All the above descriptions are available as tooltips when hovering corresponding configuration options in the editor.
+
+## Compression Ratio
+
+When inspecting atlas asset, notice `Compression Ratio` line; it shows the ratio between source textures size and generated data (atlas textures + sprite meshes).
+
+![](https://i.gyazo.com/80575364742301fbf5902d91972f2d4f.png)
+
+When around to 1.0 or lower, the generated data size is close to or even larger than the source. You should either change atlas generation configuration (eg, increase dice unit size) or not use the solution at all.
+
+## Export Mode
+
+When exporting the project, make sure to **not include the source textures**. Otherwise, your build will contain both the original textures and their diced counterparts baked into the atlas textures.
+
+Use the **Export Mode** to control which resources are exported. The simplest way to exclude the source textures is by changing the mode to "Export selected scenes" — this will make Godot only include the resources actually used in the selected scenes.
+
+![](https://i.gyazo.com/488b2fe92ecd692708f76b66663e45f8.png)
+
+## API
+
+### DicedSpriteAtlas
+
+```gdscript
+# Get a sprite resource by identifer
+var sprite = atlas.get_sprite("sprite_id")
+
+# Collect all sprite identifiers
+var ids := PackedStringArray()
+atlas.collect_sprite_ids(ids)
+```
+
+### DicedSprite2D
+
+```gdscript
+# Change the displayed sprite
+sprite_node.sprite_id = "new_sprite"
+
+# Change the atlas
+sprite_node.atlas = new_atlas
+```
+
+## Building the GDExtension
+
+### Prerequisites
+
+1. **Python 3.6+** with SCons installed:
+   ```bash
+   pip install scons
+   ```
+
+2. **C++ Compiler**:
+    - Windows: Visual Studio 2019+ with C++ workload
+    - macOS: Xcode Command Line Tools
+    - Linux: GCC or Clang
+
+### Build Steps
+
+1. Clone godot-cpp into the native directory:
+   ```bash
+   cd godot/addons/sprite_dicing/editor/native
+   git clone https://github.com/godotengine/godot-cpp
+   cd godot-cpp
+   git checkout 4.6  # Match your Godot version
+   git submodule update --init --recursive
+   ```
+
+2. Build the GDExtension:
+   ```bash
+   cd ..  # Back to native directory
+   scons target=template_release
+   ```
+
+3. The compiled library will be in `bin/`.
+
+## Sample Assets
+
+- [Godette by tqqq](https://tqqq.itch.io/godette-3-animations-with-psd-files) (CC-BY 3.0)

docs/guide/index.md

@@ -2,11 +2,11 @@
 
 Use SpriteDicing to split a set of sprite textures into units, discard identical ones, bake unique units into atlas textures to then seamlessly reconstruct the original sprites at runtime, without actually keeping original textures in the build.
 
-The solution significantly reduces build size when multiple textures with identical areas are used. Consider a [visual novel](https://en.wikipedia.org/wiki/Visual_novel) type of game, where multiple textures per character are used, each portraying different emotion; most of the texture space is occupied with identical data, while only a small area varies:
+The solution significantly reduces the build size when multiple textures with identical areas are used. Consider a [visual novel](https://en.wikipedia.org/wiki/Visual_novel) type of game, where multiple textures per character are used, each portraying different emotion; most of the texture space is occupied with identical data, while only a small area varies:
 
 ![](https://raw.githubusercontent.com/elringus/sprite-dicing/main/docs/public/img/banner.png)
 
-These original five textures have total size of **17.5MB**. After dicing, the resulting atlas texture will contain only the unique areas of the original textures and consume just **2.4MB**, effectively compressing the textures by **86.3%**.
+These original five textures have a total size of **17.5MB**. After dicing, the resulting atlas texture will contain only the unique areas of the original textures and consume just **2.4MB**, effectively compressing the textures by **86.3%**.
 
 <a href="https://naninovel.com">
   <p align="center">Sprite Dicing is used in <strong>Naninovel</strong> — visual novel engine. Check it out!</p>

docs/guide/unity.md

@@ -1,10 +1,10 @@
 # Unity
 
-SpriteDicing has a [Unity](https://unity.com/) integration with full-fledged atlas editor. It communicates with the Rust libraries via C ABI and outputs native Unity sprite assets.
+SpriteDicing has a [Unity](https://unity.com/) integration with a full-fledged atlas editor. It communicates with the Rust libraries via C ABI and outputs native Unity sprite assets.
 
 The extension package bundles pre-built binaries for Windows x64, Mac ARM and Linux x64. All the code is editor-only, so this covers all the Unity editor-supported platforms.
 
-Minimum supported Unity version: 2022.3. For previous Unity versions use legacy v1.x branch: https://github.com/elringus/sprite-dicing/tree/arch/v1.
+Minimum supported Unity version: 2022.3. For previous Unity versions use the legacy v1.x branch: https://github.com/elringus/sprite-dicing/tree/arch/v1.
 
 ## Installation
 
@@ -16,14 +16,14 @@ https://github.com/elringus/sprite-dicing.git?path=/plugins/unity/Assets/SpriteD
 
 ![](/img/upm.mp4)
 
-Alternatively, clone the repository and install [extension directory](https://github.com/elringus/sprite-dicing/tree/main/plugins/unity/Assets/SpriteDicing) as local package.
+Alternatively, clone the repository and install [extension directory](https://github.com/elringus/sprite-dicing/tree/main/plugins/unity/Assets/SpriteDicing) as a local package.
 
 ## Usage
 
 1. Create a `DicedSpriteAtlas` asset using `Assets -> Create -> Diced Sprite Atlas` menu command, select it;
-2. Specify `Input Folder` — project directory, containing the source textures to process. You can drag-drop a folder from the project hierarchy window or select one with object picker;
+2. Specify `Input Folder` — project directory, containing the source textures to process. You can drag-drop a folder from the project hierarchy window or select one with the object picker;
 3. Click `Build Atlas` button and wait for the procedure to finish;
-4. Generated sprites will appear inside the atlas asset; drag and drop them on scene like regular sprites.
+4. Generated sprites will appear inside the atlas asset; drag and drop them on a scene like regular sprites.
 
 ![](https://i.gyazo.com/faddf19580d8e6c9e0660d61976b2bef.gif)
 
@@ -58,7 +58,7 @@ When inspecting atlas asset, notice `Compression Ratio` line; it shows the ratio
 
 ![](https://i.gyazo.com/c104f864bb4ce2b33760616ced9a9276.png)
 
-When close to 1 or lower, the value will be in yellow/red color indicating the generated data size is close to or even larger than the source and you should either change atlas generation configuration (eg, increase dice unit size) or not use the solution at all.
+When close to 1 or lower, the value will be in yellow/red color indicating the generated data size is close to or even larger than the source. You should either change atlas generation configuration (eg, increase dice unit size) or not use the solution at all.
 
 ## uGUI
 
@@ -68,10 +68,10 @@ To use the diced sprites in with Unity UI (aka uGUI), enable `Use Sprite Mesh`.
 
 ## UI Toolkit
 
-Diced sprites are normal Unity sprite assets and can be assigned as source for various visual UI Toolkit elements, no additional setup is required. Check "UI" scene in the [samples directory](https://github.com/elringus/sprite-dicing/tree/main/plugins/unity/Assets/Samples) for an example.
+Diced sprites are normal Unity sprite assets and can be assigned as a source for various visual UI Toolkit elements, no additional setup is required. Check the "UI" scene in the [samples directory](https://github.com/elringus/sprite-dicing/tree/main/plugins/unity/Assets/Samples) for an example.
 
 ## Animation
 
-It's possible to use diced sprites for animation. Make sure to disable `Trim Transparent` when generating the atlas to preserve relative positions of the generated sprites. An example on animating diced sprites is available in "Animation" scene.
+It's possible to use diced sprites for animation. Make sure to disable `Trim Transparent` when generating the atlas to preserve relative positions of the generated sprites. An example on animating diced sprites is available in the "Animation" scene.
 
 ![](https://i.gyazo.com/9df7af39368a7b17f067a03a50c41509.gif)

docs/index.md

@@ -41,7 +41,7 @@ hero:
                                 <div class="icon">🧩️</div>
                                 <h2 class="title">Engine-agnostic</h2>
                             </div>
-                            <p class="details">SpriteDicing is compiled into native library with C ABI making it embeddable to any game engine, framework or programming language.</p></article>
+                            <p class="details">SpriteDicing is compiled into a native library with C ABI making it embeddable to any game engine, framework or programming language.</p></article>
                     </div>
                 </div>
                 <div class="grid-3 item">
@@ -51,7 +51,7 @@ hero:
                                 <div class="icon">💻</div>
                                 <h2 class="title">Standalone Tool</h2>
                             </div>
-                            <p class="details">Alternatively, standalone CLI tool is available for Windows, macOS and Linux; it'll produce atlases and JSON with the diced sprites specs.</p></article>
+                            <p class="details">Alternatively, a standalone CLI tool is available for Windows, macOS and Linux; it'll produce atlases and JSON with the diced sprites specs.</p></article>
                     </div>
                 </div>
             </div>
@@ -63,7 +63,7 @@ hero:
                                 <div class="icon">🦀</div>
                                 <h2 class="title">Written in Rust</h2>
                             </div>
-                            <p class="details">SpriteDicing is authored in Rust programming language for best performance and reliability.</p></article>
+                            <p class="details">The core is written in the Rust programming language for the best performance and reliability.</p></article>
                     </div>
                 </div>
                 <div class="grid-4 item">
@@ -83,17 +83,17 @@ hero:
                                 <div class="icon">🛠️</div>
                                 <h2 class="title">Customizable</h2>
                             </div>
-                            <p class="details">Has plethora of options: atlas size limit, UV inset, padding, trimming, sprite pivot and more.</p></article>
+                            <p class="details">Has a plethora of options: atlas size limit, UV inset, padding, trimming, sprite pivot and more.</p></article>
                     </div>
                 </div>
                 <div class="grid-4 item">
                     <div class="VPLink no-icon VPFeature">
                         <article class="box">
                             <div class="box-title">
                                 <div class="icon">🕹️</div>
-                                <h2 class="title">Unity Integration</h2>
+                                <h2 class="title">Engine Plugins</h2>
                             </div>
-                            <p class="details">First-party plugin for Unity game engine with a dedicated editor UI; outputs native sprite assets.</p></article>
+                            <p class="details">First-party plugins for the Unity and Godot game engines with dedicated editor UIs.</p></article>
                     </div>
                 </div>
             </div>

docs/package.json

@@ -8,7 +8,7 @@
     "devDependencies": {
         "typescript": "5.7.2",
         "@types/node": "22.10.0",
-        "vitepress": "1.5.0",
+        "vitepress": "1.6.4",
         "imgit": "0.2.1"
     }
 }