# 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 characters, towns, events, calamities, and blockers with statistics and relationships. Organisation-agnostic custom fields, pseudo-staging, complete restore/revert workflows, and a TUI are planned—not implemented. 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 ``` ## 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 --help`, or see the [command reference](docs/commands.md) for the complete current interface. ## Capabilities | Area | Available now | Not available yet | |---|---|---| | Repository | Initialise in the current directory; inspect status | Discovery from child directories; locking; migrations | | Timeline | Advance, switch, log, tag, summarise, diff, check integrity, delete future epochs | Integrity repair; branching; atomic restore/revert | | Entities | Add, edit, list, inspect, diff, and delete five built-in types | Organisations; custom types and custom fields; bulk operations | | Generation | Generate character, town, event, calamity, blocker, and exotic names | Deterministic seed controls and template packs | | Interfaces | CLI | TUI (possible stretch goal); 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. ## Documentation - [Documentation index](docs/README.md) - [Commands](docs/commands.md) - [Repository, persistence, and recovery](docs/repository.md) - [Architecture and development](docs/architecture.md) - [Roadmap and proposed stretch goals](docs/roadmap.md) - [Contributor/agent rules](AGENTS.md) and [working task list](AGENTS-TASKS.md) ## Development ```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. ## 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).