Merge branch 'I-am-Erk:master' into NeoDays]-National-Flags

doc/installation.md

@@ -1,5 +1,7 @@
 # Installation
 
+You can select a different tileset than the one included with the game. You have two options: stable or latest. The stable version is tested and reliable, while the latest version is updated frequently and may have new features or bug fixes.
+
 ## Stable
 
 The easiest way to download the tileset would be from the latest release. It is a stable tileset build which you can safely put into the game and run.
@@ -8,7 +10,8 @@ The easiest way to download the tileset would be from the latest release. It is
 2. Extract archive once it's downloaded.
 3. Put *UltimateCataclysm* folder from extracted files into your `cataclysmdda\gfx` folder. It should look like: `cataclysmdda\gfx\UltimateCataclysm`.
 
-> ⚠ If you have "Missing "tile_config.json" file" error upon loading the tileset, this means that you have downloaded and extracted the source code, and **not** the tileset.
+> [!WARNING]
+> If you have "Missing "tile_config.json" file" error upon loading the tileset, this means that you have downloaded and extracted the source code, and **not** the tileset.
 
 ## Develop
 
@@ -19,17 +22,14 @@ The most up to date build of the tileset (per commit). Might be broken.
 3. Find *Artifacts* drop-down menu, click on it, and then select the artifact.
 4. Proceed with step 2 and 3 from stable installation.
 
+> [!NOTE]
 > Red cross means that the build has failed and no artifacts were produced.
 
 # Building
 
-You will need:
-- Python 3
-- [Libvips](https://libvips.github.io/libvips/install.html)
-- pyvips (install it via python pip: `pip install pyvips`) 
+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).
 
-Once you have everything ready, you can build the tileset:
-```sh
-# Assuming that you are in the root of the tileset repository
-$ python3 tools/compose.py gfx/UltimateCataclysm
-```
+These guides will help you set up the required tools and steps to build the tileset from the source files.

doc/installation_nix.md

