Crypt Clash CLI (MVP)

A playable full-screen terminal RPG prototype using Python + Textual.

What is playable now

• Party-based adventure loop with exploration + encounters
• Turn-based action selection in a full-screen TUI with a dedicated battle screen panel
• Combat actions: Attack, Skills, Defend, Path, Bag, Equip Gear, Rest
• Explore actions: Venture Deeper, Look Around, Path, Bag, Equip Gear, Rest
• Explore actions also include contextual Open Chest after successful chest discovery.
• Path opens a dedicated mini-map overlay with route progress and legend
• Loot rewards, consumables, and simple per-character gear progression
• Encounter XP and level progression (level, xp, level-up stat gains)
• Autosave after actions, plus optional named save slots
• Ironman mode (one life, no manual save, hall-of-fame archive on victory)

Quickstart

cd /path/to/project
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cryptclash

Running cryptclash / DND with no subcommand now opens a full-screen launcher menu (splash screen) with built-in setup forms for online account/login/character and LAN host/join paths. The launcher also includes Start Local Server / Stop Local Server actions for one-click local online setup, and launcher actions return to launcher screens (instead of dropping back to raw terminal prompts).

One-command install (macOS/Linux)

If you're publishing this repo publicly, you can also let players run the installer script:

curl -fsSL https://raw.githubusercontent.com/VF-AdminOver/Crpyt-Clash/main/scripts/install.sh | bash -s -- --repo https://github.com/VF-AdminOver/Crpyt-Clash.git
cryptclash

Homebrew tap (best UX for macOS users)

Once you publish a Homebrew tap, players can install with:

brew tap VF-AdminOver/games
brew install dnd
cryptclash

Single command (no separate tap step):

brew install vf-adminover/games/dnd && cryptclash

Primary command is cryptclash (alias: crypt-clash). Legacy aliases DND / dnd remain for compatibility.

Start modes

cryptclash new --mode normal
cryptclash new --mode ironman
cryptclash new --hero <character_id>

cryptclash new opens a character creation flow before the run begins:

• Name (2-16 chars, letters/space/hyphen)
• Archetype (Fighter, Rogue, Cleric, Mage)
• Point-Buy 27 stat allocation (base 8-15)
• Live preview of derived combat stats while adjusting point-buy
• Review and confirm

Only cryptclash new opens creator. continue and load skip it and resume saves.

Roster

cryptclash roster

Use roster IDs with --hero to begin with a saved hero.

Continue a run

cryptclash continue

Load a specific save

cryptclash load --file ~/.dnd-cli/saves/autosave.json
cryptclash load --slot boss-run

Create a save slot

cryptclash save --slot boss-run

List saves

cryptclash list-saves

cryptclash list-saves now shows both active saves and hall-of-fame ironman victories.

Get a quick gameplay tip

cryptclash tip

Online MMO-lite (server-authoritative)

Install client+server extras (no Docker path):

pip install -e ".[online,server]"

Start the online server locally (no Docker):

./scripts/run-online-local.sh

Register/login from a client:

cryptclash register --server http://127.0.0.1:8000 --username iris
cryptclash login --server http://127.0.0.1:8000 --username iris

Notes:

• 127.0.0.1 means "this same machine" (you are hosting your own credentials/server locally).
• --server is optional for register/login/online; it defaults to last-used server, then local http://127.0.0.1:8000.
• Account passwords require at least 8 characters.

Create/list online characters:

cryptclash character create --name Iris --archetype Mage
cryptclash characters

Join the online hub:

cryptclash online --server http://127.0.0.1:8000

cryptclash online currently provides a command-loop hub client (party, ready, queue, react) as the first MMO-lite slice.

Docker path is also supported:

cp .env.example .env
./scripts/run-online-docker.sh

Guides:

• No Docker: /path/to/project/docs/online-local.md
• Docker: /path/to/project/docs/online-deploy.md

Online host/join (legacy LAN mode)

Start a host session (this machine owns the game state and opens the full Textual battle UI):

