Phase 8: the quest book, generated from docs/quests.yaml

- tools/quests.py writes pack/config/ftbquests/quests/ in FTB Quests 2101's
  format (data.snbt, chapters/*.snbt, texts in lang/en_us.snbt) with ids
  derived from the YAML names, so progress survives regeneration. Flexible
  progression, no lock icons, no rewards (Adrian, 2026-11-03). tools/build.py
  runs it.
- docs/quests.yaml: 18 chapters, 74 quests. Getting Started; one chapter per
  zone and the End from a zone template (reach it, catch three of its
  Pokemon, mine its ores, beat its guardian) plus chapter extras (Mire
  Waders, Eyes of Ender, Eternatus); Pokemon Machines; Base and Jobs.
- Node positions: --pull reads them from an FTB Quests folder into the
  layout block (only moved nodes); tools/prism_instance.py pulls from the
  instance before each sync and rebuilds if something moved.
- The pack's own events as hidden advancements (cobblesurvival:events/...),
  granted by QuestEvents: zone reached, guardian beaten, machine filled, End
  boss beaten.
- Self-tests quest_book_loads and quest_events_mark_zones; the guardian and
  furnace tests check their events. Self-tests and island check pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/checklists/phase-8.md

@@ -8,11 +8,18 @@
 
 - **Add-ons in the pack:** Cobblemon Quests Reloaded 2.0.2 (Cobblemon task type for FTB Quests) and Cobblemon Info for REI / JEI / EMI 2.32.14. Automated: `quests_have_cobblemon_tasks`, `jei_addon_shows_island_spawns`.
 - **Spawn info in JEI:** right for the pack (species, levels, rarity come from the zone pools), but it shows biomes, not zones; our own pages will add the zone.
+- **Quest book:** 18 chapters, 74 quests, generated from `docs/quests.yaml`: Getting Started, one chapter per zone and the End, Pokémon Machines, Base and Jobs. No rewards, nothing locked. Zone chapters: reach the zone, catch three of its Pokémon, mine its ores, beat its guardian. Automated: `quest_book_loads`, `quest_events_mark_zones` (and the guardian and furnace tests check their quest events).
 
 ## In game (Prism instance)
 
 - [ ] Open JEI, look up a Pokémon (e.g. Pikachu) in Cobblemon Info's pages: the spawn levels match its zone (`docs/zone-species.md`), and its drops are listed.
 
+- [ ] Open the quest book (FTB Quests' book item, or its key): every chapter shows, nodes are joined by lines, none shows a lock.
+- [ ] Getting Started: tick "Welcome to the Island"; catch a Pokémon: "A Partner" completes.
+- [ ] Soft-lock check: get 16 Poké Balls before ticking "Welcome to the Island", then tick it: "Poké Balls" completes too (if it stays stuck, tell me: there's a known flexible-mode bug in older FTB Quests).
+- [ ] Walk into Southwold: "Southwold" in its chapter and "Beyond Button Isle" complete.
+- [ ] Move a few nodes in the editor (`/ftbquests editing_mode`), close the game, run `tools/prism_instance.py`: your positions stay, and `docs/quests.yaml` has them in its `layout` block.
+
 ## Ask Adrian
 
 - (after the first chapters) Does the layout read well? Move nodes freely in the editor; the next generation keeps your positions.

docs/design.md

@@ -304,11 +304,14 @@ Adrian's choices: Cobblemon tasks come from **Cobblemon Quests Reloaded** (a mai
 
 **Add-ons checked** (2026-11-03). Quests Reloaded declares Cobblemon 1.8+ and FTB Quests 2101+, boots with the pack and adds the task type `cobblemon_tasks:cobblemon_task` (catch, defeat, evolve into, level up, obtain, seen, and more; filters by species, type, form, shiny, level, biome). Cobblemon Info reads the server's live spawn pool, so what it shows is the pack's own zone pools: right species, levels and rarity; the self-test compares every entry. It does not know the pack's zone rule and lists a spawn's biomes instead: a Southwold Pokémon reads as "plains", though it only spawns in Southwold's plains. Our own JEI pages add the zone. It must be on the server too (it is, side both): a client on a server without it falls back to Cobblemon's unmodified spawn files.
 
-**Plan** (in progress):
-- `docs/quests.yaml` → `tools/quests.py` → `pack/config/ftbquests/quests/` (FTB Quests 2101 format: `data.snbt`, `chapter_groups.snbt`, `chapters/*.snbt`, texts in `lang/en_us.snbt`). Quest ids are derived from the YAML ids, so they stay the same across regenerations and players keep their progress. `tools/quests.py --pull <instance>` reads node positions back from an instance's quest files first.
-- Flexible progression everywhere and no lock icons, so dependencies show as lines but never block; check FTB Quests 2101.1.37 for the soft-lock a fix mod reports for 1.20.1.
-- Chapters: getting started, one per zone, base building and Pokémon jobs, machines, bosses and the End. Tasks: Cobblemon tasks (Quests Reloaded), items (drops, materials), and the pack's own events (zone reached, guardian beaten, machine built) as hidden advancements the companion mod grants.
-- JEI: our plugin adds, per item, every place on the island it comes from that Cobblemon Info doesn't cover: guardian and End boss rewards, Sacrifice Altar tiers, ore veins by zone, pasture mining and finder tables by zone; and per Pokémon its zone.
+**The quest book** is written in `docs/quests.yaml` and generated by `tools/quests.py` (run by `tools/build.py`) into `pack/config/ftbquests/quests/` in FTB Quests 2101's format (`data.snbt`, `chapter_groups.snbt`, `chapters/*.snbt`, every title and text in `lang/en_us.snbt`). Chapter, quest and task ids are derived from their names in the YAML, so they stay the same across regenerations and players keep their progress. The whole book is in flexible progression with lock icons off: dependencies show as lines but never block. No rewards.
+
+- **Chapters** (18, 74 quests on 2026-11-03): Getting Started (welcome, first catch, Poké Balls, a full team, the Revival Charm and permadeath, healing, level 10, drops and JEI, evolution, on to Southwold); one per zone and the End; Pokémon Machines (how to build one, then each of the five); Base and Jobs (Pasture Block, PC). A zone chapter (`zone: <id>`) starts with the template quests `zone_chapter`, filled from the zone's data: reach it (levels, hazard), catch three of its Pokémon (any species of its spawn pool), mine its ores (one item task per vein), beat its guardian (species, level, drops, the boss bar). Chapters add their own quests (Mire Waders for the Mire; Eyes of Ender and Eternatus for the End).
+- **Tasks:** Cobblemon actions through Quests Reloaded (catch, defeat, evolve, level up), items, and the pack's own events: hidden advancements `cobblesurvival:events/zone/<zone>`, `guardian/<zone>`, `machine/<core>` and `end_boss` (no display, no toast; written by `tools/quests.py`), granted by the companion mod (`QuestEvents`: a player's zone once a second, a guardian's battle winners, a machine's owner when a Pokémon goes in, the End boss's winners). They unlock nothing.
+- **Node positions:** Adrian moves nodes in the in-game editor; `tools/quests.py --pull <folder>` records every node that isn't where the generator would put it in the `layout` block at the end of `docs/quests.yaml`. `tools/prism_instance.py` does that from the instance before each sync, and rebuilds if something moved, so a sync never undoes his layout (docs/quests.yaml then needs committing). Titles, texts, tasks and dependencies edited in game are overwritten.
+- **Self-tests:** `quest_book_loads` (FTB Quests on the server has the book in flexible mode, every task type is known, every item and advancement exists), `quest_events_mark_zones`, and the guardian and furnace tests check their events.
+- Still open: the flexible-mode soft-lock a fix mod reports for 1.20.1 (tasks done before their dependencies); checked in game for now.
+- JEI (next): our plugin adds, per item, every place on the island it comes from that Cobblemon Info doesn't cover: guardian and End boss rewards, Sacrifice Altar tiers, ore veins by zone, pasture mining and finder tables by zone; and per Pokémon its zone.
 
 ## Open decisions for Adrian (proceeding with the default, flagged)
 

docs/quests.yaml

@@ -0,0 +1,366 @@
+# The quest book (roadmap Phase 8). tools/quests.py turns this file into pack/config/ftbquests/quests/.
+#
+# Adrian, 2026-11-03: quests give no rewards; they point the way and never block (flexible progression, no lock
+# icons). Titles, texts, tasks and dependencies live only here: edits to them in game are overwritten. Node
+# positions are different: move nodes in the in-game editor, then `tools/quests.py --pull <instance quests folder>`
+# (tools/prism_instance.py does it before each sync) copies them into the `layout` block at the end of this file.
+#
+# A chapter lists quests: id (unique in its chapter), title, optional subtitle, text (blank line = new paragraph),
+# icon, after (quests it builds on: an id in the chapter, or chapter/id), and tasks, each one of:
+#   item: <item id>, count: <n>             have the item
+#   cobblemon: catch|defeat|evolve|level_up_to|..., amount: <n>, optional pokemon: [ids], types: [types],
+#              zone_species: <zone>         a Cobblemon action (Cobblemon Quests Reloaded); zone_species = any
+#                                           Pokémon of that zone's spawn pool
+#   event: zone/<zone> | guardian/<zone> | machine/<core> | end_boss   the pack's own events (hidden advancements)
+#   checkmark: true                         the player ticks it
+# A task may also have a title. A chapter with `zone: <id>` starts with the quests of `zone_chapter`, where
+# {zone}, {low}, {high}, {hazard_text}, {guardian}, {guardian_level}, {drops} and {ore_names} come from the
+# zone's data; a template quest with `when:` is left out of zones that lack the thing named.
+
+book:
+  title: Cobblemon Survival
+  icon: cobblemon:poke_ball
+
+# What each zone's ore veins give when mined (pack/config/regenerating_ore_veins/veins.json).
+ore_items:
+  coal_node: minecraft:coal
+  copper_node: minecraft:raw_copper
+  iron_node: minecraft:raw_iron
+  redstone_node: minecraft:redstone
+  lapis_node: minecraft:lapis_lazuli
+  gold_node: minecraft:raw_gold
+  emerald_node: minecraft:emerald
+  amethyst_node: minecraft:amethyst_shard
+  diamond_node: minecraft:diamond
+  quartz_node: minecraft:quartz
+  netherite_node: minecraft:ancient_debris
+  thunder_stone_node: cobblemon:thunder_stone
+  shiny_stone_node: cobblemon:shiny_stone
+  leaf_stone_node: cobblemon:leaf_stone
+  water_stone_node: cobblemon:water_stone
+  moon_stone_node: cobblemon:moon_stone
+  sun_stone_node: cobblemon:sun_stone
+  fire_stone_node: cobblemon:fire_stone
+  ice_stone_node: cobblemon:ice_stone
+  dawn_stone_node: cobblemon:dawn_stone
+  dusk_stone_node: cobblemon:dusk_stone
+
+zone_chapter:
+  - id: arrive
+    title: "{zone}"
+    subtitle: "Lv {low}–{high}"
+    icon: minecraft:filled_map
+    text: |
+      Wild Pokémon in {zone} are level {low} to {high}. Bring a team that can hold its own there. {hazard_text}
+      A Pokémon far above a zone's levels learns less from battles there; Exp. Candy always works in full.
+    tasks:
+      - event: "zone/{zone_id}"
+        title: "Reach {zone}"
+  - id: locals
+    when: [species]
+    title: "Locals of {zone}"
+    icon: cobblemon:poke_ball
+    after: [arrive]
+    text: |
+      Each kind of Pokémon lives in one zone of the island. Catch three that call {zone} home.
+      Their drops are what this zone adds to your crafting: look an item up in JEI to see who drops it.
+    tasks:
+      - cobblemon: catch
+        zone_species: "{zone_id}"
+        amount: 3
+  - id: ores
+    when: [ores]
+    title: "Ores of {zone}"
+    icon: minecraft:iron_pickaxe
+    after: [arrive]
+    text: |
+      There is no ore anywhere except in each zone's own veins, and they grow back after you mine them.
+      {zone} has {ore_names}.
+    tasks:
+      - each: ores
+        count: 8
+  - id: guardian
+    when: [guardian]
+    title: "Guardian of {zone}"
+    icon: minecraft:netherite_sword
+    after: [locals]
+    text: |
+      {guardian}, Lv {guardian_level}, guards {zone}: a giant that takes at most a quarter of its health from any one attack.
+      Within 128 blocks its bar shows how far away it is. In the fight, watch the ground and step out of its area attacks; leaving the arena or dying loses the fight.
+      Beat it for {drops}. It returns 5 hours later.
+    tasks:
+      - event: "guardian/{zone_id}"
+        title: "Beat {guardian}"
+
+chapters:
+  - id: getting_started
+    title: Getting Started
+    subtitle: The island, your first partner, and the rules that matter
+    icon: cobblemon:poke_ball
+    quests:
+      - id: welcome
+        title: Welcome to the Island
+        icon: minecraft:filled_map
+        size: 1.5
+        text: |
+          This island has no zombies, no creepers and no cows: only Pokémon. Their drops are your food, string, leather and much more.
+          The island is split into zones, each with its own Pokémon, levels, ores and a guardian. You start on Button Isle; the further out you go, the stronger everything gets.
+
+          This book suggests what to do next. Nothing in it is locked and it gives no rewards: do things in any order you like.
+        tasks:
+          - checkmark: true
+            title: Read this
+      - id: first_partner
+        title: A Partner
+        icon: cobblemon:poke_ball
+        after: [welcome]
+        text: |
+          Weaken a wild Pokémon in battle, then throw a Poké Ball at it.
+        tasks:
+          - cobblemon: catch
+            amount: 1
+      - id: poke_balls
+        title: Poké Balls
+        icon: cobblemon:poke_ball
+        after: [welcome]
+        text: |
+          Poké Balls are crafted from apricorns, which grow on apricorn trees around the island. Look the recipe up in JEI.
+        tasks:
+          - item: cobblemon:poke_ball
+            count: 16
+      - id: full_team
+        title: A Full Team
+        icon: cobblemon:great_ball
+        after: [first_partner]
+        text: |
+          Six Pokémon of different types handle more than one strong one.
+        tasks:
+          - cobblemon: catch
+            amount: 6
+      - id: permadeath
+        title: A Second Chance
+        icon: cobblesurvival:revival_charm
+        after: [first_partner]
+        text: |
+          A Pokémon that faints is gone for good once the battle ends. Revives only help within that battle.
+          A Pokémon holding a Revival Charm is saved once instead: the charm is used up and the Pokémon is healed. Give one to your most valuable partner.
+        tasks:
+          - item: cobblesurvival:revival_charm
+      - id: healing
+        title: Healing
+        icon: cobblemon:healing_machine
+        after: [first_partner]
+        text: |
+          Sleeping doesn't heal your Pokémon. A Healing Machine does, but it is expensive and recharges slowly; potions and berries help in between.
+        tasks:
+          - item: cobblemon:healing_machine
+      - id: level_10
+        title: Growing Up
+        icon: cobblemon:exp_candy_s
+        after: [first_partner]
+        text: |
+          Raise a Pokémon to level 10 by battling. Wild Pokémon stronger than your team may come after you; weaker ones keep their distance.
+        tasks:
+          - cobblemon: level_up_to
+            amount: 10
+      - id: drops
+        title: What Pokémon Leave Behind
+        icon: minecraft:string
+        after: [first_partner]
+        text: |
+          Defeated Pokémon drop items. Look any item up in JEI (Cobblemon Info pages) to see which Pokémon drop it and where they live.
+        tasks:
+          - cobblemon: defeat
+            amount: 5
+      - id: evolve
+        title: Evolution
+        icon: cobblemon:fire_stone
+        after: [level_10]
+        text: |
+          Evolve a Pokémon. Some need a level, some an evolution stone: the stones come from ore veins in particular zones.
+        tasks:
+          - cobblemon: evolve
+            amount: 1
+      - id: beyond
+        title: Beyond Button Isle
+        icon: minecraft:compass
+        after: [level_10, full_team]
+        text: |
+          Southwold, north of Button Isle, is the next step: Pokémon up to level 18 and the island's copper.
+        tasks:
+          - event: zone/southwold
+            title: Reach Southwold
+
+  - id: button_isle
+    zone: button_isle
+    title: Button Isle
+    icon: cobblemon:poke_ball
+  - id: shallows
+    zone: shallows
+    title: Shallows
+    icon: minecraft:kelp
+  - id: southwold
+    zone: southwold
+    title: Southwold
+    icon: minecraft:raw_copper
+  - id: lush_caves
+    zone: lush_caves
+    title: Lush Caves
+    icon: minecraft:glow_berries
+  - id: westmarch
+    zone: westmarch
+    title: Westmarch
+    icon: cobblemon:thunder_stone
+  - id: jungle
+    zone: jungle
+    title: Verdant Jungle
+    icon: cobblemon:leaf_stone
+  - id: dripstone
+    zone: dripstone
+    title: Dripstone Depths
+    icon: minecraft:pointed_dripstone
+  - id: highlands
+    zone: highlands
+    title: Highland Meadows
+    icon: cobblemon:sun_stone
+  - id: mire
+    zone: mire
+    title: Mangrove Mire
+    icon: cobblesurvival:mire_waders
+    hazard_text: "The Mire's water poisons you unless you wear Mire Waders: the guardians of Westmarch and the Verdant Jungle drop them."
+    quests:
+      - id: waders
+        title: Mire Waders
+        icon: cobblesurvival:mire_waders
+        text: |
+          Waders keep the Mire's poison off. Beat the guardian of Westmarch or the Verdant Jungle for a pair.
+        tasks:
+          - item: cobblesurvival:mire_waders
+  - id: sunscorch
+    zone: sunscorch
+    title: Sunscorch
+    icon: cobblemon:fire_stone
+    hazard_text: "The desert heat hurts without heat insulation on your armor (Cold Sweat): look up insulation in JEI."
+  - id: deep_sea
+    zone: deep_sea
+    title: Deep Sea
+    icon: cobblemon:mystic_water
+  - id: frostpeak
+    zone: frostpeak
+    title: Frostpeak Range
+    icon: cobblemon:ice_stone
+    hazard_text: "The cold hurts without wool insulation on your armor (Cold Sweat): look up insulation in JEI."
+  - id: deep_dark
+    zone: deep_dark
+    title: Deep Dark
+    icon: minecraft:sculk
+    hazard_text: "Sculk darkens your sight down here. There is no Warden, but the ancient colossus sleeps in the ruins."
+  - id: basalt
+    zone: basalt
+    title: Basalt Furnace
+    icon: minecraft:magma_block
+    hazard_text: "The heat of the furnace hurts without heat insulation on your armor (Cold Sweat)."
+  - id: the_end
+    zone: the_end
+    title: The End
+    icon: minecraft:end_stone
+    quests:
+      - id: eyes
+        title: Eyes of Ender
+        icon: minecraft:ender_eye
+        text: |
+          The way to the End is through a stronghold's portal. Ender pearls come from Abra and its evolutions; blaze powder from Fire types such as Magmar.
+        tasks:
+          - item: minecraft:ender_eye
+            count: 12
+      - id: eternatus
+        title: Eternatus
+        icon: minecraft:dragon_egg
+        after: [arrive]
+        text: |
+          Eternatus has taken the dragon's place: a Lv 80 giant whose bar shows its health. Like the guardians, it takes at most a quarter of its health from any one attack.
+          Beating it opens the way home and leaves the dragon egg the first time.
+        tasks:
+          - event: end_boss
+            title: Beat Eternatus
+
+  - id: machines
+    title: Pokémon Machines
+    subtitle: Five machines, each powered by a Pokémon inside it
+    icon: cobblesurvival:heat_core
+    quests:
+      - id: about
+        title: Building a Machine
+        icon: cobblesurvival:heat_core
+        text: |
+          Each machine is a 3×3×3 shell with its core in the middle of one wall and an empty chamber in the centre for the Pokémon. Place the core: glowing ghost blocks show where the shell goes.
+          Send your Pokémon out near the core and use the core with an empty hand: it walks in. Use the core again to take it back; sneak-use to see what the machine is doing.
+        tasks:
+          - checkmark: true
+            title: Read this
+      - id: furnace
+        title: Large Furnace
+        icon: cobblesurvival:heat_core
+        after: [about]
+        text: |
+          A Fire-type Pokémon in a Heat Core shell of bricks heats furnaces placed against the shell: they burn without fuel and cook much faster. Hoppers work as usual.
+        tasks:
+          - event: machine/heat_core
+            title: Put a Fire type into a Large Furnace
+      - id: generator
+        title: Generator
+        icon: cobblesurvival:dynamo_core
+        after: [about]
+        text: |
+          An Electric-type Pokémon in a Dynamo Core shell of copper makes Forge Energy for cables and other machines.
+        tasks:
+          - event: machine/dynamo_core
+            title: Put an Electric type into a Generator
+      - id: synthesizer
+        title: Drop Synthesizer
+        icon: cobblesurvival:synthesis_core
+        after: [generator]
+        text: |
+          Feed energy into a Synthesis Core shell: the Pokémon inside makes its own drops, as if defeated. Gold, diamond or netherite shells add looting.
+        tasks:
+          - event: machine/synthesis_core
+            title: Put a Pokémon into a Drop Synthesizer
+      - id: altar
+        title: Sacrifice Altar
+        icon: cobblesurvival:altar_core
+        after: [about]
+        text: |
+          A Pokémon of level 20 or more in an Altar Core shell of obsidian can be given up for rare rewards: rare candies, ability items, even a nether star. It is gone for good.
+        tasks:
+          - event: machine/altar_core
+            title: Put a Pokémon on a Sacrifice Altar
+      - id: rebirth
+        title: Rebirth Chamber
+        icon: cobblesurvival:rebirth_core
+        after: [about]
+        text: |
+          A level 100 Pokémon in a Rebirth Core shell of amethyst is reborn after two hours as a shiny level 1 of its first stage, with better IVs and every move it knew.
+        tasks:
+          - event: machine/rebirth_core
+            title: Start a rebirth
+
+  - id: base
+    title: Base and Jobs
+    subtitle: Pokémon that work while you're away
+    icon: cobblemon:pasture
+    quests:
+      - id: pasture
+        title: A Pasture
+        icon: cobblemon:pasture
+        text: |
+          Pokémon in a Pasture Block live at your base. With Cobblebase they work there: harvesting, mining, finding items, breeding.
+          A job needs the Pokémon to be strong enough for the zone its work belongs to, or to hold one of that zone's materials.
+        tasks:
+          - item: cobblemon:pasture
+      - id: pc
+        title: A PC
+        icon: cobblemon:pc
+        text: |
+          Your PC holds every Pokémon not in your party. There is no remote access: you have to stand at a PC block.
+        tasks:
+          - item: cobblemon:pc