# 📦 Epoch Forge (`epoch_forge`) – *early alpha* ![code coverage](badges/coverage.svg) ![version](badges/version.svg) ![code coverage](badges/test.svg) ![📚 Online Documentation](https://books.dandaedre.com/rust_doc/efo/bin_efo/index.html) > **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 ```bash # 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 `` (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 ``. | | **`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! ✨