cryptclash host --bind 0.0.0.0 --port 8765 --code CRYP --name Host
cryptclash host --bind 0.0.0.0 --port 8765 --code CRYP --name Host --hero <character_id>
cryptclash host --bind 0.0.0.0 --port 8765 --code CRYP --name Host --chat-mode reactions_only
cryptclash host --bind 0.0.0.0 --port 8765 --code CRYP --name Host --chat-mode text_18_plus

Join from another terminal (or another machine on LAN) with the same full UI:

cryptclash join --host 127.0.0.1 --port 8765 --code CRYP --name Iris

Notes:

• Host is authoritative; clients send action intents only.
• First joined players are assigned party members automatically; extra joiners spectate.
• Unassigned party members are auto-piloted so the run never stalls.
• Room comms default to reactions-only; host can opt into text_18_plus chat mode.
• Host and join clients both use the polished panel UI (party, battle/map, log, actions).

Controls

• Number keys / numpad 1-9: choose matching action instantly
• Arrow keys + Enter: move and confirm selected action
• Mouse click: click icon action rows to trigger
• s: save to autosave (disabled in ironman)
• t: add a gameplay tip to the log
• r: restart encounter
• q: quit

Combat UX (V2)

• Turn flow: Action -> Style/Skill -> Target while keeping initiative order.
• Attack now opens styles: Quick (+hit, lower damage), Balanced, Heavy (-hit, higher damage).
• Skills opens class moves (2 per archetype) with mana cost shown as (X MP).
• Manual target picker appears for enemy/ally targeting with Target: labels.
• Mana rules: spend on skills, +1 mana at start of your turn, and +2 mana when using Rest in combat.

Chained Adventures

• Clearing all rooms now ends the current arc and unlocks Begin Next Adventure.
• Selecting it keeps your party progression (levels/gear), restores HP/MP, and starts a tougher new 3-room descent.
• Enemy stats and rewards scale by adventure number, so runs can continue as a long-form campaign.

Treasure Chests

• Some rooms contain hidden treasure chests.
• Look Around performs a discovery roll: d20 + INT mod vs DC 13 (max 2 attempts per room).
• Open Chest appears only after discovery and can be used once.
• Chests grant bonus gold and often a bonus consumable/item, and can only be opened once.

Look Around Outcomes

• Look Around can trigger a one-time roaming encounter check per room.
• On trigger, combat starts immediately as a side encounter and does not advance room depth when won.

Loot Economy (V2.2)

• Combat and chest rewards now use one unified item-drop pipeline.
• Rarity tiers use weighted odds (Common 65%, Uncommon 28%, Rare 7%), with chest rolls slightly favoring higher tiers.
• Rare pity protection guarantees the next drop is Rare after 5 non-rare drops.
• Smart bias softly boosts drops that fit alive party archetypes and under-equipped slots while still allowing surprises.
• Duplicate gear past useful copy limits is auto-salvaged into gold and logged.

Store Crafting & Trade

• Store actions now show explicit recipe costs and payouts in-line.
• Craft recipes currently include Healing Potion, Smoke Bomb, and Holy Water.
• Trade actions are dynamic (Sell ... x1 and Sell ... xAll) based on current inventory.

Notes

• This is an MVP focused on immediate playability.
• Content is original and text-only in-terminal (ASCII-friendly).

Roadmap

• Track current status and upcoming phases in /path/to/project/docs/roadmap.md.
• Online systems spec draft is in /path/to/project/docs/online-roadmap.md.

Documentation

• Installation guide: /path/to/project/docs/installation.md
• Homebrew distribution guide: /path/to/project/docs/homebrew.md
• Full game guide: /path/to/project/docs/game-manual.md
• Project roadmap: /path/to/project/docs/roadmap.md
• Online systems roadmap: /path/to/project/docs/online-roadmap.md
• Online local (no Docker) guide: /path/to/project/docs/online-local.md
• Online deployment guide: /path/to/project/docs/online-deploy.md