epoch_forge/README.md

102 lines
3.7 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 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 <command> --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, delete future epochs | World diff; 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) |
Some commands in the 0.1.0 parser are known incomplete. `epoch diff`,
`epoch fsck`, and the top-level `show` command are being repaired and should not
be relied upon until their roadmap items are checked. The per-type commands,
such as `efo chr show`, are the supported way to inspect entities.
## 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).