Dungeon

Dungeon is an early-stage 2D dungeon crawler built around a deterministic game state machine. The goal is to make gameplay reproducible, inspectable, and provable while keeping the core game loop local and fast.

Workspace

crates/game/core        Deterministic game rules and state transitions
crates/game/content     Data-backed game content loaders
crates/runtime          Runtime orchestration, workers, persistence, proving
crates/client           Client composition root and binary
crates/client/bootstrap Runtime setup helpers for frontends
crates/client/frontend  CLI and shared frontend model
crates/zk               RISC0, SP1, and stub proving backends
crates/xtask            Local inspection and maintenance tools

Design Principles

• Keep gameplay deterministic. Any randomness must be explicit input to the state transition and proof flow.
• Keep game-core stateless and data-oriented. Runtime workers provide I/O, persistence, and orchestration around it.
• Generate local proof artifacts first: action logs, checkpoints, journals, roots, and proof files.
• Keep external verification adapters separate from the main development line.

Requirements

• Rust toolchain with Rust 2024 support
• just for convenience commands

Install just if needed:

cargo install just

Quick Start

Fast local build and test with the stub prover:

just build stub cli
just test stub cli
just run-fast stub

Run with persistence and proving enabled through environment configuration:

ENABLE_PERSISTENCE=true ENABLE_ZK_PROVING=true just run stub cli

ZK Backends

Dungeon currently exposes these backend features:

Feature	Purpose
stub	Instant local prover for development and tests
risc0	RISC0 zkVM proving
sp1	SP1 zkVM proving
arkworks	Placeholder for future custom circuits

Use exactly one backend feature at a time:

cargo check --workspace --no-default-features --features stub,cli
cargo test --workspace --no-default-features --features stub,cli

Local Artifacts

When persistence is enabled, sessions contain:

• session_init.json with oracle root, seed commitment, and initial state root
• checkpointed state files
• action logs grouped into batches
• proof files generated for completed batches

The CLI save menu shows checkpoint and proof lifecycle status:

InProgress -> Complete -> Proving -> Proven -> Failed

Tools

cargo run -p xtask -- inspect-proof <proof-file>
cargo run -p xtask -- read-state <nonce>
cargo run -p xtask -- read-actions
cargo run -p xtask -- tail-logs
cargo run -p xtask -- clean --logs

Verification Before Changes

Run the focused local workflow before submitting changes:

cargo fmt --check
cargo clippy --workspace --all-targets --no-default-features --features stub,cli
cargo test --workspace --no-default-features --features stub,cli

For convenience:

just check stub