A Rust‑powered CLI for managing fantasy organisations across time
Go to file
Dandaedre 79ce7f84d3
Rust CI Epoch Forge passed all CI checks.
Gitea/epoch_forge/pipeline/head This commit looks good Details
feat: add deterministic configured world generation
2026-09-21 02:17:44 +02:00
badges Adds a build, stops work 2025-12-16 20:58:14 +01:00
bin_efo feat: add deterministic configured world generation 2026-09-21 02:17:44 +02:00
docs feat: add deterministic configured world generation 2026-09-21 02:17:44 +02:00
lib_efo feat: add deterministic configured world generation 2026-09-21 02:17:44 +02:00
scripts feat: add deterministic configured world generation 2026-09-21 02:17:44 +02:00
tui_efo refactor: make reversible format the initial layout 2026-09-21 02:10:24 +02:00
.gitignore Prepare efo 0.1.0 cross-platform binary release 2026-09-13 20:15:24 +02:00
.ignore Adds a build, stops work 2025-12-16 20:58:14 +01:00
.run_status.toml Adds a build, stops work 2025-12-16 20:58:14 +01:00
.rust-toolchain.toml Investigating CI 2025-12-12 19:44:16 +01:00
AGENTS-TASKS.md feat: add deterministic configured world generation 2026-09-21 02:17:44 +02:00
AGENTS.md docs: establish project guardrails and delivery plan 2026-09-20 20:47:41 +02:00
Cargo.lock feat: add deterministic configured world generation 2026-09-21 02:17:44 +02:00
Cargo.toml feat: add read-only repository tui 2026-09-21 01:25:25 +02:00
Cross.toml Prepare efo 0.1.0 cross-platform binary release 2026-09-13 20:15:24 +02:00
Jenkinsfile Update Jenkinsfile 2026-09-13 13:12:01 +02:00
LICENSE Deslop 2025-11-30 18:26:06 +01:00
README.md feat: add deterministic configured world generation 2026-09-21 02:17:44 +02:00

README.md

Epoch Forge

coverage version tests

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

Development

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.