@@ -2,6 +2,13 @@
 
 Documentation of developing tileset with [Nix](https://nixos.org/). 
 
+## Prerequisites
+
+You will need:
+- Python 3
+- [Libvips](https://libvips.github.io/libvips/install.html)
+- pyvips (install it via python pip: `pip install pyvips`) 
+
 ## Build
 
 As this repository uses flakes, it's possible to build any of the tileset (not only UlitCa) using `nix build .#{name}` command. For example:

doc/installation_windows.md

@@ -2,52 +2,89 @@
 
 Guide for Windows users, without touching the Command Line.
 
-## Install requirements
+## First steps
 
-**Python**
+1. [Register](https://github.com/join) on GitHub
+2. [Get](https://docs.github.com/en/enterprise-cloud@latest/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop#downloading-and-installing-github-desktop) `Github Desktop` [^1]
+3. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) Tileset repository
+4. [Clone](https://docs.github.com/en/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop) forked repository.
 
-Install Python 3 from [python.org](https://www.python.org/downloads/windows/).
+> [!NOTE]
+> 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.
 
-During installation, check "Add Python to PATH".
+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.  
 
-**libvips**
+## The Game
 
-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).
+The easiest way to get the game is to use the [CDDA Game Launcher](https://github.com/Fris0uman/CDDA-Game-Launcher/releases).
+With the launcher, install the latest **experimental** release.
 
-Extract the files somewhere.
+Tools need to know where to put composed tileset. So you have three options:
+- copy `set_game_path.cmd` to your game dir and double-click it.
+- drag and drop game folder over `set_game_path.cmd` script.
+- or just double-click it and type path to the game folder.
 
-**Cataclysm-DDA game**
+> [!NOTE]
+> if you change your game folder later, you can repeat this step and provide new path.
 
-The easiest way to get the game is to use the [CDDA Game Launcher](https://github.com/Fris0uman/CDDA-Game-Launcher/releases).
-With the launcher, install the latest **experimental** release.
+## Tilesets and Windows
+
+Some tilesets reuse assets from other tilesets. This can be done by using symlinks, which are shortcuts that point to another file or folder. However, symlinks are disabled by default in Windows systems. If you want to compose tilesets that use symlinks (such as Altica or Ultica-ISO), you need to enable them.
+
+To enable symlinks, go to the `tools` folder in your local repository and double-click on `git_symlinks.cmd`. This will run a script that will configure your Git settings to allow symlinks. [^2]
 
-## Setting up paths
+## Python and Windows
 
-For composing tilesets, some path must be known to the respective scripts.
-This section describes the most easy drag & drop approach.
+If you dont have Python istalled yet you need to disable app execution alias.  
+<details>
+   <summary>Go to -> "start" and type "Manage App Execution Aliases". Go to it and turn off "Python"</summary>
 
-In `CDDA-Tilesets`, go into folder `tools`.
+![img](https://i.stack.imgur.com/7C78e.png)
+
+</details>
 
-1. Copy `set_game_path.cmd` into the game's folder, and double-click it.  
-OR: Drag & drop the game folder onto `set_game_path.cmd`.
-   > Note: This sets the environmental variable `CDDA_PATH`.
+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.
 
-2. Copy `set_vips_path.cmd` into the vips folder (e.g. `C:\vips-dev-x.xx`), and double-click it.  
-OR: Drag & drop the vips folder onto `set_vips_path.cmd`.
-   > Note: This sets the environmental variable `LIBVIPS_PATH`.
+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.  
 
-3. Optional: 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`.
+> [!WARNING]
+> 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".
 
-After these steps, it might be necessary to restart the computer.
+## Python and components
 
-## Compose and update tileset
+The script will first check if Python is installed on your system. It will print the Python version and verify that the pyvips module and the libvips library are available.
 
-In `tools`, double-click `updtset.cmd`.
+- If pyvips is missing, the script will try to install it automatically. This step should not cause any errors, only informational messages.
+- Next, the script will check if there are any libvips binaries in the system. If not, the script will attempt to download the 8.15 version and unzip it using VBS into the user’s home folder. Then, the script will call set_vips_path.cmd with this path.
 
-You will be prompted to select a tileset (unless it was set permanently).
-At the first run, `pyvips` will be installed automatically.
+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`  
+
+## Final
+
+Maximum at third run script should compose tileset and propose you to check it in game.
 If something goes wrong, read the script's output carefully!
+
+> [!TIP]
+> 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.  
+
+> [!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.

gfx/MShockXotto+/pngs_tall_32x48/furniture/monster_corpse/monster_corpse.json

@@ -0,0 +1,10 @@
+[
+  {
+    "id": [ "f_nm_tube", "f_nm_tube_emitter" ],
+    "fg": "f_nm_tube"
+  },
+  {
+    "id": [ "f_nm_nether_grass", "f_nm_nether_grass_tall" ],
+    "fg": "f_nm_nether_grass"
+  }
+]

gfx/MShockXotto+/pngs_tiles_32x32/terrain/monster_corpse/t_nm_ichor_sh/t_nm_ichor_sh.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "t_nm_ichor_sh",
+    "fg": "t_nm_ichor_sh_0",
+    "rotates": true,
+    "multitile": true,
+    "additional_tiles": [
+      { "id": "center", "fg": "t_nm_ichor_sh_0" },
+      { "id": "corner", "fg": "t_nm_ichor_sh_1" },
+      { "id": "edge", "fg": "t_nm_ichor_sh_2" },
+      { "id": "end_piece", "fg": "t_nm_ichor_sh_3" },
+      { "id": "t_connection", "fg": "t_nm_ichor_sh_0" },
+      { "id": "unconnected", "fg": "t_nm_ichor_sh_4" }
+    ]
+  }
+]

gfx/UltimateCataclysm/pngs_normal_32x32/overmap/cabin/cabin.json

@@ -17,7 +17,7 @@
     "cabin_strange_b",
     "riverside_dwelling"
   ],
-  "fg": [ "cabin_faceN", "cabin_faceE", "cabin_faceS", "cabin_faceW" ],
+  "fg": [ "cabin_faceN", "cabin_faceW", "cabin_faceS", "cabin_faceE" ],
   "bg": "field",
   "rotates": true
 },{
@@ -35,7 +35,7 @@
     "cabin_lake_roof",
     "lake_cabin_boathouse_roof"
   ],
-  "fg": [ "cabin_faceN", "cabin_faceE", "cabin_faceS", "cabin_faceW" ],
+  "fg": [ "cabin_faceN", "cabin_faceW", "cabin_faceS", "cabin_faceE" ],
   "bg": "open_air",
   "rotates": true
 }]

gfx/UltimateCataclysm/pngs_normal_32x32/overmap/cs_private_park/cs_private_park.json

@@ -3,9 +3,9 @@
 	"id": "cs_private_park_roof",
 	"fg": [
 	  "cs_private_park_rot_N",
-	  "cs_private_park_rot_E",
+	  "cs_private_park_rot_W",
 	  "cs_private_park_rot_S",
-	  "cs_private_park_rot_W"
+	  "cs_private_park_rot_E"
 	],
 	"bg": "open_air",
 	"rotates": true
@@ -14,9 +14,9 @@
 	"id": "cs_private_park",
 	"fg": [
 	  "cs_private_park_rot_N",
-	  "cs_private_park_rot_E",
+	  "cs_private_park_rot_W",
 	  "cs_private_park_rot_S",
-	  "cs_private_park_rot_W"
+	  "cs_private_park_rot_E"
 	],
 	"bg": "field",
 	"rotates": true

gfx/UltimateCataclysm/pngs_normal_32x32/overmap/cs_public_art_piece/cs_public_art_piece.json

@@ -3,9 +3,9 @@
 	"id": "cs_public_art_piece",
 	"fg": [
 	  "cs_public_art_piece_rot_N",
-	  "cs_public_art_piece_rot_E",
+	  "cs_public_art_piece_rot_W",
 	  "cs_public_art_piece_rot_S",
-	  "cs_public_art_piece_rot_W"
+	  "cs_public_art_piece_rot_E"
 	],
 	"bg": "field",
 	"rotates": true

gfx/UltimateCataclysm/pngs_normal_32x32/overmap/cs_public_space/cs_public_space.json

@@ -3,9 +3,9 @@
 	"id": "cs_public_space",
 	"fg": [
 	  "cs_public_space_rot_N",
-	  "cs_public_space_rot_E",
+	  "cs_public_space_rot_W",
 	  "cs_public_space_rot_S",
-	  "cs_public_space_rot_W"
+	  "cs_public_space_rot_E"
 	],
 	"bg": "field",
 	"rotates": true

gfx/UltimateCataclysm/pngs_normal_32x32/overmap/dirt_road/dirt_road.json

@@ -1,19 +1,31 @@
 [
-{
-	"id": [ "dirt_road", "dirt_road_forest" ],
-	"fg": [ "dirt_road_edge_ns", "dirt_road_edge_ew" ],
-	"rotates": true
-},{
-	"id": [ "dirt_road_3way", "dirt_road_3way_forest" ],
-	"fg": [ "dirt_road_t_connection_n", "dirt_road_t_connection_e", "dirt_road_t_connection_s", "dirt_road_t_connection_w" ],
-	"rotates": true
-},{
-	"id": [ "dirt_road_turn", "dirt_road_turn_forest" ],
-	"fg": [ "dirt_road_corner_ne", "dirt_road_corner_se", "dirt_road_corner_sw", "dirt_road_corner_nw" ],
-	"rotates": true
-},{
-	"id": [ "dirt_road_turn1", "dirt_road_turn1_forest" ],
-	"fg": [ "dirt_road_corner_nw", "dirt_road_corner_ne", "dirt_road_corner_se", "dirt_road_corner_sw" ],
-	"rotates": true
-}
-]
+  {
+  	"id": [ "dirt_road", "dirt_road_forest" ],
+  	"fg": [ "dirt_road_edge_ns", "dirt_road_edge_ew" ],
+  	"rotates": true
+  },
+  {
+    "id": [ "dirt_road_turnback", "trailhead" ],
+    "fg": [ "dirt_road_end_piece_s", "dirt_road_end_piece_e", "dirt_road_end_piece_n", "dirt_road_end_piece_w" ],
+    "rotates": true
+  },
+  {
+  	"id": [ "dirt_road_3way", "dirt_road_3way_forest" ],
+  	"fg": [ "dirt_road_t_connection_n", "dirt_road_t_connection_w", "dirt_road_t_connection_s", "dirt_road_t_connection_e" ],
+  	"rotates": true
+  },
+  {
+  	"id": [ "dirt_road_turn", "dirt_road_turn_forest" ],
+  	"fg": [ "dirt_road_corner_ne", "dirt_road_corner_nw", "dirt_road_corner_sw", "dirt_road_corner_se" ],
+  	"rotates": true
+  },
+  {
+  	"id": [ "dirt_road_turn1", "dirt_road_turn1_forest" ],
+  	"fg": [ "dirt_road_corner_nw", "dirt_road_corner_ne", "dirt_road_corner_se", "dirt_road_corner_sw" ],
+  	"rotates": true
+  },
+  {
+    "id": "dirt_road_4way",
+    "fg": "dirt_road_center"
+  }
+]

gfx/UltimateCataclysm/pngs_normal_32x32/overmap/evac_shelters/evac_shelters.json

@@ -1,28 +1,35 @@
 [
   {
     "id": [
-	  "shelter",
-	  "shelter_1",
-	  "shelter_2",
-	  "shelter_vandal",
-	  "shelter_1_vandal",
-	  "shelter_2_vandal"
-	],
-    "fg": [ "otr_evac_shelter_1_faceN", "otr_evac_shelter_1_faceE", "otr_evac_shelter_1_faceS", "otr_evac_shelter_1_faceW" ],
+	    "shelter",
+	    "shelter_1",
+	    "shelter_2",
+	    "shelter_vandal",
+	    "shelter_1_vandal",
+	    "shelter_2_vandal",
+      "shelter_1b"
+	  ],
+    "fg": [ "otr_evac_shelter_1_faceN", "otr_evac_shelter_1_faceW", "otr_evac_shelter_1_faceS", "otr_evac_shelter_1_faceE" ],
     "bg": "field",
     "rotates": true
-  },{
+  },
+  {
 	  "id": [
-	     "shelter_roof",
+	   "shelter_roof",
 		 "shelter_roof_1",
-		 "shelter_roof_2"
+		 "shelter_roof_2",
+     "shelter_roof_1b"
 		],
-	  "fg": [ "otr_evac_shelter_1_faceN", "otr_evac_shelter_1_faceE", "otr_evac_shelter_1_faceS", "otr_evac_shelter_1_faceW" ],
+	  "fg": [ "otr_evac_shelter_1_faceN", "otr_evac_shelter_1_faceW", "otr_evac_shelter_1_faceS", "otr_evac_shelter_1_faceE" ],
 	  "bg": "open_air",
 	  "rotates": true
-  },{
-	  "id": "shelter_under",
-	  "fg": [ "otr_evac_shelter_1_faceN", "otr_evac_shelter_1_faceE", "otr_evac_shelter_1_faceS", "otr_evac_shelter_1_faceW" ],
+  },
+  {
+	  "id": [
+      "shelter_under",
+      "shelter_under_1b"
+    ],
+	  "fg": [ "otr_evac_shelter_1_faceN", "otr_evac_shelter_1_faceW", "otr_evac_shelter_1_faceS", "otr_evac_shelter_1_faceE" ],
 	  "rotates": true
   }
 ]

gfx/UltimateCataclysm/pngs_normal_32x32/overmap/gas/omt_gasstations.json

@@ -6,7 +6,7 @@
       "garage_gas_1", "garage_gas_2", "garage_gas_3",
       "garage_gas_roof_1", "garage_gas_roof_2", "garage_gas_roof_3"
     ],
-    "fg": [ "gas_small_faceN", "gas_small_faceE", "gas_small_faceS", "gas_small_faceW" ], 
+    "fg": [ "gas_small_faceN", "gas_small_faceW", "gas_small_faceS", "gas_small_faceE" ], 
     "bg": "field"
   }
 ]