# STORY — SCICRAFT: The Dark Photon Protocol

**This folder is the single source of truth for the pack's story.**
Every piece of player-facing text in the game comes from here.

## How editing works

1. Edit prose and text in `STORY/*.md`.
2. Run the generator:
   ```bash
   python tools/gen_story.py
   ```
3. It merges every ````lang` JSON block into `en_us.json` in **both** packs
   and fails if any referenced lang key is missing.
4. Reload in-game: `/reload` for server text, `F3+T` for client text.

> **Golden rule:** never hand-edit `en_us.json` and never hardcode a story
> string inside a `.js` script. Text lives here (or in the `STORY/*.md`
> prose); scripts only reference lang keys.

## File map

| File | What lives here | Game artifact |
|------|-----------------|---------------|
| `00-index.md` | This index + the editing workflow + verified IDs | — |
| `01-canon.md` | The canon, in one page (the actual story) | — |
| `02-items.md` | Item/block names, hover tooltips, JEI pages | `item.*`, `block.*`, `tooltip.*`, `jei.*` |
| `03-dimensions.md` | Dimension lore + verified dimension IDs | — |
| `04-phases.md` | The advancement phase tree (titles + descriptions) | `advancements.scicraft.protocol.*` |
| `05-dialogue.md` | Player messages: tide warnings, signals, lattice hum | `scicraft.phrases.*` |
| `06-loot.md` | Who drops what, and why | `04_loot.js` (LootJS) |
| `07-todo.md` | Future story beats (drop in whenever) | — |

## The phase tree (non-terminal — the Protocol is maintained)

1. `root` — The Dark Photon Protocol (on login)
2. `first_signal` — recover a Photon Fragment
3. `the_core` — press 3 fragments → Photon Core
4. `the_seal` — craft the Void Stabilizer
5. `the_lattice` — assemble the Quantum Lattice
6. `the_legacy` — craft Renegade Glass
7. `through_the_doors` — enter Dimensional Doors Limbo
8. `the_wound` / `the_answer` / `per_spatium` — Void, Deeper&Darker, Stellaris

## Adding a new story beat (5-minute workflow)

1. **Write the prose** in the right `STORY/*.md` file (canon → `01-canon.md`,
   item → `02-items.md`, message → `05-dialogue.md`, goal → `04-phases.md`).
2. **Add the lang keys** to that file's ````lang` block.
3. **If it's a new item/block**: add to `kubejs/startup_scripts/registry_blocks.js`
   + run `tools/gen_textures.py` for a placeholder texture. **Restart** to apply.
4. **Wire the beat** into a script (tide → `01_corruption_tide.js`,
   powers → `02_events.js`, craft → `03_recipes_tags.js`, drop → `04_loot.js`).
   Use `Text.translate('key')` — never a raw string.
5. Run `python tools/gen_story.py`, then sync:
   ```bash
   bash tools/sync_kubejs.sh
   ```
6. Reload: `/reload` (server) or `F3+T` (client). Startup items need a restart.

## Verified IDs (do not guess these — they were checked against the jars)

| Thing | Correct ID |
|---|---|
| Limbo (Dimensional Doors) | `dimensionaldoors:limbo` |
| The Wound (Void Dimension) | `thevoiddimension:overworld` |
| The Othersides (Deeper & Darker) | `deeperdarker:otherside` |
| Stellaris moon | `stellaris:moon` (mars/venus/mercury likewise) |
| Warden | `minecraft:warden` |
| Mutant Zombie / Skeleton / Enderman | `mutantmonsters:mutant_zombie` / `mutant_skeleton` / `mutant_enderman` |
| Born in Chaos Dark Vortex / Dread Hound / Nightmare Stalker | `born_in_chaos_v1:dark_vortex` / `dread_hound` / `nightmare_stalker` |

When in doubt, verify against the installed jar before writing an ID into a script.