116 lines
5.5 KiB
Markdown
116 lines
5.5 KiB
Markdown
# 📦 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`<br>`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`<br>`efo gen town -n 2`<br>`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 ...`<br>`efo event remove ...` | Adds or removes an event. |
|
||
| **`org add` / `org remove`** | `efo org add ...`<br>`efo org remove ...` | Manages organisations (guilds, factions). |
|
||
| **`town add` / `town remove`** | `efo town add ...`<br>`efo town remove ...` | CRUD for towns. |
|
||
| **`monster add` / `monster remove`** | `efo monster add ...`<br>`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! ✨
|
||
|