update the map definitions

1 files changed, 46 insertions, 0 deletions

diff --git a/maps/Readme.md b/maps/Readme.md
new file mode 100644
index 00000000..c1bbcc9e
--- /dev/null
+++ b/maps/Readme.md
@@ -0,0 +1,46 @@
+# Map Definitions for Muhq's Game
+
+## Available Maps
+
+```
+maps
+├── 2P-ring-street.yml
+├── 2P-river-king.yml
+├── 3P-ring-street.yml
+├── 4P-islands.yml
+├── the-kraken.yml
+└── the-tyrant.yml
+```
+
+## Naming Convention
+  * Map names use kebab case
+  * Maps start with their player amount
+  * Map names somehow describe their features (`ring-street`, `islands`, `river`, ...)
+  * Boss maps are named after the boss
+
+## Yaml Schema
+
+### Required Keys
+Map definitions are written in Yaml and must have at least the following keys:
+
+```yaml
+map: # A multiline string featuring one character per tile
+```
+
+All trailing newlines are removed from the `map` string.
+It is advised to use `|+` to preserve potential meaningful trailing white space.
+
+```yaml
+symbols: # The symbols must contain the tile descriptions for each character used in the map
+```
+
+The `" "` key will be inserted automatically for `neutral` tiles if it is not present in the symbols. 
+Symbols should be quoted to ensure they are parsed as characters.
+
+### Optional Keys:
+
+  ```yaml
+  start_deck_list: # A string containing the map's starting deck list
+  win_condition: # The map's win condition
+  kings: # A list of the 0-based positions of each player's king
+  ```