# 📦 Epoch Forge (`epoch_forge`) – *early alpha*
  

> **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! ✨