⚔️ Crawl RS: Roguelike game in terminal

A classic ASCII roguelike in pure terminal Rust. Procedurally generated dungeons, turn-based combat, permadeath. Runs over SSH; scales from a phone shell to a 4K terminal.

Current version: 0.1.1

---

Install

Repository: https://github.com/drasogun/crawl-rs Latest release: https://github.com/drasogun/crawl-rs/releases/latest

Option A — pre-built binaries (no Rust required)

Each tagged release on GitHub attaches binaries for all three platforms. Download the one that matches your OS from the releases page.

Linux (x86_64) — binary

curl -L -o crawl-rs \
  https://github.com/drasogun/crawl-rs/releases/latest/download/crawl-rs-linux-x86_64
chmod +x crawl-rs
sudo mv crawl-rs /usr/local/bin/
crawl-rs

Linux (x86_64) — Debian / Ubuntu package

curl -L -o crawl-rs.deb \
  https://github.com/drasogun/crawl-rs/releases/latest/download/crawl-rs_linux_amd64.deb
sudo dpkg -i crawl-rs.deb
crawl-rs

macOS (universal — Intel + Apple Silicon)

curl -L -o crawl-rs \
  https://github.com/drasogun/crawl-rs/releases/latest/download/crawl-rs-macos-universal
chmod +x crawl-rs
sudo mv crawl-rs /usr/local/bin/
# Remove quarantine flag added by macOS Gatekeeper (only needed once):
xattr -d com.apple.quarantine /usr/local/bin/crawl-rs
crawl-rs

Windows (x86_64)

PowerShell:

Invoke-WebRequest `
  https://github.com/drasogun/crawl-rs/releases/latest/download/crawl-rs-windows-x86_64.exe `
  -OutFile crawl-rs.exe
.\crawl-rs.exe

Move crawl-rs.exe somewhere on your PATH (e.g. %USERPROFILE%\bin) to launch it from any directory. Windows Terminal gives the best rendering.

Option B — build from source

Requires Rust 1.75 or newer. Get it from https://rustup.rs.

git clone https://github.com/drasogun/crawl-rs.git
cd crawl-rs
cargo install --path crawl-rs

The binary lands in ~/.cargo/bin/crawl-rs (Linux/macOS) or %USERPROFILE%\.cargo\bin\crawl-rs.exe (Windows). Add that directory to your PATH if it isn't already:

Shell	One-liner
bash	echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc && exec bash
zsh	echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc && exec zsh
fish	fish_add_path $HOME/.cargo/bin
PowerShell	[Environment]::SetEnvironmentVariable('Path', $env:Path + ';' + "$env:USERPROFILE\.cargo\bin", 'User')

Option C — run without installing

git clone https://github.com/drasogun/crawl-rs.git
cd crawl-rs/crawl-rs
cargo run --release

Run

crawl-rs                # title screen → new game / continue / quit
crawl-rs --seed 42      # skip menu, start a deterministic run
crawl-rs --dump --count 5 --seed 1
                        # print 5 BSP maps to stdout (no TUI)
~/.cargo/bin/crawl-rs

Controls

Key	Action
w a s d / arrow keys	move (4-way)
q e z x	move diagonally (NW NE SW SE)
.	wait one turn
f or ,	pick up item
i	open inventory
b	open book / codex
k	open character status
h	open key help
> (on > tile)	descend stairs
esc / ctrl-c	save and quit

q is the NW diagonal during play, so quitting is bound to esc (or ctrl-c) to avoid clobbering a movement key. On the title screen and the death/victory screens, q still works as quit.

In the inventory screen, the up/down arrows (or w / x) move the cursor, f (or enter) uses or equips the highlighted slot, and g sells the slot for XP (equipped items auto-unequip on sale). esc or i closes the screen without spending a turn.

The book (b) has mob and item pages. Entries stay hidden as ??? until you first see that mob or item, then the codex shows stats, abilities, range, duration, and related notes.

The status screen (k) shows your current final values: HP, atk+, def-, move, sight, XP progress, kills, pack size, equipment, and active effects.

The help screen (h) shows the in-game Key / Action list so controls are always available without leaving the run.

Levelling

Killing mobs and selling items both award XP. Each level requires 50 × current_level XP. On level-up the player gains +5 max HP, +5 HP, +1 attack, +1 defense, +5 inventory slots. The HUD shows current level + progress as lv N (xp/needed).

How it works

• ECS via hecs
• BSP dungeon generation per level (20 levels, increasing density)
• Recursive shadowcasting FOV (8 octants, radius 8) with memory tiles
• Round-based movement (move_tiles per round)
• Combat damage: max(1, 1d6 + atk - def)
• Player attacks resolve before the enemy round; if you kill a mob first, it does not hit back
• Ranged mobs attack from 2 tiles away and cannot move on the same round they attack
• Persistent book / codex discoveries saved separately from the run save
• Bincode save (single slot, deleted on death)
• Deterministic given --seed N — record this in any bug report

Win condition

Reach depth 20 and pick up the Amulet of Yendor. Permadeath: you die, the save file is gone, and your score is recorded in the high-score table.

Notable seeds

See examples/seeds.txt.

Demo

Recording a play session: asciinema rec demo.cast then play with asciinema play demo.cast. Drop the recording into the README of any fork you make.

License

MIT — see LICENSE.

Support

If WiringWorkbench is useful to you, you can support the project here:

Support Me