cobblemon-survival-pack/docs/roadmap.md

# Cobblemon Survival Pack – Agent Roadmap

Oct 28, 2026 · @Adrian

## Brief for the agent

Build a free NeoForge 1.21.1 modpack on Cobblemon 1.8.x: one large preset island with Palworld/ARK-style progression, plus a single companion mod for the mechanics no addon covers. Work phase by phase; every phase ends with "Done when" checks, and some end with a checkpoint where you stop and report to Adrian.

### Design pillars (do not trade these away)

1. **Soft gates only.** Nothing is hard-locked. Progress is steered by hostile environments, harder Pokémon and recipe chains. A player who pushes ahead with potions or golden apples is allowed to.
2. **Pokémon permadeath.** A fainted Pokémon is deleted. The player does not die when the team wipes.
3. **Controlled resources.** No natural ore anywhere. Ore comes only from surface veins that regenerate on a timer.
4. **Pokémon are part of the world.** Their drops are crafting inputs, they work at bases, their moves change blocks (fire, ice, digging), and machines run on Pokémon that are visibly inside them.
5. **Base-bound storage.** The PC works only at a placed PC block; pastured Pokémon are physically present.
6. **Zones by level.** Each biome region of the island has its own level band and Pokémon.
7. **Data before code.** Config, datapack or KubeJS first; an existing addon second; the companion mod third.

### Working rules

- Never bundle third-party jars. Reference every mod through packwiz metadata, read its license first, and log it in `docs/licenses.md`.
- Pin every version. Record each addon's Cobblemon 1.8 status in `docs/addon-status.md`; many addons still target 1.7.
- Keep every tunable (levels, drop rates, timers, damage) in config or `docs/balance.md`. Mark guessed values as placeholders instead of presenting them as decided.
- You cannot judge visuals or feel. At the end of each phase, list exactly what Adrian should check in-game.
- Stop at each **Ask Adrian** checkpoint and wait for an answer before continuing.
- The pack stays free: no monetization, credit every author, include a non-affiliation disclaimer.

## Technical baseline

NeoForge 1.21.1 is assumed because Cold Sweat and Regenerating Ore Veins only ship for NeoForge on 1.21.1; Adrian has not confirmed it yet.

