[P&P] Documentation update (#2489)

* screenshots

* Update colors.md

* old maps

* Update colors.md

* bg_examples

* size fix

* Update colors.md

* bgs

* Update colors.md

* colors

* Update colors.md

* support for new granularity buildings

CleverRaven/Cataclysm-DDA#75704

* Update colors.md

* addons

* added first Ukrainian page

* small fix

* added usage UA translation

* fallback translation

* colors.md translated

* added TODO marks

* Create file_structure.md

* Create file_structure.ua-UA.md

* removed one TODO:

* UA translation removed

* Update usage.md

* added workflow file

* Create credits.txt

doc/style/PenAndPaper/colors.md

@@ -1 +1,115 @@
 # Used Colors and Pens properties
+
+## At the beginning there was SM_Overmap
+
+The idea for this tileset had been floating around for quite some time, and I wasn’t the first to implement it. A survivor character drawing their own map is a fairly obvious move. The first to implement it was @curstwist with the SurveyorMap tileset. I am very glad that I was able to participate in its creation. However, there we drew player markings on top of the ‘official’ map. I made some decisions there that later turned out to be not the most popular among players.
+
+For example, the background. Many find it very bright in the SM tileset. And Wist is going to make it darker. In search of inspiration, I looked at old hand-drawn maps. And I decided that the new tileset should be just like that.
+
+<details>
+   <summary>SM background circa 2022</summary>
+
+![2022 SurveryorMap screenshot](./images/SM_example.png)
+
+</details>
+
+<details>
+   <summary>Old map, example 1</summary>
+
+![Actual map, 1500-1600](./images/old_map1.png)
+
+</details>
+
+<details>
+   <summary>Old map, example 2</summary>
+
+![Actual map, 1800-1900](./images/old_map2.png)
+
+</details>
+
+The background color should resemble paper in dim light, paper in the light of a flashlight. And the brightness of the map should not be more than 50%. Since most of the time players see unexplored territory (black) and often move at night (the main screen is dark). At the same time, Ultica in winter is quite bright.
+
+Below you can see first attempt to find a sweet spot (top left) and current background (bottom right).
+![bg_combined](./images/backgrounds.png)
+
+Looking at the image above, the map’s background might seem dark. However, below I provide a comparison of the map with nighttime player movements (bottom left quarter) and a bright spring day (bottom right quarter). As you can easily see, the map is not much darker than the daytime screenshot, and I hope it doesn’t differ significantly from the nighttime one.
+
+In any case, the entire tileset is based on the concept of transparent sprites. This will allow any adjustments to the background if necessary.
+
+## Background
+
+![brightness](./images/brightness_test.png)
+
+1) As I just mentioned, sprite transparency is one of the pillars of the tileset.
+
+2) The second pillar is having multiple variations for the same object.
+
+3) Third is hand-drawn elements (wobbly lines, absence of straight angles, etc.).
+
+4) And the last - readability takes precedence over artistic beauty. The image should be clear at first glance, without forcing the player to decipher a jumble of lines. You can imagine it as the survivor trying to mark an object on the map as quickly as possible, rather than creating a museum-worthy piece of art.
+
+And the background is no exception from these rules. To create the feeling of a large sheet of paper on which the map is drawn, I created 25 sprite variations (you can see the workflow in the corresponding section).
+
+Background color: #7d7869 or in the HSB model:
+
+- Hue: 45
+- Saturation: 15%
+- Brightness: 50%
+
+*Due to the additional texture imitating irregularities, the saturation and brightness values may vary slightly in different areas.*
+
+Below, I provide the original sprite, which was later divided into 25 variations.
+
+![background_variants](./images/bg_variants.png)
+
+Regarding the fog of war, I initially wanted to make these areas lighter, as if the paper there was cleaner, and the known area of the map was where the player had already drawn/erased objects. However, I later abandoned this idea in favor of the more commonly accepted darkening.
+
+Another idea is to make the unknown territory noisy, so it appears out of focus or with interference. This can be achieved using the same variations, by playing with the saturation and brightness of the sprites.
+
+Even a fluctuation of minus two percent to plus two percent is noticeable on a large map, but completely invisible on the original large sprite.
+
+| background for uncertain areas | background for unknown areas |
+|--------------------------------|------------------------------|
+| ![bg_outlines](./images/bg_outlines_variants.png) | ![bg_unknown](./images/bg_unknown_variants.png) |
+
+In game you can notice those effects easily:
+![bg_in_game](./images/backgrounds_in_game.png)
+
+## Drawing lines
+
+I wanted to move away from the pixel art style in map representation while staying within the existing sprite rendering methods.
+
+To achieve this, I decided to use the “brush” tool instead of the “pencil”. This creates of semi-transparent pixels when drawing, and from a sufficient distance, it gives the effect of smooth lines drawn with a pen on paper.
+
+Since the map in the game can be scaled, I had to use a width of 2 pixels to maintain the visibility of the lines.
+
+However, with this tool, the usual 24 or 32 pixels per tile become too small a canvas for drawing.
+
+Thus, the resulting sprite size became 48x48 pixels.
+
+Note that coloring even a small part of the image (e.g., the entrance to a cave) immediately makes the object stand out on the map. Try not to overuse this.
+
+| Pencil | Pen |
+|--------|-----|
+| ![pencil](./images/cave_pencil.png) | ![pen](./images/cave_pen.png) |
+
+> [!WARNING]
+> The background here is just for better visibility. The actual sprite has a transparent background.
+
+Most objects should be drawn with a black pen, as they have better contrast with the background.
+
+Common houses are brown (refer to colors [here](./fallback.md)), forest trees are green, and meadows are brown, as well as dirt roads.
+
+Military objects and craters are red.
+
+Water bodies (from streams to oceans) have a different blue color than those described above. The main color is RGB: #001c54, HSB: 220 / 100% / 33%.
+
+The pencil is a black "pen" with 50% transparency. Large overmap objects (starting from 2x2 tiles) should have a pencil border line.
+
+Objects on the map should be drawn with dark pens or pencils. White is reserved for extremely important marks like high objects and "stairs" between Z-levels.
+
+*Also used for highlighting autotravels and recently revealed roads so it is pretty common sometimes.*
+
+Bright "highlighters" are for manual player usage.
+
+![colors](./images/colors.png)

