rogged/docs/README.md

# Rogged

Turn-based, infinite roguelike dungeon crawler built with C99 and with a dash of
Zig. Meant to serve primarily, but not exclusively, 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 or die chasing a highscore!

The game itself, be it the code or mechanics, is _heavily_ in development. For
now, a non-exhaustive list of its (current) features are as follows:

- 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

There are still some features lacking polish, or lacking _any_ kind of attention
to be viable. For a semi-complete list of things that need to be done, see the
[future plans section](#future-plans).

## Build Instructions

Rogged is built on a relatively simple stack. It uses C99 for the main game
logic, and Zig for the combat library. Besides `raylib` and `pkg-config`, you
only need the core Zig tooling. For now the required Zig version is 0.15.2, but
this might change in the future. Additionally, you will need `clang-format` and
`just` for common development tasks in the case you plan to contribute. For
building, Zig is enough.

### Using Nix (Recommended)

The _recommended_ way of developing this project is using
[Nix](https://nixos.org) and relying on devshells for pure, reproducible
developer environment across all machines.

If you are a [Direnv](https://direnv.net) user, you may simply run
`direnv allow` or you may use `nix develop` to enter the default shell.

```sh
# Enter the development shell
$ nix develop

# Build and run
$ just dev
```

### Manual Build

If you are allergic to good tooling and would rather use your system Zig, you
may simply invoke `zig build` after acquiring Zig 0.15.2.

```sh
# Full build
$ zig build

# Build and run
$ zig build run

# or
$ just dev
```

The Justfile provides commands that work across both methods.

### 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 a fair bit of polish
to claim its place as a fun, engaging roguelike you can just boot up and play.
Some of the features that are planned for the future, in no particular order,
are as follows:

- [ ] **Better enemy AI** - The current AI is very simple.
- [ ] **Fog of War** - Instead of loading the entire map, let the player
      discover the rooms
- [ ] **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

Later down the line it might be an interesting choice to provide a scripting
API, likely with Lua, to allow customizing the game state and events. 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 :/_