A Rust‑powered CLI for managing fantasy organisations across time
Go to file
Dandaedre 199d2eccf7
Build Successful The build was successful
Gitea/epoch_forge/pipeline/head This commit looks good Details
Fixed updated tests
2025-12-15 03:44:28 +01:00
badges Adds more testing updates coverage 2025-12-14 05:17:43 +01:00
bin_efo Slop cleanup 2025-12-15 03:41:56 +01:00
lib_efo Fixed updated tests 2025-12-15 03:44:28 +01:00
.gitignore Fixes show and add 2025-12-12 17:22:04 +01:00
.ignore Adds boc/user doc 2025-12-13 20:21:47 +01:00
.run_status.toml Adds more testing updates coverage 2025-12-14 05:17:43 +01:00
.rust-toolchain.toml Investigating CI 2025-12-12 19:44:16 +01:00
Cargo.lock Adds more testing updates coverage 2025-12-14 05:17:43 +01:00
Cargo.toml Random add & update position 2025-12-14 18:46:58 +01:00
Jenkinsfile Adds documentation, updates the CI 2025-12-13 19:49:21 +01:00
LICENSE Deslop 2025-11-30 18:26:06 +01:00
README.md Adds documentation, updates the CI 2025-12-13 19:49:21 +01:00

README.md

📦 Epoch Forge (epoch_forge) – early alpha

code coverage version code coverage

📚 Online Documentation

A Rust-powered CLI for managing fantasy organisations across time.
Think of it as a living, breathing world-state engine that lets you “rewind”, “fast-forward”, and alter the history of guilds, towns, wars, and characters.

Epoch Forge is a Rust‑powered command‑line tool that lets you build and manipulate a living fantasy world.
It is in early alpha – the API is subject to change, some features are missing, and stability is not guaranteed.

Stats & analytics are not yet implemented – most commands operate only on the raw data model.

✨ Quick start

# Clone the repository
git clone https://github.com/yourname/epoch_forge.git
cd epoch_forge

# Build & install the binary
cargo install --path .

# Initialise an empty world (epoch 0)
efo init

# Add an organisation
efo org add "The Iron Horde"

# Add a town
efo town add "Durn" --stat pop:32

# Inspect the current world state
efo show > world.json
cat world.json

# Show the epoch timeline
efo epoch log

# Create the next scheduled epoch
efo epoch next

# Switch back to epoch 5 (if it exists)
efo epoch switch 5

# Tag the current epoch
efo epoch tag milestone1

# Add a short-lived event
efo event add "Storm" \
  --duration Duration(1) \
  --effect permanent-effect-to-apply \
  --stats damage=20

Tip: The show command can print JSON, which you can pipe to jq or any other tooling.

🏆 Project Highlights

Feature Description Where to find it
Epoch management Switch, advance, or rewind the global timeline core::epoch
Persistence JSON/YAML stores, pluggable back-ends core::epoch
Event handling Add/remove world-shaping events (storms, festivals, wars) core::entities
Organisation CRUD Guilds, factions, corporations core::entities
Character CRUD Heroes, villains, NPCs core::entities
Town CRUD Villages, cities, trade hubs core::entities
Link network Alliances, wars, roads, trade routes core::link
CLI efo binary with sub-commands efo crate

Statistics, analytics, and the act feature are still a work in progress.

Unimplemented / WIP

Feature Status Where it lives
Act Planned, not yet implemented core::act
Stats Missing – no aggregated data –

Quick reference table

Sub‑command Usage example What it changes
init efo init
efo init --force
Creates an empty epoch repository (epoch 0) in the current directory.
epoch log efo epoch log --limit 20 Prints a chronological list of epochs up to the current one.
epoch switch efo epoch switch 5 Sets the current epoch to the specified <id> (must already exist).
epoch next efo epoch next Generates the next scheduled epoch and inserts it.
epoch reset efo epoch reset Deletes all epochs with an identifier greater than the current one.
epoch diff efo epoch diff 2 4 Unimplemented – placeholder for future diffing logic.
epoch tag efo epoch tag milestone1 Adds a unique tag to the current epoch, updating the global tag map.
epoch fsck efo epoch fsck Unimplemented – intended to run a consistency check.
epoch summary efo epoch summary "Reached the new frontier" Replaces the summary field of the current epoch with <text>.
show efo show Prints the current world state (JSON).
gen efo gen character -n 5 --short
efo gen town -n 2
efo gen event -n 3 --name
Prints generated names/ideas; useful for scripting.
chr add efo chr add "Aria" --pos 5,12 --stats strength=12 agility=9 Creates a new entity (character, town, event, etc.) and writes the epoch.
chr del efo chr del "Aria" Removes the matching entity from the epoch.
chr edit efo chr edit "Storm" --duration Duration(2) Modifies an existing entity’s stats, position, duration, etc.
chr find efo chr find "Aria" Prints full details of a single entity.
chr show efo chr show Lists all entities, or efo chr show "Aria" shows one in full detail.
chr diff efo chr diff "Aria" Prints the difference between the current and previous epoch for that entity.
event add / event remove efo event add ...
efo event remove ...
Adds or removes an event.
org add / org remove efo org add ...
efo org remove ...
Manages organisations (guilds, factions).
town add / town remove efo town add ...
efo town remove ...
CRUD for towns.
monster add / monster remove efo monster add ...
efo monster remove ...
CRUD for monsters.
act Not yet implemented Planned for future action handling.

All changes are persisted immediately to the epoch file after the command finishes.

Contributions & Feedback

Because the project is in early alpha, any feedback, bug reports, or pull requests are welcome.
Please remember that stability is not guaranteed, so use it in a versionned environnement.

Happy forging! ✨