108 lines
3.8 KiB
Markdown
108 lines
3.8 KiB
Markdown
# Epoch Forge
|
|
|
|
  
|
|
|
|
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. 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
|
|
```
|
|
|
|
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; inspect status; preview/apply backed-up format migration | Discovery from child directories; locking; automated migration rollback |
|
|
| 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 six built-in types | 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)
|
|
- [Reversing changes](docs/recovery.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).
|