139 lines
5.6 KiB
Markdown
139 lines
5.6 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. 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).
|