5.1 KiB
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 read-only TUI browses repository status and entities. Custom fields and TUI write 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.
Install
The project currently requires Rust 1.92 or newer:
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:
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.
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 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, restore, revert, and backed-up future pruning | Branching and merging |
| Entities | Add, edit, list, inspect, diff, and delete six built-in types | Custom types and custom fields; bulk operations |
| Generation | Generate names and deterministic seeded events, settlements, regions, or worlds from embedded/override configuration | Roads, diffusion, and setting template packs |
| Interfaces | Complete CLI; read-only efo-tui repository browser |
TUI write workflows; 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. The TUI
uses ordinary Unicode and text labels, so no meaning depends on Nerd Font
glyphs. Press ? for its complete keyboard reference.
Documentation
- Documentation index
- Commands
- Repository, persistence, and recovery
- Reversing changes
- Architecture and development
- TUI scope and keyboard guide
- Roadmap and proposed stretch goals
- Ready-to-use Draän example world
- Contributor/agent rules and working task list
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:
mkdir /tmp/epoch-forge-example
cargo run -p lib_efo --example repository -- /tmp/epoch-forge-example
See lib_efo/examples/repository.rs for the
complete program. Mutations should use Workspace methods so they retain the
same transactional guarantees as efo.
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.