epoch_forge/README.md

139 lines
5.6 KiB
Markdown

# Epoch Forge
![coverage](badges/coverage.svg) ![version](badges/version.svg) ![tests](badges/test.svg)
Epoch Forge (`efo`) is an early-alpha command-line tool for managing a game's
world or organisation across a sequence of snapshots called **epochs**. It is
designed for people who are comfortable with Git-like concepts: inspect the
current state, advance it, compare it with history, and deliberately discard a
future timeline when needed.
The current release manages organisations, characters, towns, events,
calamities, and blockers with statistics and relationships. Repository format
1.0 provides worktree/index staging, immutable commits, restore, conflict-safe
revert, switching, and recoverable future pruning from initialisation. A separate
TUI searches entities across HEAD, staged, and working state, and offers
previewed entity creation/editing with one-step undo. Custom fields and TUI
staging/commit workflows remain planned. There is no GUI or web interface.
> Epoch Forge is not yet suitable as the only copy of important campaign data.
> Keep the repository in Git or make a directory backup before destructive
> operations. See [Safety and recovery](docs/repository.md#safety-and-recovery).
## Install
The project currently requires Rust 1.92 or newer:
```bash
git clone https://proxy.dandaedre.com/gitea/idle-org/epoch_forge.git
cd epoch_forge
cargo install --locked --path bin_efo
cargo install --locked --path tui_efo
```
Nerd Font icons are enabled by default. Build a portable-Unicode variant for
terminals without a Nerd Font with:
```bash
cargo install --locked --path bin_efo --no-default-features
```
## Quick start
Start in an empty directory. Epoch Forge stores `.epoch` and `epoch/` in the
current working directory.
```bash
mkdir my-world
cd my-world
efo init
efo chr add "Aria" --stats strength:12 food:8
efo town add "Durn" --position 12,5
efo status
efo chr show Aria
# Snapshot the current state as the next epoch.
efo epoch summary "The expedition begins"
efo epoch tag beginning
efo epoch next
# Compare an entity after editing it in epoch 1.
efo chr edit Aria --prestige-add 2
efo chr diff Aria --epoch-id beginning
efo epoch log
```
Run `efo --help`, `efo <command> --help`, or see the
[command reference](docs/commands.md) for the complete current interface.
## Capabilities
| Area | Available now | Not available yet |
|---|---|---|
| Repository | Initialise format 1.0; inspect; lock and recover transactional writes | Future 1.x migration tooling; discovery from child directories; integrity repair |
| Timeline | Commit, advance, switch, log, tag, summarise, diff, reviewable/committed revert, backed-up pruning, and explicit hard reset | Branching and merging |
| Entities | Add, edit, list, inspect, diff, and delete six built-in types | Custom types and custom fields; bulk operations |
| Generation and simulation | Generate deterministic seeded worlds; roads, travel, event diffusion/arrival resolution; record external rolls and adjudications; run multi-side fights and wars | Setting template packs and interpolated in-transit positions |
| Interfaces | Complete CLI; `efo-tui` browser and entity editor | TUI staging/commits; GUI/web (out of scope) |
`efo show all` gives a world overview; per-type commands such as
`efo chr show Aria` provide targeted or detailed inspection.
Run `efo-tui` in a repository root (or use `--repository PATH`). Press `/` to
search, `1`/`2`/`3` to browse HEAD/index/worktree, and `v` to toggle formatted
details and raw JSON. Use `a` to add to the current collection, `e` to edit,
`Ctrl-S` to preview, and `y` to save to the worktree. Press `u` to preview undo
of the last TUI save. Narrow terminals show one
focused panel; Tab cycles panels. Use `--no-color` for monochrome output and
`?` for the scrollable keyboard reference. No Nerd Font is required.
## Documentation
- [Documentation index](docs/README.md)
- [Commands](docs/commands.md)
- [Repository, persistence, and recovery](docs/repository.md)
- [Reversing changes](docs/recovery.md)
- [Architecture and development](docs/architecture.md)
- [TUI scope and keyboard guide](docs/tui-design.md)
- [Roadmap and proposed stretch goals](docs/roadmap.md)
- [Ready-to-use Draän example world](examples/ravenous-draan/README.md)
- [Contributor/agent rules](AGENTS.md) and [working task list](AGENTS-TASKS.md)
## Development
### Library example
`lib_efo` exposes repository initialization and the complete HEAD/index/worktree
model without going through the CLI. To create a repository in an existing
empty directory and inspect its initial epoch:
```bash
mkdir /tmp/epoch-forge-example
cargo run -p lib_efo --example repository -- /tmp/epoch-forge-example
```
See [`lib_efo/examples/repository.rs`](lib_efo/examples/repository.rs) for the
complete program. Mutations should use `Workspace` methods so they retain the
same transactional guarantees as `efo`.
```bash
cargo fmt --all -- --check
cargo test --workspace --all-targets --all-features --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
```
Tarpaulin and `rust_autobadges` are intentionally release-only. They do not run
in routine CI because of their cost; badge files are refreshed for significant
releases. The Tarpaulin configuration excludes the thin CLI adapters because
their subprocess integration tests cannot be attributed reliably by its ptrace
backend; library and TUI code remain directly measured.
## Release archives
The CLI package is `efo` in `bin_efo`. Release tags follow the Cargo version
(for example `v0.1.0`). Cross-built archives are named
`efo-{target}-v{version}.tgz` and are accompanied by `SHA256SUMS`.
Epoch Forge is licensed under the terms in [LICENSE](LICENSE).