doc/style/PenAndPaper/credits.txt

@@ -0,0 +1,2 @@
+old_map1.png is a part of CC0 image from https://en.wikipedia.org/wiki/Glamorgan#/media/File:Glamorgana_Atlas.jpg
+old_map2.png is a part of a antique map photo, the map itself from 1754, so I think there should be no problem with it. Source: https://www.puddletownbookshop.co.uk/product/47237/An-Accurate-Map-of-Glamorgan-Shire-Drawn-from-an-actual-survey-with-various-Improvements-Illustrated-with-Historical-Extracts-relative-to-its-Natural-Products-Air-Soil-Trade-Manufacture-ampc

doc/style/PenAndPaper/fallback.md

@@ -46,6 +46,7 @@ The last 6 blocks are for bright colors. My idea was to make the characters in t
 
 > [!NOTE]
 > For those who familiar with HSB color space there are some hints:
+>
 > - highlighters have saturation 66% and brightnes 85%
 > - pens have saturation 100% and brightnes 40%
 
@@ -59,13 +60,13 @@ It is also worth noting that the dot symbol has been made significantly larger a
 <tr><th>Pen or pencil</th><th>&nbsp;</th></tr>
 <tr><td>
 
- dark gray   (`dg`) (<i>black pen actually</i>)
- 
- dark cyan   (`C`)
- 
- magenta     (`m`)
- 
- brown       (`br`)
+dark gray   (`dg`) (*black pen actually*)
+
+dark cyan   (`C`)
+
+magenta     (`m`)
+
+brown       (`br`)
 
 </td><td>
 
@@ -89,7 +90,7 @@ white       (`W`)
 </td></tr>
 <tr><td>
 
-light gray  (`lg`) (<i>pencil</i>)
+light gray  (`lg`) (*pencil*)
 
 red         (`R`)
 
@@ -113,7 +114,6 @@ blue        (`B`)
 
   `l`   : arrow right
 
-
 </td></tr>
 </table>
 
@@ -131,16 +131,16 @@ light cyan  (`c`)
 
 pink        (`P`)
 
-yellow      (<i>default</i>)
+yellow      (*default*)
 
 </td><td>
 
    `(`   : dead face
-   
+
    `)`   : happy face
-   
+
  `-`,`/`,`=` : wide strokes
- 
+
    `@`   : human figurine
 
 </td></tr>

doc/style/PenAndPaper/file_structure.md