| Component | Choice | Notes |
| --- | --- | --- |
| Game + loader | Minecraft 1.21.1, NeoForge 21.1.x | Pin one NeoForge build |
| Core | [Cobblemon](https://modrinth.com/mod/cobblemon/version/gBW3vLC7) 1.8.x | 1.8.3 is current as of Oct 2026 |
| Pack definition | packwiz | Exports to Modrinth and CurseForge formats |
| Companion mod | Kotlin, NeoForge MDK + Kotlin for Forge | Take Cobblemon's maven coordinates from its official docs or addon template; don't guess them |
| Recipes, tags, item tweaks | KubeJS | Keeps recipe chains out of Java/Kotlin |
| Quests | FTB Quests | See Phase 8 |
| Map | WorldGen Editor + shipped world template | See Phase 1 |

### Repo layout

```
pack/              packwiz definition: mods/*.pw.toml, config/, kubejs/, defaultconfigs/
datapacks/core/    spawn pools, species drops, ride settings, habitat pools
mod/               companion mod (Kotlin)
world/             shipped world template
docs/              design.md, balance.md, licenses.md, addon-status.md, quests source
tools/             build, server smoke test, quest generator, worldgen helpers
```

### Test loop

1. `packwiz refresh`, then export both pack formats.
2. Server smoke test in CI: boot a dedicated NeoForge server with the pack and the world template, wait for startup, run a command script over RCON (key commands exist, datapacks loaded, no errors or missing-mod warnings in the log), then stop.
3. Companion mod: unit tests for pure logic, NeoForge GameTests for anything that touches blocks or entities.
4. A written in-game checklist for Adrian at the end of each phase.

## Phase map

[embedded content: phase dependencies · 10 phases\]

Phases in the same column can run in parallel. Not drawn: boss battles (Phase 7) also reuse the field-move effects from Phase 5.

## Phase 0 – Repo and pack skeleton

Goal: a pack that boots on a dedicated server with Cobblemon 1.8.x and an empty companion mod.

- Create the repo layout above, the packwiz pack, and the companion mod scaffold (mod id, Kotlin for Forge, Cobblemon as a compile dependency).
- Add the CI smoke test from the test loop.
- Start `docs/addon-status.md` with every addon named in this roadmap and its 1.8 status.

**Done when:** CI boots the server cleanly, the companion mod logs that it loaded, and both pack exports install in a launcher.

## Phase 1 – Island map

Goal: a generated, natural-looking large island that Adrian can tweak later.

**Approach.** Use [WorldGen Editor](https://www.mado-hosting.com/en/minecraft-mods/worldgen-editor) (NeoForge 1.21.1, v0.3.0). It generates islands from JSON presets with position, radius, coastline roughness, temperature, biome patch size and per-island biome exclusions, keeps vanilla-style terrain, and has a separate previewer for layouts. It is licensed CC BY-NC-SA 4.0, which fits a free pack with attribution. The fallback is the desktop editor WorldPainter.

1. Write one preset: a single large island inside an outer ocean. Use biome exclusions so the biome set matches the zone plan from Phase 3.
2. Remove natural ore: [Ore Generation Configuration](https://www.curseforge.com/minecraft/mc-mods/regenerating-ore-veins) (linked via its author's vein-mod page; a server-side mod that reduces, denies or replaces ore generation in new chunks) or a datapack that blanks the ore placed features.
3. Generate a test world, pregenerate the island area with a pregenerator such as Chunky, and set a world border just outside the coast.
4. Ship the result as the pack's world template. Document how to edit it (WorldPainter on the exported world, or in-game editing tools).
5. Render a top-down biome map image for review.

**Ask Adrian:** approve the island size and layout before Phase 3. The radius is undecided; start around 1,500 blocks for testing (a placeholder, not a design value).

**Done when:** the template loads, contains no natural ore blocks in a scripted scan of sample chunks, and the border matches the coast.

## Phase 2 – Core survival rules

Goal: the survival ruleset works before any zone content exists.

- **Permadeath.** Install [CobbleHardcoreMon](https://modrinth.com/project/VqvNhP9x) (MIT, NeoForge, Cobblemon 1.8.x). A Pokémon that faints without holding the configured totem item is removed permanently. Point that item at a costly crafted "revival charm" (soft safety net) instead of the default Totem of Undying. Leave its Health Link and Soul Link options off. Do not install any whiteout mod.
- **Verify permadeath edge cases** with GameTests or scripted tests: faint in a wild battle, a trainer battle, and outside battle (poison, fall, fire). Close any gap in the companion mod.
- **Healing friction.** Turn off party healing on sleep and make Healing Machines expensive.
- **Storage.** PC only at placed PC blocks; add no remote-PC addons such as Cobblemon Box Link. Install [TP-Pastures](https://www.curseforge.com/minecraft/mc-mods/cobblemon-tp-pastures) so pastured Pokémon are teleported back instead of recalled.
- **Dangerous wilds.** Install Fight or Flight Reborn so wild Pokémon flee or fight back.
- **Free movement in battle.** Cobblemon lets players toggle free movement during battles (build, mine, fight mobs). Confirm it stays available; Phase 7 depends on it.
- **Vanilla clean-up.** Remove or replace vanilla hostile mobs, villages and loot tables that hand out ore or ingots.

**Done when:** the permadeath test matrix passes, a party can no longer be healed by sleeping, and no remote PC access exists.

## Phase 3 – Zones, spawns and soft gates

Goal: each region of the island has its own Pokémon, level band and hazard.

1. Draft a zone table in `docs/design.md`: zone, biomes, level band, hazard, signature drops, Alpha guardian. **Ask Adrian** to approve it.
2. Nullify Cobblemon's base spawns from your datapack's `pack.mcmeta` and write `spawn_pool_world` entries per zone with narrow level ranges ([custom spawns tutorial](https://wiki.cobblemon.com/index.php/Tutorials/Creating_Custom_Spawns)). Keep ranges tight, because the spawner also considers the party's level.
3. Use [Habitat Blocks](https://wiki.cobblemon.com/index.php/Habitat_Block) for set pieces: each sets its own pool, level range, spawn range, max spawns and whether it replaces natural spawns.
4. Place one Alpha guardian per zone. Its drops should make the next zone easier, never unlock it.
5. **Hazards as gates.** Cold and heat through [Cold Sweat](https://www.curseforge.com/minecraft/mc-mods/cold-sweat): without insulation the player keeps taking damage. Make insulation recipes (KubeJS) need Pokémon drops, e.g. wool for the cold zone. Other hazards (a poison swamp) go in the companion mod as area effects. Potions and golden apples must remain a valid way to push through.
6. **Soft level pressure** (companion mod): reduced XP, or a disobedience chance, for Pokémon far above a zone's band. No hard level caps.
7. **Flyers.** Tune stamina and speed per species in `ride_settings`; strong flyers only spawn in high-level zones. Nothing blocks mounting.

**Done when:** a scripted spawn survey per zone shows only that zone's species and levels, and the cold zone damages an unprotected player but not one in wool armour.

## Phase 4 – Resources and jobs

Goal: ore, Pokémon drops and base production form the economy.

- **Ore veins.** [Regenerating Ore Veins](https://www.curseforge.com/minecraft/mc-mods/regenerating-ore-veins): one `areas.json` box per zone, `veins.json` entries per ore tier restricted to their zone, regeneration intervals with jitter, and hand-placed showcase veins. Higher-tier ores sit in higher-level zones.
- **Unique drops.** Species drop tables in the datapack for every crafting-relevant drop. List each drop and what consumes it in `docs/balance.md`.
- **Base jobs.** [Cobblebase](https://modrinth.com/project/cobblebase) for pasture jobs; check it on 1.8 first. Tune Producer loot and cooldowns per species.
- **Power.** Either [Cobblemon Poke Power](https://modrinth.com/project/lIn7oRFm) (Electric types output Forge Energy) or your own generator from Phase 6, not both.

**Done when:** every ore tier has veins in exactly one zone, veins regenerate after restart and chunk unload, and every recipe input that comes from a Pokémon has at least one obtainable source.

## Phase 5 – Field moves and party passives (companion mod)

Goal: moves a Pokémon knows act on the world, HM-style. Flamethrower sets blocks on fire.

**Decided 2026-10-31 (Adrian):** the field moves come from Cobblemon HMs instead of the spec below; mining ore is the one hard requirement, and furnaces are lit by a Pokémon inside a Phase 6 machine. See `docs/design.md`.

**Prior art to study, not depend on.** None is confirmed on Cobblemon 1.8:

- [Cobblemon Field Survival](https://www.modpackindex.com/mod/173947/cobblemon-field-survival) (NeoForge 1.21.1, Cobblemon 1.7.3): mining, digging, water utilities, Fire types cooking food.
- [Cobblemon Environment Interactions](https://www.modpackindex.com/mod/122894/cobblemon-environment-interactions): type-based mining and utilities while riding or commanding one companion.
- [SceneBlocks](https://www.modpackindex.com/mod/151464/sceneblocks) (from CobbleKanto): Cut, Rock Smash, Strength and Flash interacting with special blocks, checked against the party's moves.
- [CobbleStrike](https://modrinth.com/project/cobblestrike): Dig, Cut, Rock Smash, fire and ice field moves, but built for Cobblemon 1.5.2.

**Spec.**

- Data-driven: `data/<modid>/field_moves/*.json` maps move ids to an action (ignite, freeze water, break blocks by tag with a hardness cap, extinguish, grow crops, light area), range, shape (line, cone, sphere), cooldown and optional cost.
- Trigger with a keybind while the Pokémon is sent out or ridden. The server checks that the Pokémon really knows the move.
- Respect game rules and protection: fire spread follows `doFireTick`, block changes go through normal break/place events so claim mods can cancel them.
- First set: Flamethrower/Ember (ignite, light campfires and furnaces), Ice Beam (freeze water), Dig/Rock Smash (break stone and ore within cap), Cut (fell trees), Water Gun (extinguish, fill cauldrons).
- **Party passives**, also data-driven: e.g. Haste while a Rock or Ground type is in the party, warmth in the cold zone from Fire types.

**Done when:** GameTests cover every action, a missing move is rejected server-side, and fire behaves correctly with `doFireTick` on and off.

## Phase 6 – Pokémon machines (companion mod)

Goal: multiblock machines powered by a Pokémon that is visibly inside them, e.g. a Fire type fuelling a large furnace.

- **Structure.** Pattern-checked multiblocks with a controller block; first machines: Large Furnace (Fire) and Generator (Electric, outputs Forge Energy so other mods' cables work).
- **Inserting a Pokémon.** From the party or a ball item at the controller. The Pokémon keeps its identity and data while inside.
- **Rendering.** Preferred: spawn a real Cobblemon Pokémon entity anchored in the machine's cavity with movement disabled, so Cobblemon's own models and animations are reused. Study how Pasture Blocks tether their entities and copy that pattern. Fallback: a block-entity renderer that draws the model directly (more fragile across versions).
- **Behaviour.** Output scales with type, level and a relevant stat. The Pokémon never faints or dies from machine work.
- **Safety.** Breaking or invalidating the structure returns the Pokémon to the owner (party, else PC). State survives chunk unload and restart. No duplication through break/insert races.

**Done when:** GameTests cover insert, remove, structure break, unload/reload and server restart without loss or duplication, and Adrian confirms the in-machine rendering looks right.

## Phase 7 – Boss battles with area attacks (companion mod)

Goal: during a boss battle, the boss spawns area attacks that the player must physically dodge.

- **Why this works.** Cobblemon supports free movement during battles ([official modpack feature list](https://www.modpackindex.com/modpack/70659/cobblemon-official-modpack-fabric)). A third-party addon notes that Cobblemon only checks flee distance when a battle starts ([Auto-Battle changelog](https://www.curseforge.com/minecraft/mc-mods/cobblemon-auto-battle/files/7999259)); verify this, and add your own arena radius so players can't walk away from a boss.
- **Boss definition JSON.** Which Pokémon (an Alpha or a custom aspect), arena radius, and attack patterns: circle, line, cone, ring. Each pattern has a telegraph time, damage, and trigger (every N turns, on a timer, or at HP thresholds).
- **Runtime.** While the boss's battle is active, the server runs patterns: telegraph with ground particles, then damage entities in the area. Everything stops when the battle ends. Reuse Phase 5 effects (fire, ice) where they fit.
- **Rules to confirm** (see open decisions): AoE hits the player only, and a player death mid-battle ends the battle as a loss.

**Done when:** a test boss telegraphs and lands each pattern type, attacks stop on battle end, and leaving the arena radius forfeits the battle.

## Phase 8 – Questbook as a research tree

Goal: a quest book that points players onward, laid out like a research tree whose dependencies are visible but never block.

- **Tool.** FTB Quests, which has current NeoForge 1.21.1 builds ([files](https://www.curseforge.com/minecraft/mc-mods/ftb-quests-forge/files/all)) and draws quests as nodes connected in dependency trees.
- **Soft dependencies.** Use FTB Quests' Flexible progression mode, where a quest's tasks can be completed before its dependencies. A community fix mod reports a [soft-lock in that mode](https://modrinth.com/project/SWZGEk5x) when tasks finish first; test for it and add the fix if needed. Hide the per-quest lock icon ("Hide Lock Icon") so nothing looks locked, and keep dependency lines visible.
- **Layout.** One chapter per zone plus chapters for base building, Pokémon jobs and machines. Each chapter reads left to right, from basics to advanced.
- **Content.** Tasks: catch a species, obtain a drop, visit a biome, build a machine, beat a guardian. Rewards stay small and never unlock anything. Cobblemon-specific task types come from a Cobblemon–FTB Quests integration addon; check its 1.8 support.
- **Drop sources in JEI** (Adrian, 2026-11-02). Every item that can drop gets a JEI page (JEI is the pack's NEI) showing where it drops: which Pokémon (chance, amount, and the zone they spawn in), guardian and End boss rewards, the Sacrifice Altar's level tiers, the Drop Synthesizer, zone ore veins and the pasture mining/finder tables. Generate the pages from the data the game itself uses (species drops, `guardians/`, `bosses/`, `machines/`, loot tables) through a JEI plugin in the companion mod, so they can't drift. First check whether a Cobblemon–JEI addon already shows Pokémon drops on 1.8 and build on it if so.
- **Source of truth.** Write quests in `docs/quests.yaml` (id, title, description, tasks, soft dependencies, grid position) and generate FTB Quests SNBT with a script in `tools/`. Adrian can then rearrange nodes in the in-game editor; note which file wins on regeneration.

**Done when:** every zone has a chapter, every quest is completable in any order, the generator round-trips without losing Adrian's manual position edits, and every item that can drop has a JEI page naming all its sources.

## Phase 9 – Balancing and release

- **Balance pass** on levels, drop rates, vein timers, job cooldowns, hazard damage and machine output, all from `docs/balance.md`.
- **Every implemented Pokémon is obtainable** (Adrian, 2026-11-09). Every species Cobblemon has a model for must be reachable somewhere in the world, even if rarely or through crafting: a wild spawn, evolving a wild line, a fossil, or a crafted or summoned encounter. Legendaries and the like count too; they can be very rare or expensive. Checked on 2026-11-09: 95 of 905 implemented species are not reachable by a wild spawn or by evolving a wild line (legendaries, fossils, and lines the zone assignment left out, such as Aron, Litwick and Piplup). Report what is missing with a tool or self-test so new Cobblemon versions can't reopen the gap.
- **A shader pack included** (Adrian, 2026-11-09). Ship [Iris](https://modrinth.com/mod/iris) (client only) and [Complementary Reimagined](https://modrinth.com/shader/complementary-reimagined), installed but off by default; players switch it on with a key or in Video Settings. Iris 1.8.14-beta.1+1.21.1-neoforge (MR `KduFYu4t`) is built against Sodium 0.8.13, which the pack already pins; it is the only NeoForge 1.21.1 build for Sodium 0.8, and a beta. Complementary r5.9.3 (MR `Bqen1mJX`) has the most downloads of the common shader packs and keeps a vanilla-like look, which suits Cobblemon's models. Its license allows modpacks if it is left unmodified, credited where the pack is described when it's on by default (it isn't; it's credited anyway), and added through Modrinth or CurseForge's own systems, never as an uploaded file: the private pack has to download it from Modrinth. Check that Cobblemon's models, the machine and boss particles and the see-through blocks render properly with it on, and measure the frame-rate cost.
- **Performance.** Profile with spark on a server with realistic pen and machine counts; cap entity density through pasture config if needed.
- **Reproducible builds** (Adrian, 2026-11-09). The same commit gives the same bytes: pinned JDK, packwiz, Gradle plugins and Python packages; `tools/check_reproducible.py` proves it.
- **Balancing on the server** (Adrian, 2026-11-09). Balance changes reach playtesters without a client update: `tools/server_update.py`, a server-held data pack, JEI pages sent by the server.
- **Multiplayer test** with Adrian's group.
- **Release.** Final `docs/licenses.md`, credits and non-affiliation disclaimer; publish client and server packs on Modrinth and CurseForge as dependency-based packs.

**Done when:** a full playthrough from spawn to the last zone is possible without commands, every implemented Pokémon can be obtained without commands, and a server runs a multi-hour session without tick-time spikes from Pokémon entities.

## Open decisions for Adrian

The agent should proceed with the default in each row and flag it, rather than block.

| Decision | Default to assume |
| --- | --- |
| Loader | NeoForge 1.21.1 |
| Island size | Radius around 1,500 blocks for testing; final size after Phase 1 review |
| Permadeath safety net | One costly crafted revival charm replaces the Totem of Undying as the protective held item |
| Do boss area attacks hit party Pokémon? | No, player only |
| Player dies during a battle | The battle ends as a loss; Pokémon that had not fainted survive |
| Separate storage per base | No; all PC blocks share one storage |
| Roster size for v1 | Every species Cobblemon has a model for (Adrian, 2026-11-09; see Phase 9), replacing the curated 150–250 |
| Pen footprint rule | Lower pasture limits only; no size-based rule in v1 |
| Multiplayer target | Small private server group |

## Sources

- [Cobblemon 1.8.1 (Modrinth)](https://modrinth.com/mod/cobblemon/version/gBW3vLC7)
- [Cobblemon Official Modpack feature list (Modpack Index)](https://www.modpackindex.com/modpack/70659/cobblemon-official-modpack-fabric)
- [Creating Custom Spawns (Cobblemon Wiki)](https://wiki.cobblemon.com/index.php/Tutorials/Creating_Custom_Spawns)
- [Habitat Block (Cobblemon Wiki)](https://wiki.cobblemon.com/index.php/Habitat_Block)
- [WorldGen Editor (Mado Hosting listing)](https://www.mado-hosting.com/en/minecraft-mods/worldgen-editor)
- [Regenerating Ore Veins (CurseForge)](https://www.curseforge.com/minecraft/mc-mods/regenerating-ore-veins)
- [CobbleHardcoreMon (Modrinth)](https://modrinth.com/project/VqvNhP9x)
- [Cobblemon TP-Pastures (CurseForge)](https://www.curseforge.com/minecraft/mc-mods/cobblemon-tp-pastures)
- [Cold Sweat (CurseForge)](https://www.curseforge.com/minecraft/mc-mods/cold-sweat)
- [Cobblebase (Modrinth)](https://modrinth.com/project/cobblebase)
- [Cobblemon Poke Power (Modrinth)](https://modrinth.com/project/lIn7oRFm)
- [Cobblemon Field Survival (Modpack Index)](https://www.modpackindex.com/mod/173947/cobblemon-field-survival)
- [Cobblemon Environment Interactions (Modpack Index)](https://www.modpackindex.com/mod/122894/cobblemon-environment-interactions)
- [SceneBlocks (Modpack Index)](https://www.modpackindex.com/mod/151464/sceneblocks)
- [CobbleStrike (Modrinth)](https://modrinth.com/project/cobblestrike)
- [Cobblemon Auto-Battle changelog (CurseForge)](https://www.curseforge.com/minecraft/mc-mods/cobblemon-auto-battle/files/7999259)
- [FTB Quests NeoForge files (CurseForge)](https://www.curseforge.com/minecraft/mc-mods/ftb-quests-forge/files/all)
- [FTB Quests flexible-mode fix (Modrinth)](https://modrinth.com/project/SWZGEk5x)
- [Iris Shaders (Modrinth)](https://modrinth.com/mod/iris)
- [Complementary Reimagined (Modrinth)](https://modrinth.com/shader/complementary-reimagined), [its license](https://github.com/ComplementaryDevelopment/ComplementaryReimagined/blob/main/License.txt)