feat: add initial documentation covering game assets, configuration, …

CONFIGURATION.md

@@ -0,0 +1,94 @@
+# Zanthor – Configuration System
+
+Zanthor ships with a simple, modular configuration system that lets
+players tweak **display, audio, controls and gameplay** settings either
+from the in‑game **Options** screen or by hand‑editing a JSON file.
+
+---
+
+## In‑game Options Screen
+
+Open the game → **Options** on the title menu.
+
+| Input | Action |
+|---|---|
+| Mouse click | Select tab / row / button; drag a slider; click again to edit |
+| `Tab` / `Shift+Tab` | Cycle tabs |
+| `↑` / `↓` | Move selection |
+| `←` / `→` | Adjust current value (slider / choice / toggle) |
+| `Enter` / `Space` | Toggle / cycle / start key‑rebind |
+| Mouse wheel | Scroll the options list |
+| `Esc` | Back (auto‑saves on exit) |
+
+Key‑rebind: select a key‑binding row → `Enter` → press any key, or
+`Backspace` to clear the binding, or `Esc` to cancel.
+
+Settings marked with a red `*` require restarting the game.
+
+---
+
+## Configuration file
+
+The file lives at a platform‑appropriate location:
+
+| Platform | Path |
+|---|---|
+| Linux / BSD | `~/.config/zanthor/settings.json` |
+| macOS | `~/Library/Application Support/zanthor/settings.json` |
+| Windows | `%APPDATA%\zanthor\settings.json` |
+| Override | set `$ZANTHOR_CONFIG_DIR` |
+
+It is **safe to hand‑edit** – the loader validates and clamps every
+value.  Missing keys fall back to defaults; unknown keys are ignored;
+a corrupt file simply yields the defaults (and is logged, not thrown).
+
+Example:
+```json
+{
+  "display": {
+    "resolution": [1024, 768],
+    "fullscreen": true,
+    "fps_cap": 60,
+    "skip_intro": true
+  },
+  "audio": {
+    "music_volume": 0.5,
+    "sfx_volume": 0.8,
+    "mute": false
+  },
+  "controls": {
+    "move_up":    ["i"],
+    "move_down":  ["k"],
+    "move_left":  ["j"],
+    "move_right": ["l"],
+    "fire":       ["e"],
+    "mouse_look": false
+  },
+  "gameplay": {
+    "auto_pickup": false,
+    "holes_are_tiles": 1
+  }
+}
+```
+
+Key names are the human‑readable names returned by
+`pygame.key.name()` (`"space"`, `"left ctrl"`, `"return"` …).
+
+---
+
+## For developers
+
+The two new modules are drop‑in:
+
+* **`zanthor/settings.py`** – schema‑driven `Settings` singleton.
+  Adding a new option is one line in the `SCHEMA` dict and it shows up
+  in the UI automatically.  `settings.get("section.key")`,
+  `settings.keys("move_up")`, `settings.save()` … that's the whole API.
+
+* **`zanthor/options.py`** – a `pgu.engine.State` that renders the
+  Options screen purely with pygame primitives (no extra deps).
+
+`const.py` now sources its previously hard‑coded values from
+`settings`, and `KEYS_UP()`, `KEYS_FIRE()` etc. helpers are used by
+`castle.py`, `menu.py` and `level.py` instead of literal `K_*`
+constants, so rebinds take effect immediately.

INSTALL.md

@@ -0,0 +1,77 @@
+# Zanthor Installation Guide
+
+Zanthor is a game built with Python and Pygame where you play an evil robot castle. 
+
+## Requirements
+- **Python 3.6 or higher** (Python 3.12+ recommended)
+- **Pygame** (or `pygame-ce`, which is recommended for modern Python versions)
+
+---
+
+## 🚀 Running from Source (Recommended)
+
+Follow these steps to run the game directly from the downloaded source code without installing it permanently to your system.
+
+### 1. Extract the Game Files
+If you downloaded a `.zip` file, extract it to a folder of your choice. Open your terminal or command prompt and navigate to that folder:
+```bash
+cd path/to/zanthor
+```
+
+### 2. Install Dependencies
+The game requires the `pygame` library. On modern versions of Python, it is highly recommended to install Pygame Community Edition (`pygame-ce`), as it provides pre-built wheels and avoids compilation errors.
+
+```bash
+python -m pip install pygame-ce
+```
+*(Note: If you are on Linux/macOS and `python` defaults to Python 2, use `python3 -m pip install pygame-ce` instead).*
+
+### 3. Run the Game
+Once the installation finishes, you can start the game right away:
+
+```bash
+python run_game.py
+```
+
+---
+
+## 📦 System-wide Installation (Optional)
+
+If you prefer to install Zanthor so you can launch it from anywhere on your computer using the `zanthor` command:
+
+### 1. Navigate to the Source Folder
+```bash
+cd path/to/zanthor
+```
+
+### 2. Install using pip
+Run the following command to install the project and its dependencies:
+
+```bash
+python -m pip install .
+```
+
+*Troubleshooting note:* The `setup.py` explicitly demands `pygame`. If this fails on your system due to missing build tools for older pygame versions, install `pygame-ce` first (`pip install pygame-ce`) and try again, or just use the **Running from Source** method above.
+
+### 3. Launch from Anywhere
+After a successful installation, you can launch the game from any terminal window simply by typing:
+```bash
+zanthor
+```
+
+---
+
+## 🎮 Controls
+
+### Keyboard
+- **Move**: Arrow keys or `W`, `A`, `S`, `D`
+- **Fire**: `F`, `Space`, or `Ctrl`
+- **Pause**: `F10`
+
+### Mouse
+- **Fire**: Left Button (Button 1)
+- **Move**: Right Button (Button 2)
+
+### Gamepad / Joystick
+- **Move**: D-Pad or Analog Stick
+- **Fire**: Button 1