diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md
index ccc4422fcd..489768916b 100644
--- a/doc/SUMMARY.md
+++ b/doc/SUMMARY.md
@@ -1,17 +1,20 @@
# Summary
-- [Installation & Building](installation.md)
- - [Windows guide](installation_windows.md)
- - [Nix](installation_nix.md)
-- [Style guidelines](style/summary.md)
- - [General](style/general.md)
- - [Items](style/items.md)
- - [Overlay](style/overlay.md)
- - [Creatures](style/creatures.md)
- - [Terrain & Furniture](style/terrain-furniture.md)
-- [How to]()
- - [Tileset structure](how-to/structure.md)
- - [Autotiles](how-to/autotiles.md)
-- [Tools]()
- - [Slice autotiles]()
- - [Generate preview]()
+- [Installation & Building](./installation.md)
+ - [Windows guide](./installation_windows.md)
+ - [Nix](./installation_nix.md)
+- [Style guidelines](./style/summary.md)
+ - [UltimateCataclysm (UltiCa)](./style/UltimateCataclysm/summary.md)
+ - [MShockXotto+](./style/MShockXotto+/summary.md)
+ - [HollowMoon](./style/HollowMoon/summary.md)
+
+- [How to](./how-to/summary.md)
+ - [Tileset structure](./how-to/structure.md)
+ - [Autotiles/Multitiles](./how-to/autotiles.md)
+ - [Multitiles detailed info](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/TILESET.md#multitile) (new browser window with man CDDA doc)
+ - [Windows and symlinks](./how-to/Cloning_symlinks_on_windows.md)
+- [Tools](./tools/summary.md)
+ - [Common tools](./tools/common_tools.md)
+ - [Windows wrappers](./tools/windows_wrappers.md)
+
+You may find additional info in the [main CDDA documentation](https://github.com/CleverRaven/Cataclysm-DDA/blob/db3054e61b77fd16ef15961714bff97c4b5aac0c/doc/TILESET.md#composepy)
diff --git a/doc/how-to/structure.md b/doc/how-to/structure.md
index a3fd9072da..169f78ee40 100644
--- a/doc/how-to/structure.md
+++ b/doc/how-to/structure.md
@@ -1,9 +1,8 @@
# Tileset structure
-*// TODO: rewrite*
+//TODO: rewrite document from scratch
- Put files into the best appropriate folder (terrain, furniture, mutations, items, etc).
- Give files a name based on the JSON ID they suit, eg `t_floor`.
- If multiple files apply to that ID, make a subfolder eg `terrain/t_floor/` for all the views.
- For the moment, there isn't a clear naming convention after that. Working on it.
-
diff --git a/doc/how-to/summary.md b/doc/how-to/summary.md
index f058e8f1be..7ea6c2f6b3 100644
--- a/doc/how-to/summary.md
+++ b/doc/how-to/summary.md
@@ -1 +1,8 @@
# How to
+
+Some guides that might help
+
+- [Multitiles summary](./autotiles.md)
+- [Multitiles detailed](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/TILESET.md#multitile) (will open new browser window with main CDDA documentation)
+- [Tileset structure](./structure.md)
+- [Windows and Symlinks](./Cloning_symlinks_on_windows.md)
diff --git a/doc/installation.md b/doc/installation.md
index e2a63357e6..0f73071302 100644
--- a/doc/installation.md
+++ b/doc/installation.md
@@ -29,7 +29,7 @@ The most up to date build of the tileset (per commit). Might be broken.
To create your own tileset, test new sprites, or contribute to the project, please follow the instructions for your operating system:
-- For Linux, macOS, or other Unix-like systems, see [this guide](installation_nix.md).
-- For Windows, see [this guide](installation_windows.md).
+- For Linux, macOS, or other Unix-like systems, see [this guide](./installation_nix.md).
+- For Windows, see [this guide](./installation_windows.md).
These guides will help you set up the required tools and steps to build the tileset from the source files.
diff --git a/doc/installation_windows.md b/doc/installation_windows.md
index 3b440779fb..a1ba3e8bad 100644
--- a/doc/installation_windows.md
+++ b/doc/installation_windows.md
@@ -13,8 +13,8 @@ Guide for Windows users, without touching the Command Line.
> It is a good practice to create new branch at the start. Name it "playground" for example.
> Your repo is your own private space. You can do whatever you want in it without affecting the original project. However, if you want to contribute to the project, you need to follow some guidelines. One of them is to keep your master branch clean and empty, and do your work in a separate branch. This will make it easier for you to sync your changes with the upstream repo and create pull requests.
-Now you have source files on your drive and some tools as well.
-These tools will help you managing multitile objects, setting up the environment and composing tilesets.
+Now you have source files on your drive and some tools as well.
+These tools will help you managing multitile objects, setting up the environment and composing tilesets.
## The Game
@@ -37,22 +37,22 @@ To enable symlinks, go to the `tools` folder in your local repository and double
## Python and Windows
-If you dont have Python istalled yet you need to disable app execution alias.
+If you dont have Python istalled yet you need to disable app execution alias.
Go to -> "start" and type "Manage App Execution Aliases". Go to it and turn off "Python"
![img](https://i.stack.imgur.com/7C78e.png)
-
+
Make sure you are not using the Python version from the Microsoft Store. This version is incompatible with the tileset composing tools. You can uninstall this version safely from your system. The tools from the repo will install Python 3.12 for you, which you can use for any purpose.
Open the `tools` folder in your local repository and double-click `updtset.cmd`
Select any common tileset (like MShockXotto+) for the first runs until it finally compose.
-At the first run script will try to install Python using `winget`. In case of successful install it would stop and ask you to relaunch it again.
+At the first run script will try to install Python using `winget`. In case of successful install it would stop and ask you to relaunch it again.
> [!WARNING]
-> If script failed to install Python you should do it manually from [python.org](https://www.python.org/downloads/windows/).
+> If script failed to install Python you should do it manually from [python.org](https://www.python.org/downloads/windows/).
> During installation, check "Add Python to PATH".
## Python and components
@@ -65,10 +65,10 @@ The script will first check if Python is installed on your system. It will print
If the script successfully adds libvips, it will stop and ask the user to run it again.
> [!WARNING]
-> If script failed to install libvips you should do it manually.
-> Download the latest libvips distribution from [libvips.github.io](https://libvips.github.io/libvips/install.html)
-> get vips-dev-w64-web-#.#.#.zip NOT vips-dev-w64-all-#.#.#.zip
-> extract files somewhere and drag and drop this folder on `set_vips_path.cmd`
+> If script failed to install libvips you should do it manually.
+> Download the latest libvips distribution from [libvips.github.io](https://libvips.github.io/libvips/install.html)
+> get vips-dev-w64-web-#.#.#.zip NOT vips-dev-w64-all-#.#.#.zip
+> extract files somewhere and drag and drop this folder on `set_vips_path.cmd`
## Final
@@ -79,12 +79,13 @@ If something goes wrong, read the script's output carefully!
> You may ask for help at tileset Discord server.
> [!TIP]
-> To set a tileset to compose permanently, double-click `set_tileset.cmd` and select the desired tileset.
-> If not set permanently, the update script will allow for interactive selection of a tileset.
-> Note: This sets the environmental variable `CDDA_TILESET`. Delete it if you want to select tileset again.
+> To set a tileset to compose permanently, double-click `set_tileset.cmd` and select the desired tileset.
+> If not set permanently, the update script will allow for interactive selection of a tileset.
+> Note: This sets the environmental variable `CDDA_TILESET`. Delete it if you want to select tileset again.
> [!TIP]
> When scripts ask you to restart your computer it may be necessary on some systems. But you can try and skip reboots.
[^1]: Some tasks can be done much faster and easier with command line actually. So you can try to run ```winget install Github.GitHubDesktop```
+
[^2]: That tool will guide you how to [enable symlinks](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/) in your system and turn them on for your local repository.
diff --git a/doc/style/HollowMoon/SUMMARY.md b/doc/style/HollowMoon/SUMMARY.md
new file mode 100644
index 0000000000..223487ebea
--- /dev/null
+++ b/doc/style/HollowMoon/SUMMARY.md
@@ -0,0 +1,8 @@
+# HollowMoon style guide
+
+There are some guides:
+ - [Summary guide](./readme.md)
+ - Detailed guides
+ - [Terrain](./terrain.md)
+ - [Walls](./walls.md)
+ - [Overlays](./overlay.md)
diff --git a/doc/style/MShockXotto+/SUMMARY.md b/doc/style/MShockXotto+/SUMMARY.md
new file mode 100644
index 0000000000..c9dfa446d2
--- /dev/null
+++ b/doc/style/MShockXotto+/SUMMARY.md
@@ -0,0 +1,9 @@
+# MShockXotto+ style guide
+
+You can read it from the beginning or jump to the topic:
+
+[Start](./readme.md)
+ - [Monsters](./readme.md#monsters)
+ - [Items](./readme.md#items)
+ - [Furniture](./readme.md#furnitures)
+ - [Terrain](./readme.md#terrain)
diff --git a/doc/style/creatures.md b/doc/style/UltimateCataclysm/creatures.md
similarity index 76%
rename from doc/style/creatures.md
rename to doc/style/UltimateCataclysm/creatures.md
index 495c3563c3..a32ecc6392 100644
--- a/doc/style/creatures.md
+++ b/doc/style/UltimateCataclysm/creatures.md
@@ -4,12 +4,12 @@
Consider 32x64 a default template for human-sized creatures:
-![male](image/skin-male.png)
-![female](image/skin-female.png)
+![male](./image/skin-male.png)
+![female](./image/skin-female.png)
# Monster sprites should have ~8px offset from the ground
-*// TODO: image*
+// TODO: add monster image with measured offset
To give them a 3d look.
@@ -19,6 +19,6 @@ And remember that tiles are mirrored when creatures move.
# Monsters should drop shadows when possible
-*// TODO: image*
+// TODO: add monster with a shadow image
Put shadows in a `bg` field in json, use `shadow_x_` template. You can find shadow files in the root of any size directory (e.g. `pngs_normal_32x32`).
diff --git a/doc/style/general.md b/doc/style/UltimateCataclysm/general.md
similarity index 84%
rename from doc/style/general.md
rename to doc/style/UltimateCataclysm/general.md
index e26cd90db9..7dcda4f8a7 100644
--- a/doc/style/general.md
+++ b/doc/style/UltimateCataclysm/general.md
@@ -4,24 +4,24 @@ A bunch of rules that can be applied for every type of sprite.
## Use a limited set of colors as in pseudo-16 bit format
-![colors](image/colors.png)
+![colors](./image/colors.png)
-This is rule is one of the main rules not only for this tileset, but pixel art in general.
-Each "colour block" should use 3-6 colors for shades. For example a blue shirt might have one light blue highlight, two medium blue main colours, one dark blue shade, and one very dark blue-green shade.
+This is rule is one of the main rules not only for this tileset, but pixel art in general.
+Each "colour block" should use 3-6 colors for shades. For example a blue shirt might have one light blue highlight, two medium blue main colours, one dark blue shade, and one very dark blue-green shade.
See [colors tutorials section](https://lospec.com/pixel-art-tutorials/tags/colors) on lospec if you're having troubles with palette.
## Try to draw with realistic proportions
-![proportions](image/proportions.png)
+![proportions](./image/proportions.png)
Small items/creatures should be small. But if feel that they are **too small**, it is ok to make them bigger for sakes of ability to be recognized. Be careful about sizes.
## Use hard edges on foreground objects
-![hard-edges](image/hard-edges.png)
+![hard-edges](./image/hard-edges.png)
.. such as items and monsters. This is important because it makes things much more recognizable when zoomed out.
## The default light source is assumed to come from above and to the left.
-![sunlight](image/sunlight.png)
+![sunlight](./image/sunlight.png)
diff --git a/doc/style/image/colors.png b/doc/style/UltimateCataclysm/image/colors.png
similarity index 100%
rename from doc/style/image/colors.png
rename to doc/style/UltimateCataclysm/image/colors.png
diff --git a/doc/style/image/containers.png b/doc/style/UltimateCataclysm/image/containers.png
similarity index 100%
rename from doc/style/image/containers.png
rename to doc/style/UltimateCataclysm/image/containers.png
diff --git a/doc/style/image/hard-edges.png b/doc/style/UltimateCataclysm/image/hard-edges.png
similarity index 100%
rename from doc/style/image/hard-edges.png
rename to doc/style/UltimateCataclysm/image/hard-edges.png
diff --git a/doc/style/image/item-group.png b/doc/style/UltimateCataclysm/image/item-group.png
similarity index 100%
rename from doc/style/image/item-group.png
rename to doc/style/UltimateCataclysm/image/item-group.png
diff --git a/doc/style/image/item-proportions.png b/doc/style/UltimateCataclysm/image/item-proportions.png
similarity index 100%
rename from doc/style/image/item-proportions.png
rename to doc/style/UltimateCataclysm/image/item-proportions.png
diff --git a/doc/style/image/items-on-tables.png b/doc/style/UltimateCataclysm/image/items-on-tables.png
similarity index 100%
rename from doc/style/image/items-on-tables.png
rename to doc/style/UltimateCataclysm/image/items-on-tables.png
diff --git a/doc/style/image/proportions.png b/doc/style/UltimateCataclysm/image/proportions.png
similarity index 100%
rename from doc/style/image/proportions.png
rename to doc/style/UltimateCataclysm/image/proportions.png
diff --git a/doc/style/UltimateCataclysm/image/skin-female.png b/doc/style/UltimateCataclysm/image/skin-female.png
new file mode 100644
index 0000000000..5024056f5c
Binary files /dev/null and b/doc/style/UltimateCataclysm/image/skin-female.png differ
diff --git a/doc/style/UltimateCataclysm/image/skin-male.png b/doc/style/UltimateCataclysm/image/skin-male.png
new file mode 100644
index 0000000000..c9abdf5f46
Binary files /dev/null and b/doc/style/UltimateCataclysm/image/skin-male.png differ
diff --git a/doc/style/image/sunlight.png b/doc/style/UltimateCataclysm/image/sunlight.png
similarity index 100%
rename from doc/style/image/sunlight.png
rename to doc/style/UltimateCataclysm/image/sunlight.png
diff --git a/doc/style/items.md b/doc/style/UltimateCataclysm/items.md
similarity index 78%
rename from doc/style/items.md
rename to doc/style/UltimateCataclysm/items.md
index 7649298677..05a44735d5 100644
--- a/doc/style/items.md
+++ b/doc/style/UltimateCataclysm/items.md
@@ -2,31 +2,31 @@
## Maximum item size is 32x32; small items should fit within 16x16
-![item-proportions](image/item-proportions.png)
+![item-proportions](./image/item-proportions.png)
This is continuation of the general rule.
## Item tiles should be as close to scale as they can be while still recognizable
-![item-group](image/item-group.png)
+![item-group](./image/item-group.png)
When in doubt, err on the side of larger, but avoid filling an entire 32x32 tile with a single nail or it would look like a nail as large as a survivor.
Even for single items, putting multiple items into the icon could give it more recognizability without making it look comically huge.
## Containers should be drawn empty
-![containers](image/containers.png)
+![containers](./image/containers.png)
Like jars or bottles. The game will use the same tile no matter the actual content of the item.
## 100% black underline without shadow
-*// TODO: image*
+// TODO: add item shadow image
No shadow will make sure that players don't confuse several big items with furniture. Black underline helps to identify an item in the game world.
## Consider placement on tables
-![items-on-tables](image/items-on-tables.png)
+![items-on-tables](./image/items-on-tables.png)
-Table surfaces usually occupy top 19 pixels of a 32x32 sprite, try fitting your items there when possible.
\ No newline at end of file
+Table surfaces usually occupy top 19 pixels of a 32x32 sprite, try fitting your items there when possible.
diff --git a/doc/style/UltimateCataclysm/overlay.md b/doc/style/UltimateCataclysm/overlay.md
new file mode 100644
index 0000000000..be86470c8c
--- /dev/null
+++ b/doc/style/UltimateCataclysm/overlay.md
@@ -0,0 +1,9 @@
+# Overlay
+
+Rules about hair, mutations, worn clothes, wielded items and survivour's skin.
+
+# 32x64 tile base
+Use these as reference (base male and base female sprites):
+
+![male](./image/skin-male.png)
+![female](./image/skin-female.png)
diff --git a/doc/style/UltimateCataclysm/summary.md b/doc/style/UltimateCataclysm/summary.md
new file mode 100644
index 0000000000..11c0401680
--- /dev/null
+++ b/doc/style/UltimateCataclysm/summary.md
@@ -0,0 +1,8 @@
+# UltimateCataclysm (Ultica) style guide
+
+Rules and guidelines are divided between groups:
+- [General](general.md)
+- [Items](items.md) (things on the floor)
+- [Overlay](overlay.md) (wielded/worn/mutations)
+- [Creatures](creatures.md)
+- [Terrain](terrain.md)
diff --git a/doc/style/terrain-furniture.md b/doc/style/UltimateCataclysm/terrain-furniture.md
similarity index 79%
rename from doc/style/terrain-furniture.md
rename to doc/style/UltimateCataclysm/terrain-furniture.md
index d71376676e..9b72f3598b 100644
--- a/doc/style/terrain-furniture.md
+++ b/doc/style/UltimateCataclysm/terrain-furniture.md
@@ -2,16 +2,16 @@
## Walls and floors are 32x32, other things may vary
-*// TODO: image*
+// TODO: add terrain example image
Again, you should size things accordingly to its size in the world.
## Keep color value level in medium range
-*// TODO: image*
+// TODO: add image with color levels explaination
It's important to keep value level of the background objects (terrain, furniture) about 60-80, because it would define foreground entities (e.g. monsters) better.
# Keep table surfaces consistent
-When drawing something similar to a table keep in mind that currently table surfaces usually occupy top 19 pixels and items may be optimized to look like placed in that area.
\ No newline at end of file
+When drawing something similar to a table keep in mind that currently table surfaces usually occupy top 19 pixels and items may be optimized to look like placed in that area.
diff --git a/doc/style/image/skin-female.png b/doc/style/image/skin-female.png
deleted file mode 120000
index bba5672bac..0000000000
--- a/doc/style/image/skin-female.png
+++ /dev/null
@@ -1 +0,0 @@
-../../../gfx/UltimateCataclysm/pngs_human_body_32x36/overlay/skin/skin_light_f.png
\ No newline at end of file
diff --git a/doc/style/image/skin-male.png b/doc/style/image/skin-male.png
deleted file mode 120000
index 681c94f4ac..0000000000
--- a/doc/style/image/skin-male.png
+++ /dev/null
@@ -1 +0,0 @@
-../../../gfx/UltimateCataclysm/pngs_human_body_32x36/overlay/skin/skin_light_m.png
\ No newline at end of file
diff --git a/doc/style/overlay.md b/doc/style/overlay.md
deleted file mode 100644
index 9e1e273f31..0000000000
--- a/doc/style/overlay.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Overlay
-
-Rules about hair, mutations, worn clothes, wielded items and survivour's skin.
-
-# 32x64 tile base
-Use these as reference (base male and base female sprites):
-
-![male](image/skin-male.png)
-![female](image/skin-female.png)
diff --git a/doc/style/summary.md b/doc/style/summary.md
index 70cfab8f4a..83cc20ddaf 100644
--- a/doc/style/summary.md
+++ b/doc/style/summary.md
@@ -1,12 +1,10 @@
# Style guidelines
-We have rules for sprites these days.
-Not because it's important to keep the tileset consistent, but also to make things recognizable on the screen in the game.
-Without strict rules, UltiCa will quickly turn itself into a pixels mash up.
-Rules and guidelines are divided between groups:
-- [General](general.md)
-- [Items](items.md) (things on the floor)
-- [Overlay](overlay.md) (wielded/worn/mutations)
-- [Creatures](creatures.md)
-- [Terrain](terrain.md)
+We have rules for sprites these days.
+Not because it's important to keep the tileset consistent, but also to make things recognizable on the screen in the game.
+Without strict rules, any tileset will quickly turn itself into a pixels mash up.
+Different tilesets have different guides:
+ - [UltimateCataclysm (Ultica)](./UltimateCataclysm/summary.md)
+ - [MShockXotto+](./MShockXotto+/summary.md)
+ - [HollowMoon](./HollowMoon/summary.md)
diff --git a/doc/tools/SUMMARY.md b/doc/tools/SUMMARY.md
new file mode 100644
index 0000000000..28f2537c3e
--- /dev/null
+++ b/doc/tools/SUMMARY.md
@@ -0,0 +1,6 @@
+# Tileset tools manuals
+
+There are some basic tools that compatible with both Windows and *nix systems. For those who are not accustomed to the command line, we provide specific wrappers. For more information, please refer to the ‘Windows wrappers’ section of our documentation.
+
+- [Common tools](./common_tools.md)
+- [Windows wrappers](./windows_wrappers.md)
diff --git a/doc/tools/common_tools.md b/doc/tools/common_tools.md
new file mode 100644
index 0000000000..3364647294
--- /dev/null
+++ b/doc/tools/common_tools.md
@@ -0,0 +1,36 @@
+# Common tools (scrips)
+
+These are the tools that works the same way on every operating system.
+
+They supposed to run in shell environment and if you afraid doing so please refer [Windows wrappers](./windows_wrappers.md) documentation.
+
+## add_outline.py
+
+// TODO: Add some info about add_outline.py
+
+## compose.py
+
+Please refer [main CDDA documentation](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/TILESET.md#composepy) about this tool.
+
+## generate_preview.py
+
+// TODO: Add some info about generate_preview.py
+
+// TODO: Add link to how-to/preview section
+
+## recolor_season_variants.py
+
+// TODO: Add some info about recolor_season_variants.py
+
+## Slicers
+### slice_multitile.py
+
+// TODO: Add some info about slice_multitile.py
+
+### slice_variants.py
+
+// TODO: Add some info about slice_variants.py
+
+### unslice_multitile.py
+
+// TODO: Add some info about unslice_multitile.py
diff --git a/doc/tools/windows_wrappers.md b/doc/tools/windows_wrappers.md
new file mode 100644
index 0000000000..67d0d65f1f
--- /dev/null
+++ b/doc/tools/windows_wrappers.md
@@ -0,0 +1,112 @@
+# Windows Wrappers for Common Tools
+
+For more detailed information, please refer to the [Common Tools](./common_tools.md) section.
+
+We understand that artists may want to participate in tilesets, but not everyone is familiar with programmer's tools and environments. To optimize artists' time and workflow, we provide some wrappers that offer automation with preferred interactions such as double-clicking and drag-and-drop.
+
+These wrappers might have less functionality, but in most cases, their results are acceptable.
+
+## Infrastructure Building Tools
+
+// TODO: Remember to update this section when 'updtset.cmd' is divided.
+
+### 1) Installation
+
+To work with tilesets and test them in the game, you need a clone of the tileset repository on your drive and download the game itself. You can refer to [this](../installation_windows.md) page for details.
+
+The current `updtset.cmd` wrapper is written for the **Windows Command Shell** and is supposed to run on every Windows version from Windows XP to Windows 11 23H2. However, according to [this](https://www.statista.com/statistics/265033/proportion-of-operating-systems-used-on-the-online-gaming-platform-steam/) statistic, older Windows versions can be excluded and the script can be rewritten in **Powershell**.
+
+At this time, the installation of necessary environment tools is tied together with preparation steps and the composing process.
+
+The installation tool `updtset.cmd` will install the following on its first run:
+- Python
+- Necessary Python modules (pyvips and numpy)
+- Necessary VIPS library and binaries
+
+`git_symlinks.cmd` is a small script that runs commands necessary for symlinks to work in the repository. However, there is another method described [here](../how-to/Cloning_symlinks_on_windows.md).
+
+### 2) Preparation
+
+*There are some additional small scripts that are also written for the **Windows Command Shell** and should be rewritten in **Python** later, as **Powershell** does not support drag-and-drop over ps1 files.*
+
+`set_game_path.cmd` is a subtool that can be run separately from `updtset.cmd` and will set an environment variable pointing to the game. If you want to check your modified/added sprites in the game, tools need to know where the game is.
+
+`set_tileset.cmd` - This subtool will fix a tileset for future composing runs. It is helpful if you prefer to work on only one tileset.
+
+`set_vips_path.cmd` - This subtool allows you to define another `libvips` location.
+
+All these wrappers can be launched by dragging and dropping the appropriate folder over them. They will check if that folder has the correct files (game executable, libvips binary) and set the corresponding Windows user environment variable.
+Here's the revised version with improved style and grammar:
+
+## Slicer
+
+The Slicer wrapper, `slicemt.py`, is a wrapper for the [common tools](./common_tools.md) and performs the most repetitive process - slicing source files and composing tilesets. However, it cannot perform complex tasks such as multivariate multitile slicing or animation creation.
+
+If you need to slice multitiles and check the result in the game, you can do the following:
+
+1) Create a shortcut for `slicemt.py` on your desktop.
+2) Create a `source` subfolder in the `object folder` inside a tileset repository.
+3) Export a png file from your graphic editor to this `source` folder and name this multitile source accordingly.
+4) Drag-and-drop the `source` folder over the said shortcut.
+
+You will receive 16 sprites and a json file that will be used for composing. You may leave the `source` folder in the repository as it is ignored in the PR process. ([example with screenshots](https://github.com/I-am-Erk/CDDA-Tilesets/pull/2249#issue-2046838285))
+
+Under the hood, the following process occurs:
+
+1) The script (`slicemt.py`) will try to check if there is a `source` folder to work on. If it was launched from the CLI inside the `object folder`, it will try to find the `source` folder one level deeper.
+2) If the script can find a folder with `png` at the beginning and `NxM` following, it will assume that it runs in a tileset repository and `NxM` are sprite dimensions. This will allow it to make an assumption about where `updtset.cmd` is located.
+
+ Otherwise, the script will stop working.
+
+3) The script will try to make four different checks. Each check will try to find source files with a special name pattern. But you do not need to provide all of them. I will use `t_floor` as an example tile name.
+ - **Slicing Variants**
+
+ The pattern is `*_var*.png` so you can provide following files: *t_floor_var_1.png* or *t_floor_variants.png* each file will be sliced into 16 separate files and each file will have a name t_floor_var_XX.png, where XX is a number from 00 to 15.
+
+ If you provide more than one source file (for example *t_floor_var_1.png* and *t_floor_var_2.png*) you will receive 32 files numbered from 00 to 31.
+
+ In this and only in this case (slicing variants), you may provide a source file with a name different from the object name (t_floor). It can be used if you want to have variants for a subtile.
+
+ Providing a source file named `t_floor_unconnected_variants.png` will produce variants named `t_floor_unconnected_var_XX.png`.
+
+ Running this script over the same `source` folder with only one variant source file two (or more) times will produce separate images with names numbered from 00 to 31 (or even more). So each run will append the existing set of variants.
+
+ Do not forget to empty the `object folder` for each slice run.
+
+ - **Slicing Simple Multitile**
+
+ The second pattern is `object name`+`.png` so for our example, it will check for `t_floor.png` in the `source` folder and treat it as a multitile source.
+
+ Slicing this source will provide 16 named as multitile sub-tiles and a json file (`t_floor.json`).
+
+ This is the most common usage of this wrapper.
+
+ - **Slicing Transparent Multitile**
+
+ The third pattern is `object name`+`_t*.png` so you can provide names like `t_floor_transparent.png`, `t_floor_trans.png` or even `t_floor_t.png`. The resulting set will be named as `t_floor_transparent` and consists of 16 subtile images and a json file.
+
+ This pattern/name is useful for high objects and the game can swap them in close proximity to the player.
+
+ Please read [this](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/TILESET.md#optional-transparent-variant) document.
+
+ - **Seasonal Multitiles**
+
+ Same as simple multitile, but the pattern is:
+
+ object_name_winter*.png
+ object_name_spring*.png
+ object_name_summer*.png
+ object_name_autumn*.png
+
+ Resulting sets will have names like `t_floor_season_winter`, etc.
+
+ - **Seasonal Transparent Multitiles**
+
+ Everything is similar to the previous sections, except for the pattern.
+ `objectname_seasonname_t*.png` - `t_floor_winter_t.png` will work.
+
+ After slicing, the script will run `updtset.cmd` with the tileset name inferred from the path.
+
+## Composer
+
+For now, simply run `updtset.cmd`.