Merge pull request #2 from I-am-Erk/master

10/10/2020 update

.github/workflows/book.yml

@@ -0,0 +1,31 @@
+name: Book
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  book:
+    name: Build and Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install mdBook
+        uses: XAMPPRocky/get-github-release@v1
+        with:
+          owner: barsoosayque
+          repo: mdbook
+          matches: "unknown-linux-gnu"
+          token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Build book
+        run: /tmp/mdbook build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/

.github/workflows/ci_build.yml

@@ -22,7 +22,7 @@ jobs:
     steps:
       - name: Install Dependencies
         run: |
-          apk add --no-cache musl-dev gcc vips-dev python3-dev zip
+          apk add --no-cache musl-dev gcc vips-dev python3-dev zip py3-pip py3-wheel
           pip3 install pyvips
 
       - name: Checkout Code

.gitignore

@@ -3,6 +3,7 @@
 gfx/*/tile_config.json
 
 # UltimateCataclysm built sprite sheets
+gfx/UltimateCataclysm/fillergiant.png
 gfx/UltimateCataclysm/fillerhoder.png
 gfx/UltimateCataclysm/giant.png
 gfx/UltimateCataclysm/incomplete.png
@@ -11,6 +12,15 @@ gfx/UltimateCataclysm/large.png
 gfx/UltimateCataclysm/normal.png
 gfx/UltimateCataclysm/opengameartgiant.png
 gfx/UltimateCataclysm/tall.png
+gfx/UltimateCataclysm/small.png
+gfx/UltimateCataclysm/centered.png
 
 # BrownLikeBears built sprite sheets
 gfx/BrownLikeBears/tiles.png
+
+# RetroDays+ built sprite sheets
+gfx/RetroDays+/large.png
+gfx/RetroDays+/tiles.png
+
+# Builded book
+book

book.toml

@@ -0,0 +1,9 @@
+[book]
+language = "en"
+multilingual = false
+src = "doc"
+title = "UltimateCataclysm — Documentation"
+
+[output.html]
+git-repository-url = "https://github.com/I-am-Erk/CDDA-Tilesets"
+git-repository-icon = "fa-github"

doc/SUMMARY.md

@@ -0,0 +1,15 @@
+# Summary
+
+- [Installation & Building](installation.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]()

doc/how-to/autotiles.md

@@ -0,0 +1,143 @@
+### Autotiles
+
+Autotiles, referred to in CDDA game code as "multitiles", are tiles that display differently
+depending on their relationship to other sprites in the group. Water is a classic example: drawing
+water as an autotile allows it to display as a single body with edges, instead of either individual
+little puddles, or a large blue expanse with no shoreline.
+
+![Water autotile](image/t_water_sh_autotile.png)
+
+To simplify drawing these tiles, we use a template with an 8x6 grid of all the tile boundary types
+in a predictable order. Transparency allows overlapping the same tiles on different backgrounds, so
+we don't have to redraw the water boundaries for dirt, grass, rock, etc. - we draw the water once,
+and the transparent edges allow it to overlap dirt, grass, rock, and so on.
+
+This template shows the standard arrangement of tile borders:
+
+![Autotile Template](image/autotile_template_grid.png)
+
+Black space indicates background, and white is the shape of the furniture or terrain. The sixteen
+tiles in the top-left 4x4 block contain the basic boundary shapes - these are the most important
+ones to draw.
+
+Both terrain and furniture tiles may use this template. Terrain like grass or fences:
+
+![Tall grass terrain](image/t_grass_tall_autotile.png)
+![Fence terrain](image/t_fence_autotile.png)
+
+and furniture like bathtubs or benches:
+
+![Bathtub furniture](image/f_bathtub_autotile.png)
+![Table furniture](image/f_bench_autotile.png)
+
+Currently, there are only a few of these tiles supported in CDDA, although some day it would be nice
+to have all of them available. With the current tile support there are two ways you might use an
+autotile, demonstrated by the bench and table autotiles. What we're missing is the ability to draw
+different types of *diagonal* connections. Without that, we have to represent things that are likely
+to have diagonal connections or unlikely to have them in different ways.
+
+These break down into a few parts as recognized by the game.
+
+- **corner**: These attach two adjacent tiles perpendicular to the tile in question.
+- **edge**: These tiles connected either on the top-bottom or left-right sides, in a straight line.
+- **unconnected**: This is a tile just hanging out alone, unconnected to its neighbors.
+- **center**: This is a 4-way intersection tile, connected on all sides.
+- **end_piece**: These tiles are connected only on one side.
+- **t_connection**: These are the 3-way intersection tiles.
+
+![Autotile part labels](image/f_bench_autotile_labels.png)
+
+
+#### Things like benches
+
+![Autotile: bench](image/f_bench_autotile.png)
+
+The bench autotile is an example of an autotile that we don't really expect to be displayed double-thick most of the time. Generally you're going to draw a bench like this:
+```
+.....
+bbbbb
+.....
+```
+rather than like this:
+```
+bb.bb
+bb.bb
+bb.bb
+```
+
+For this reason, the **t_connection** and **center** art for the bench are drawn as 3-way and 4-way intersections.
+
+
+#### Things like tables
+
+![Autotile: table](image/f_table_autotile.png)
+
+The table autotile is an example of a tile you would often expect to be drawn double-thick,
+connecting to itself. While you might also draw it one tile wide, two or more tiles of contiguous
+table are common. For this reason you can't assume there's an edge visible on a **t_connection** or
+**center** tile. Consider the center tile in a table like this, represented by a capital T amidst
+lower case:
+
+```
+.....
+.ttt.
+.tTt.
+.ttt.
+.....
+```
+
+That **center** tile can't be drawn as a 4-way intersection, or there would be holes in the table.
+It has to be drawn as a flat contiguous tabletop. Likewise the **t_intersection** tiles (the middle
+piece of each edge section) should be assumed to connect diagonally as well, again to prevent holes
+in the table.
+
+
+### Slicing autotiles
+
+Before an autotile template can be used by the game, it needs to be sliced up into individual tiles.
+We use the `tools/slice_autotiles.py` script to achieve this.
+
+To run the script, you will need [python](https://python.org) installed, as well as the libvips
+graphic library. Something like these commands should suffice to install them on Ubuntu:
+
+```
+$ sudo apt install python3-pip libvips
+$ pip3 install pyvips
+```
+
+If all goes well, you should be able to run the `slice_autotiles.py` script and see the usage note:
+
+```
+$ tools/slice_autotiles.py
+usage: slice_autotiles.py [-h] [--no-json] tile size image out
+slice_autotiles.py: error: the following arguments are required: tile, size, image, out
+```
+
+So if you have created a `mud_autotile.png` image, using the autotile template above, you can tell
+the script to slice it into 32x32-pixel tiles with a command like this:
+
+```
+$ tools/slice_autotiles.py mud 32 mud_autotile.png mud_tiles
+```
+
+This will create a `mud_tiles` folder with separate images for each tile in the template, along with
+a JSON file with connection data, for example:
+
+- mud.json
+- mud_center.png
+- mud_corner_ne.png
+- mud_corner_nw.png
+- mud_corner_se.png
+- mud_corner_sw.png
+- mud_edge_ew.png
+- mud_edge_ns.png
+- mud_end_piece_e.png
+- mud_end_piece_n.png
+- mud_end_piece_s.png
+- mud_end_piece_w.png
+- mud_t_connection_e.png
+- mud_t_connection_n.png
+- mud_t_connection_s.png
+- mud_t_connection_w.png
+- mud_unconnected.png
+

doc/how-to/image/autotile_template_grid.png

@@ -0,0 +1 @@
+../../../templates/autotile_template_grid.png

doc/how-to/image/f_bathtub_autotile.png

@@ -0,0 +1 @@
+../../../scratch/UltimateCataclysm/furniture/f_bathtub_autotile.png

doc/how-to/image/f_bench_autotile.png

@@ -0,0 +1 @@
+../../../scratch/UltimateCataclysm/furniture/f_bench_autotile.png

doc/how-to/image/f_table_autotile.png

@@ -0,0 +1 @@
+../../../scratch/UltimateCataclysm/furniture/f_table_autotile.png

doc/how-to/image/t_fence_autotile.png

@@ -0,0 +1 @@
+../../../scratch/UltimateCataclysm/terrain/t_fence_autotile.png

doc/how-to/image/t_grass_tall_autotile.png

@@ -0,0 +1 @@
+../../../scratch/UltimateCataclysm/terrain/t_grass_tall_autotile.png

doc/how-to/image/t_water_sh_autotile.png

@@ -0,0 +1 @@
+../../../scratch/UltimateCataclysm/terrain/t_water_sh_autotile.png

doc/how-to/structure.md

@@ -0,0 +1,9 @@
+# Tileset structure
+
+*// TODO: rewrite*
+
+- 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.
+

