Merge pull request 'docs: add a proper README' (#5) from notashelf/push-omrqsvynvltn into notashelf/push-nrzuupynktom

Reviewed-on: NotAShelf/rogged#5

README.md

@@ -1,3 +1,121 @@
-# rogged
+# Rogged
 
-I got rogged :/
+Turn-based roguelike dungeon crawler, built in C99 and with a dash of Zig to
+serve as a learning opportunity. Rogged is basically a classic roguelike where
+you descend through floors of a procedurally generated dungeon, fighting
+enemies, managing inventory, and trying to reach the bottom alive.
+
+A non-exhaustive list of its (current) features:
+
+- Turn-based combat with damage variance, critical hits, dodge, and block
+  mechanics
+- Damage classes (Slash, Impact, Pierce, Fire, and Poison)
+- Status effects (Poison, Bleed, Stun, Weaken, and Burn)
+- Various enemy classes (Goblin, Skeleton, Orc) with distinct resistance
+  profiles
+- Procedural dungeon generation with rooms and corridors, seeded per floor
+- Inventory and equipment system (weapons, armor, potions)
+- Procedural audio via raylib
+- ASCII-inspired tile rendering, with HP bars and floating damage text
+
+**Controls:**
+
+| Key           | Action                              |
+| ------------- | ----------------------------------- |
+| WASD / Arrows | Move or attack                      |
+| G             | Pick up item                        |
+| I             | Open inventory                      |
+| U             | Use a potion                        |
+| E             | Equip item from inventory           |
+| D             | Drop item                           |
+| Y / N         | Confirm / decline descending stairs |
+| R             | Restart (on game over)              |
+| Q             | Quit                                |
+
+## Build Instructions
+
+Rogged is built with C99 and Zig. Besides `raylib` and `pkg-config` you will
+need a C compiler and basic Zig tooling. For now, we use C99 and Zig 0.15.2.
+Those might change in the future.
+
+Additionally you will need `clang-format` and `just` for the developer workflow
+if you plan to contribute.
+
+### Using Nix (Recommended)
+
+The recommended developer tooling is [Nix](https://nixos.org). This provides a
+pure, reproducible devshell across all machines.
+
+```sh
+# Enter the development shell
+$ nix develop
+
+# Build and run
+$ just dev
+```
+
+### Manual Build
+
+```sh
+# Full build
+$ zig build
+
+# Build and run
+$ zig build run
+
+# or
+$ just dev
+```
+
+### Task Runner Commands
+
+There's a `Justfile` designed to make common tasks somewhat easier. For now,
+they are as follows:
+
+```sh
+just build       # zig build
+just dev         # zig build run
+just clean       # remove zig-out/ and .zig-cache/
+just fmt         # format all C and Zig source files
+just fmt-check   # check formatting
+```
+
+If the project gets more complicated, new tasks might be added.
+
+## Future Plans
+
+The game is currently **playable end-to-end** but it lacks _serious_ polish to
+claim its place as a fun roguelike. Some of the features I'd like to introduce,
+in no particular order, are as follows:
+
+- [ ] **Save / Load system** - Persist and restore game state between sessions
+- [ ] **More enemy variety** - Additional enemy types with unique abilities
+- [ ] **More item variety** - Rings, wands, scrolls, and cursed items
+- [ ] **Multiple floors beyond 5** - Endless or configurable depth
+- [ ] **Test suite** - Unit tests for combat math, dungeon generation, and RNG
+- [ ] **Field of view** - Fog of war and line-of-sight mechanics
+- [ ] **Level transitions** - Upward stairs and floor teleportation
+- [ ] **Achievements / death log** - Track runs and causes of death with a
+      leaderboard
+- [ ] **UI polish** - Better message log history, item descriptions, death
+      screen
+
+In addition, it might be interesting to allow customizing the "world state" by
+as scripting API. Though, that is for much later.
+
+## Attributions
+
+[Shattered Pixel Dungeon]: https://github.com/00-Evan/shattered-pixel-dungeon
+[Raylib]: https://www.raylib.com
+
+This project draws a fair bit of inspiration from [Shattered Pixel Dungeon].
+While the mechanics are generally different, and commit to remain as such, I
+cannot deny the amount of inspiration & ideas Shattered Pixel Dungeon has given
+me. It's a GPL licensed project, and no code was borrowed. Still, some
+resemblance may occur.
+
+Additionally, _huge_ thanks to [Raylib] for how easy it made graphics and audio.
+This was perhaps my best experience in developing a graphical application, and
+CERTAINLY the most ergonomic when it comes to writing a game.
+
+_I got rogged :/_