epoch_forge/README.md

116 lines
5.5 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 📦 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`<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! ✨