13 KiB
Command reference
Epoch Forge operates on the current working directory; it does not yet search
parent directories. efo <command> --help is the authoritative syntax.
Repository and timeline
efo init [--force]creates the format-1.1 manifest, HEAD, index, worktree, andepoch/0/epochinfo.json. The normal form requires an empty directory;--forcepermits unrelated existing files but never overwrites.epochor epoch 0.efo recoverdeterministically rolls back a prepared replacement or verifies a committed one. It is safe to repeat.efo lock inspectreports writer ownership.efo lock break --yesremoves an abandoned lock only after explicit confirmation; runefo recovernext.efo status [EPOCH_ID]shows an epoch summary, tags, and entity counts.efo epoch log [-c N]shows epochs around the current epoch.efo epoch nextcreates and checks out the next snapshot. It refuses while later snapshots exist.efo epoch switch ID_OR_TAGchecks out an existing snapshot without deleting later ones.efo epoch summary TEXTandefo epoch tag TAGannotate the current epoch.efo epoch diff START [END]reports added, removed, and modified entities. A trailing!marks changes considered especially consequential (towns, events, calamities, or statistic/duration changes).ENDdefaults to the current epoch.efo epoch fsckperforms a read-only consistency check of epoch IDs, tags, and entity UUIDs. It does not repair damage.efo prune-futurepreviews later history;--yesmoves it to a restorable backup, removes tags into that future, and makes the next commit use the ID immediately after HEAD. Restoring the backup restores its allocator and tags.efo reset --hard ID_OR_TAGpreviews a destructive rewind. Add--yesto align HEAD, index, and worktree to the target and permanently delete every newer epoch. This has no built-in undo; preferswitchplusprune-futurewhen recovery may be needed.
Entities
The built-in nouns are org, chr, town, event, calamity, and blocker.
character aliases chr; organization and organisation alias org:
efo <noun> add [NAME | --rng-name] [OPTIONS]
efo <noun> edit <NAME|@UUID> [OPTIONS]
efo <noun> show [NAME|@UUID]
efo <noun> diff <NAME|@UUID> [--epoch-id ID_OR_TAG]
efo <noun> del <NAME|@UUID>
Names match by prefix. @UUID is the stable form printed in detailed output;
short UUID prefixes are accepted. Avoid ambiguous prefixes.
Common add/edit options include --stats key:value ..., --position x,y,
--duration, --bounds, --effect, faction/reach/description/relationship
options, and prestige controls. edit --delta adds supplied stats rather than
replacing them. See nested help (for example efo chr add --help) for exact
syntax and values. Persistent normalized stats are clamped to 0..=120;
growth and event/blocker modifiers use -120..=120; population remains an
unbounded non-negative count for persistent entities. Entity mutations edit
only the worktree. Use efo diff,
efo stage --all, efo stage --world, or
efo stage --kind KIND ID...,
and efo diff --staged to prepare history. efo restore --staged ... copies
HEAD into the index; efo restore --worktree ... copies the index into the
worktree. Both restore modes require either --all or an entity kind and IDs.
efo commit -m MESSAGE refuses unstaged or empty commits, creates an immutable
epoch using a manifest-last transaction, and realigns all three layers.
efo log shows the resulting parent-linked history newest first.
efo switch ID requires clean state and changes all layers without reusing
epoch IDs. efo revert ID applies that epoch's inverse to the worktree for
review; it can be undone with restore --worktree --all. revert ID --commit
prints a warning and immediately creates the inverse commit. Overlap with later
changes aborts without mutation. efo prune-future previews future epochs,
while --yes moves them into a backup. Restore using the exact command printed
after pruning; this also restores the former next-epoch allocator and tags.
After pruning, the next epoch allocator remains monotonic, so removed IDs are
not reused. efo reset --hard ID --yes is the explicitly destructive
alternative: it discards transient changes, removes newer epochs without a
backup, removes tags that point to them, and restarts the epoch allocator after
the retained target.
efo epoch summary and efo epoch tag edit worktree metadata;
stage --world selects it. efo epoch next requires a clean worktree, includes
already staged changes, advances entity time, and commits one new monotonic ID.
efo epoch fsck validates all state layers and every immutable epoch.
efo show defaults to every collection. show character, show town, show event, show calamity, show organization, and show blocker select one.
Filter with --name TEXT, --text TEXT, or --position X,Y; select a
committed snapshot with --epoch ID_OR_TAG. --detail short|long|full
controls output density. efo show epoch lists committed epoch summaries and
accepts the same --epoch and detail options. Use <noun> show IDENTIFIER for
the complete details of one entity by its name or stable ID.
Roads and travel
Spatial changes are preview-first and affect only the worktree with --apply:
efo travel road-add Haven Northwatch --speed 180
efo travel road-add Haven Northwatch --speed 180 --apply
efo travel roads
efo travel plan Aria Northwatch --offroad-speed 50
efo travel plan Aria Northwatch --offroad-speed 50 --apply
efo travel tick 3 --apply
Routing minimizes integer travel ticks with deterministic tie-breaking. Roads
carry their own speed; disconnected characters fall back to slower direct
travel. Characters have explicit resident, roaming, or travelling state. Use
efo restore --worktree --all to discard applied simulation changes.
Epoch-wide resolution semantics
adjudicate/influx, diffuse resolve, and conflict advance/fight/war
share the worktree snapshot frozen by the first applied resolution after each
commit. Each ruling reads those target stats and source potency, clamps its own
result, and contributes local result - epoch base. The aggregate adds that
sum to the base once and clamps again. Preview prints both the independent
ruling and the actual combined epoch totals. For health 110, +20 and -20 yield
100 in either order (contributions +10 and -20).
Apply rulings in any order once their explicit arrivals/rounds are ready.
efo stage --all followed by efo commit -m ... or efo epoch next ends the
interval; later rulings read the combined result. Conflict lifecycle, travel,
and diffusion scheduling still advance explicitly. Destroying a source stops
its own frontier immediately, but cannot erase already admitted same-epoch
stat contributions. In-transit/resident selection for arrival resolution uses
the frozen snapshot. Create entities and set up topology before the first
resolution, or commit before resolving newly created targets/sources.
An identical adjudication in the same epoch is rejected as already recorded.
Use --occurrence NUMBER on adjudicate preview/apply for a deliberate repeated
ruling; keep the number stable when retrying. A new epoch automatically gives
the same ruling a distinct identity. A duplicate error never reapplies effects.
Epoch Forge still does not roll dice or reinterpret external results.
Use efo restore --worktree --all to discard a resolution or efo revert for
committed history. Partial stage/restore cannot split its statistics and audit.
Commit before manually editing statistics already participating in the interval.
Applying refuses stale repository state; rerun the command for a fresh preview.
See deterministic execution and
format compatibility.
Event diffusion
Events propagate from their map position over the same topology. Roads use their configured speed and direct spatial propagation remains a slower fallback:
efo diffuse start Plague --road-speed 100 --direct-speed 25 --expires-after 20
efo diffuse start Plague --road-speed 100 --direct-speed 25 --expires-after 20 --apply
efo diffuse tick 3
efo diffuse tick 3 --apply
efo diffuse resolve Plague Haven --level good --characters residents
efo diffuse resolve Plague Haven --level good --characters residents --apply
The preview reports each destination's arrival tick and whether it is reached by road or directly. Persisted frontiers retain an affected set, so applying or previewing the same tick again cannot reach a town twice. Expired state remains inspectable and can be restored, staged, or committed like any other worktree change.
Applied ticks leave newly reached towns pending until the game master resolves
them. diffuse resolve shows colocated or linked blockers as protection
context, then previews the town and characters selected by --characters none|residents|positioned|both. Protection never silently chooses an outcome:
use --disposition applied|dampened|avoided|destroyed. Avoided targets are
still recorded and cannot be resolved twice. Travelling characters are
conservatively excluded because interpolated route positions are not yet
stored. One --apply writes all target effects and resolution records
atomically; normal worktree restore undoes the batch.
External rolls and game-master adjudication
Epoch Forge does not roll or infer an outcome. The player rolls outside the tool, then the game master records the result, interpretation, disposition, and exact stat effects:
efo adjudicate preview Plague --target town:Haven --level bad \
--result "d20=4" --disposition dampened --effect health:-8
efo adjudicate apply Plague --target town:Haven --level bad \
--result "d20=4" --disposition dampened --effect health:-8
efo adjudicate list Plague
For the common case, omit result, disposition, and effects:
efo adjudicate apply Plague --target town:Haven --level bad
This uses the configured default effects. The embedded policy progressively
dampens its health:-20 baseline: excellent 0%, good 25%, mid 50%, bad 75%,
worsen 90%, and apocalypse 100%. An external --config can replace both the
baseline and scale. Supplying one or more --effect options replaces the
defaults completely.
influx is a visible alias for adjudicate. applied uses the supplied
effects in full, dampened applies the configured attenuation, and avoided
or destroyed records zero stat change. Applied rulings are audit records in
the worktree. Use efo restore --worktree --all to undo the ruling and its
effects together; audit records cannot be cleared independently from effects.
Each ruling also marks the source event with remaining potency. Later default
effects are multiplied by that percentage. A destroyed event has 0% potency,
stops an active frontier, and cannot start another diffusion; restore or revert
the ruling to recover it. efo adjudicate list EVENT displays this state.
Fights and wars
Conflicts are generic multi-side records whose participants remain ordinary entities. Start is preview-first:
efo conflict start "Bridge War" --kind war \
--side red:town:Haven --side blue:org:Guild:2
efo conflict start "Bridge War" --kind war \
--side red:town:Haven --side blue:org:Guild:2 --apply
Advance one round with exactly one external adjudication per active side:
efo conflict advance "Bridge War" \
--side-outcome red:good:applied \
--side-outcome blue:bad:dampened \
--result "players rolled 11 and 4" [--apply]
fight and war are visible aliases for conflict. Outcomes reuse the same
levels, dispositions, progressive defaults, and explicit --effect overrides.
destroyed removes a participant from this conflict but never deletes its
entity. A fight stalemates after one unresolved round; a war stays active until
one side remains. Use conflict show, conflict list, or
conflict end --reason ... [--apply]. Every mutation affects only the
worktree and supports restore, stage, commit, and historical revert.
Generation and output
efo gen character|town|event|exotic|calamity|blocker prints generated content
without creating or changing repository files.
efo gen world --level event|settlement|region|world --seed N previews a
deterministic generated world using embedded configuration. --config PATH
selects an editable JSON override. --apply explicitly replaces only the
worktree; undo it with efo restore --worktree --all, or stage and commit it
through the ordinary workflow.
Output is human-readable Unicode, with Nerd Font icons enabled by default. A
portable build replaces those icons with textual/standard-Unicode labels; use
cargo install --path bin_efo --no-default-features. Stable JSON output is
planned. A panic is always a bug.