doc/how-to/summary.md

@@ -0,0 +1 @@
+# How to

doc/installation.md

@@ -0,0 +1,36 @@
+# Installation
+
+## 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.
+
+1. Download the [latest release](https://github.com/I-am-Erk/CDDA-Tilesets/releases/latest) from the releases page (Not the source code !).
+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.
+
+## Develop
+
+The most up to date build of the tileset (per commit). Might be broken.
+
+1. Locate the most recent commit that has a green check right next to it [here](https://github.com/I-am-Erk/CDDA-Tilesets/commits/master).
+2. Click on the green check -> *"CI Build / CI Build" Details*
+3. Find *Artifacts* drop-down menu, click on it, and then select the artifact.
+4. Proceed with step 2 and 3 from stable installation.
+
+> 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`) 
+- [compose.py](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/tools/gfx_tools/compose.py) script from the main [Cataclysm-DDA](https://github.com/CleverRaven/Cataclysm-DDA) repository
+
+Once you have everything ready, you can build the tileset:
+```sh
+# Assuming that you are in the root of the tileset repository
+$ python3 <path-to-compose-py-script>/compose.py gfx/UltimateCataclysm
+```

doc/style/creatures.md

@@ -0,0 +1,24 @@
+# Creatures
+
+## Take appropriate tile size
+
+Consider 32x64 a default template for human-sized creatures:
+
+![male](image/skin-male.png)
+![female](image/skin-female.png)
+
+# Monster sprites should have ~8px offset from the ground
+
+*// TODO: image*
+
+To give them a 3d look.
+
+# Facing to the right by default
+
+And remember that tiles are mirrored when creatures move.
+
+# Monsters should drop shadows when possible
+
+*// TODO: image*
+
+Put shadows in a `bg` field in json, use `shadow_<width>x<height>_<size>` template. You can find shadow files in the root of any size directory (e.g. `pngs_normal_32x32`).