@@ -0,0 +1,121 @@
+# P&P repository file structure
+
+- `pngs_overmap_48x48`: This folder contains almost all sprites. Details below.
+- `pngs_backgrounds_48x48`: This folder should contain only background sprites, so players can change the brightness all together with one action, for all sprites including unknown terrains.
+- `pngs_weather_96x96`: To achieve the effect of long diagonal strikes across many tiles, I had to use double-sized sprites (four times bigger in terms of area).
+- `pngs_weather_unknown_48x48`: Unknown sky areas have similar sprites to the ground ones, but blue. All are here.
+- `pngs_icons_96x96`, `pngs_icons-h_96x48`, `pngs_icons-v_48x96`: These three folders could be combined into one under different circumstances. However, the current rendering engine forced me to create additional sprites that have only half of the mission arrow sprite. The idea of the mission arrow sprite is a square patch of transparent film attached to the edge of the map. Maybe one day we can make it more obvious.
+- `pngs_cursor_288x144`: A single cursor sprite, so players can easily change it later on the client side.
+
+## Common overmap sprites
+
+Most sprites fall into this category. It is important to remember that to keep the tileset’s characteristics and flexibility, all sprites must be separated into the actual image and the background, which is standard for all sprites. A JSON file combines everything together.
+
+Many objects consist of more than one tile on the map. It is assumed that the survivor always draws them upright on the map. However, the game mechanics rotate objects, so these rotations must also be compensated in the JSON file.
+
+To avoid creating JSON files from scratch each time or searching for them throughout the repository, I have tried to group them. Objects with the same dimensions on the map are placed in corresponding folders. The terrain is stored separately, as are objects related to granular visibility.
+
+### 1x1 tile object
+
+These objects usually consist of a foreground sprite and a JSON file. Ideally, objects that occupy a single tile should have at least a few variations. Since such objects often appear close to each other, repetition can diminish the handmade map effect.
+
+```json
+[
+  {
+    "id": [
+      "animalpound", "animalpound_roof",
+      "animalshelter", "animalshelter_roof"
+    ],
+    "fg": "animal_shelter",
+    "bg": [
+      { "weight": 1, "sprite": "bg_00" },
+...
+      { "weight": 1, "sprite": "bg_23" },
+      { "weight": 1, "sprite": "bg_24" }
+    ]
+  }
+]
+```
+
+I recommend always enclosing the sprite description in square brackets, as this will simplify adding and modifying the JSON file in the future.
+
+Pay attention to the list of IDs - it is advisable to include roofs and basements. This will make it easier to navigate the map.
+
+In this example, only one foreground sprite is used.
+
+However, the background uses all 25 available variations. If there are multiple sprites for the foreground, a similar structure will need to be written. Never include the background in the final sprite. This will maintain the flexibility and size of the tileset.
+
+In this example, the “rotates” attribute with the value false is omitted. This is the default value. It means that even if the object on the map is rotated with the “entrance” facing south, the sprite will still remain in the correct position.
+
+### 1x2 tile object (this is vertical object when facing North)
+
+I have tried to include templates in most folders with standard sizes, so you can use them for typical objects. I do not recommend using JSON files from other objects, as some objects have non-standard rotations or different sets of IDs.
+
+```json
+[
+  {
+    "//helper": [
+      "    N   ", "    W   ", "    S   ", "    E   ",
+      "_0_ 1 2 ", " 0 _1_2 ", " 0  1 2 ", " 0  1_2_",
+      " 3      ", " 3      ", "_3_     ", " 3      "
+    ],
+
+
+
+    "id": [
+      "template1x2_A"
+    ],
+    "rotates": true,
+    "fg": [
+      "template1x2_var_00", "template1x2_var_01", "template1x2_var_03", "template1x2_var_02"
+    ],
+    "bg": [
+      { "weight": 1, "sprite": "bg_00" },
+...
+      { "weight": 1, "sprite": "bg_24" }
+    ]
+  },
+
+
+
+  {
+    "id": [
+      "template1x2_B"
+    ],
+    "rotates": true,
+    "fg": [
+      "template1x2_var_03", "template1x2_var_02", "template1x2_var_00", "template1x2_var_01"
+    ],
+    "bg": [
+      { "weight": 1, "sprite": "bg_00" },
+...
+      { "weight": 1, "sprite": "bg_24" }
+    ]
+  }
+]
+```
+
+In this template, you can see three parts. The first part helps visually assess what will be described in the following two parts and is not necessary for the tileset to function.
+
+It is assumed that our object consists of two tiles and by default looks as follows when facing north:
+
+```
+A
+B
+```
+
+Looking at the helper section, you can see that tile A will receive the sprites with the numbers that are underlined when the object is rotated.
+
+Accordingly, tile B will receive the non-underlined sprites (3, 2, 0, 1).
+
+As you can see, four sprites had to be created for this object because it has vertical (N, S) and horizontal (W, E) orientations. Square objects can be represented with a single large image.
+
+The correct names for the tiles (instead of A and B) need to be specified each time, there is no naming convention.
+
+### Common terrain
+
+Here are the sprites that form the main background of the map - forests, fields, rivers, etc. I want to remind you again about the variability of sprites. For example, I had to create more than 75 sprites for the forest to avoid it looking too repetitive.
+
+### Granular
+
+Sprites related to PR [#75236](https://github.com/CleverRaven/Cataclysm-DDA/pull/75236)

doc/style/PenAndPaper/summary.md

@@ -7,7 +7,7 @@ The overall style of this tileset is to give the map a hand-drawn effect. The fo
 3. Given the limited visual resources, try to show important objects and territory boundaries to the player. The more understandable at first glance, the better.
 4. The map is designed for high-resolution screens and does not adhere to the concept of displaying sprites in pixel art style.
 
-## General Aspects:
+## General Aspects
 
 1. Sprites should be transparent; the map background is added in the corresponding JSON file.
 2. It is assumed that the player first draws on the map with a pencil in places where they are unsure. Objects they are sure of are drawn with a pen of the corresponding color.
@@ -16,7 +16,7 @@ The overall style of this tileset is to give the map a hand-drawn effect. The fo
 5. Try to draw sprites so that no more than 10 strokes are used per tile.
 6. If it is possible to convey the logic and idea so that some tiles remain empty but the map is still readable, strive to do so.
 
-## Specific Features:
+## Specific Features
 
 - [Used Colors and Pens properties](./colors.md)
 - [Fallback file usage](./fallback.md)

doc/style/PenAndPaper/usage.md

@@ -0,0 +1,41 @@
+# How to use this overmap tileset
+
+To get the most out of this tileset, it’s important to understand that it requires more player interaction.
+
+By default, the color indication on the map is quite minimal, and this is intentional. It allows the player to mark points of interest and danger zones on the map themselves. Just as we make notes on a real map, the player is expected to add some information manually.
+
+Of course, the game has an Autonotes feature, and I have tried to ensure that these notes match the style of what the player can add manually. This way, manual notes and Autonotes are meant to complement each other.
+
+Let's take a closer look:
+![screenshot](./images/notes_screenshot.png)
+
+As you can see here there are some notes:
+
+1) Yellow "Home" above three buildings. This note is made out of four different notes. These are common notes the player can write using `N` key.
+(`H:`,`o:`,`m:` and `e:` - notes values. As you can see only `:` is used to define the map glyph, and the color is default yellow.)
+2) Below `Home` there is a green stroke. It can be achieved by the note `-:g;`. The stroke of highlighers (bright colors) are relatively wide.
+3) The black `X` mark on the road was made manually.
+4) But the brown circle right near the pencil is autonote (*dead vegetables*)
+5) The grey circle on the road (*burned ground*) is also an autonote. So you can see that manual and autonotes are quite the same.
+6) Light green face is `):g;`. As you can notice, you have to put one symbol at a time on the map.
+7) But there is anoter type of notes that spreads around a central point. It is a red diagonal strokes around the magenta `o`. This indicates a danger zone. It would be great if we can create other long notes like this.
+8) The red line around the red tack is a set of notes you can ~~painfully~~ draw by numbers and `+` / `-` symbols.
+
+Full set of symbols can be found [here](./fallback.md#fallback-additional-features)
+
+## Additional info
+
+You can change several aspects of this overmap tileset on the client side (but of course, you have to do it each time after a tileset update).
+
+- cursor (pencil by default)
+- brightness/saturation of background as well
+
+You can download a couple of cursors from here:
+
+- [Orange semitransparent protractor](./images/cursor_protractor.png) - This was the first cursor. It has a couple of nice features: the ruler on the protractor is relatively accurate and almost equal to real centimeters/inches, and it has a couple of “handmade ticks” for 100 and 200 meters/yards(?). But this one can be confusing.
+- [Classic small red circle](./images/cursor_circle.png) - Can be used if you prefer a cursor that doesn’t span across several tiles.
+
+> [!WARNING]
+> You should save it as `cursor.png` in `\gfx\PenAndPaper\`. Save original `cursor.png` somewhere just in case.
+
+To change brightness/saturation of the tileset use any image editor and adjust those files.