cobblemon-survival-pack/docs/balance.md

# Balance values

Every tunable lives in a config file or in this table. **Placeholder** means guessed and not yet approved by Adrian; never treat a placeholder as decided.

| Value | Current | Status | Where it is applied | Notes |
| --- | --- | --- | --- | --- |
| Island radius | 1,500 blocks | Placeholder | `tools/pokeball_preset.py --radius` | Test value from the roadmap; final size after Phase 1 review |
| Poké Ball band | 160 blocks wide channel across the middle | Placeholder | `tools/pokeball_preset.py --band` | |
| Poké Ball button | centre island r 280, ring channel 120 wide | Placeholder | `tools/pokeball_preset.py --button --ring` | The world spawn lands on the button |
| Coastline roughness | 0.03 (smooth, so the ball reads as a circle) | Placeholder | `tools/pokeball_preset.py` | |
| Raw ore blocks in structures | raw iron → tuff, raw copper → terracotta, raw gold → yellow terracotta | Placeholder | `tools/clean_structures.py` (`RAW`) | Look-alikes only; ores in structures become stone/deepslate/netherrack |
| World seed | chosen by `tools/seed_search.py` | Placeholder | `world/world.json` | Decides where each biome lands on the island |
| Seed-search targets | ≥5% land share per surface biome (3% for cherry grove, mangrove swamp, windswept hills, jagged peaks); no biome above 35%; gentle land within 350 blocks of 0,0 | Placeholder | `tools/seed_search.py` | Scoring weights, not gameplay values |
| Revival Charm recipe | 2 gold ingots, 2 Revives, 1 Max Revive (shaped) | Decided (Adrian, 2026-10-29) | `kubejs/server_scripts/revival_charm.js` | Meant to be expensive; gold comes from veins (Phase 4) and loot chests |
| Healing Machine recipe | 3 gold ingots, 4 iron ingots, 1 Max Revive, 1 diamond (shaped; Cobblemon: 3 copper, 4 iron, Max Revive, redstone) | Decided (Adrian, 2026-10-29) | `kubejs/server_scripts/healing_machine.js` | Roadmap: make Healing Machines expensive |
| Healing Machine recharge | 3,600 s from empty to full (6 charge, one per full Pokémon heal; Cobblemon: 900 s) | Decided (Adrian, 2026-10-29) | `config/cobblemon/main.json` → `secondsToChargeHealingMachine` | So a machine heals a full party about once an hour of play |
| Fainted Pokémon auto-recovery | never (`defaultFaintTimer` 1e9 s) | Decided (permadeath) | `config/cobblemon/main.json` | |
| Zone level bands | Button Isle 2–10, Southwold 8–18, Westmarch 15–25, Verdant Jungle 18–30, Highland Meadows 25–35, Mangrove Mire 25–38, Sunscorch 30–45, Frostpeak 40–55, Shallows 5–20, Deep Sea 30–50, Lush Caves 12–28, Dripstone 22–38, Deep Dark 45–60, Basalt Furnace 55–70 | Decided (Adrian, 2026-10-30) | `world/zones.json` → `levels`, then `tools/zone_layout.py` and `tools/zone_spawns.py` | Zone shapes approved (Adrian, 2026-10-29) |
| Evolution lines per zone (targets) | 15–35 per zone, scaled to the 377 lines available | Decided (Adrian, 2026-10-30) | `world/zones.json` → `lines` | Result per zone in `docs/zone-species.md` |
| Lines pinned to a zone | Durant, Torkoal, Heatmor → Basalt Furnace | Decided (Adrian, 2026-10-30) | `world/zones.json` → `species` | Basalt's own lines were all too big for its caves |
| Comfortable temperature range | 0.25–1.51 (Cold Sweat units; Cold Sweat: 0.4–1.51) | Decided (Adrian, 2026-10-30) | `config/coldsweat/main.toml` | Keeps the lowlands' nights livable without gear |
| Windswept hills temperature | 45–72 °F (Cold Sweat: 24–58 °F) | Decided (Adrian, 2026-10-30) | `config/coldsweat/world.toml` | They lie in the starter lowlands too |
| Insulating armour | fur set (cold 10/14/12/10), hide set (heat 10/14/12/10), as Cold Sweat; leather armour none (Cold Sweat: 5/7/6/5 both) | Decided (Adrian, 2026-10-30) | `config/coldsweat/item.toml` | Frostpeak at noon: about 1 min bare, 14 min in fur; Sunscorch at noon: about 2 min bare, 25 min in hide |
| Sewn-in insulation | goat fur 2 cold, hoglin hide 2 heat, wool 0.5 cold, leather 0.5/0.5 (Cold Sweat: wool 1.5, leather 1/1, rabbit hide 1.5 heat) | Decided (Adrian, 2026-10-30) | `config/coldsweat/item.toml` | |
| Goat Fur / Hoglin Hide recipes | 8 wool + 1 Heat Rock → 8 Goat Fur; 8 leather + 1 Icy Rock → 8 Hoglin Hide (a set takes 24) | Decided (Adrian, 2026-10-30) | `kubejs/server_scripts/insulation.js` | Heat and Icy Rocks come from the guardians before Frostpeak and Sunscorch (archaeology finds too) |
| Guardian respawn | 5 hours of game time after being beaten | Decided (Adrian, 2026-10-29) | `world/zones.json` → `guardian_respawn_hours` | Fixed spots |
| Guardian strength | strongest Pokémon spawning in the zone, band top + 5 levels, 1.5× size, uncatchable | Decided (Adrian, 2026-10-30) | `tools/zone_spawns.py` (`GUARDIAN_*`), `world/zones.json` → `guardian.species` | |
| Guardian drops | Button Isle 10 Poké Balls + 4 Potions; Southwold 6 Great Balls + 4 Exp. Candy S; Westmarch and Jungle Mire Waders + 4 Pecha Berries + 2 Exp. Candy M; Mire and Highlands 3 Icy Rocks + 4 Super Potions; Sunscorch 3 Heat Rocks + 2 Exp. Candy L; Frostpeak and Deep Dark 3 Icy Rocks + 2 Exp. Candy L; Deep Sea Mystic Water + 3 Exp. Candy M | Decided (Adrian, 2026-10-30) | `world/zones.json` → `guardian.drops` | 3 rocks make one full fur or hide set |
| Mire poison | Poison I for 7 s, renewed every 5 s while in the Mire without Mire Waders | Decided (Adrian, 2026-10-30) | `datapacks/core/data/cobblesurvival/zone_hazards/mire.json` | Vanilla Poison stops at half a heart |
| Level pressure | full experience up to 5 levels above the zone's band, then 10 % less per level, at least 10 % (Exp. Candy and commands exempt) | Decided (Adrian, 2026-10-30) | `world/zones.json` → `level_pressure` | E.g. on Button Isle (up to Lv 10): Lv 15 full, Lv 20 half, Lv 24+ a tenth |
| Strong flyer | ridable through the air with top speed ≥ 60 or top stamina ≥ 85 (Cobblemon ride stats) | Decided (Adrian, 2026-10-30) | `tools/zone_spawns.py` (`STRONG_FLYER_*`) | 29 species |
| High zone for strong flyers | band starts at Lv 30 or more (Sunscorch, Frostpeak, Deep Sea, Deep Dark, Basalt Furnace) | Decided (Adrian, 2026-10-30) | `tools/zone_spawns.py` (`HIGH_ZONE_LEVEL`) | |
| Ore tiers per zone | Button Isle: coal; Southwold: copper; Westmarch: iron, thunder stone; Verdant Jungle: redstone, leaf stone; Highland Meadows: lapis, sun stone; Sunscorch: gold, fire stone; Frostpeak Range: emerald, ice stone, dawn stone; Dripstone Depths: amethyst, moon stone; Deep Dark: diamond, dusk stone; Basalt Furnace: quartz, netherite; Lush Caves: shiny stone; Mangrove Mire: water stone | Placeholder | `world/zones.json` → `ores` → `tools/zone_ores.py` | Each tier in exactly one zone; evolution stones are tiers (their natural ores are off) |
| Vein regrowth | 20 min: coal; 30 min: copper; 40 min: iron; 45 min: redstone, lapis; 60 min: gold, quartz, thunder stone, shiny stone, leaf stone, water stone, moon stone, sun stone, fire stone, ice stone; 75 min: emerald, dawn stone, dusk stone; 90 min: diamond; 120 min: amethyst; 180 min: netherite; ±10 % jitter; real time | Placeholder | `world/zones.json` → `ores` (`regen_minutes`, `ore_defaults.jitter`) | Counts while the server is off too |
| Vein spacing, size, tries | spacing 4–14 chunks between candidate chunks, radius 0–2, 70 % filled, 1–4 tries per candidate chunk (per tier in `world/zones.json`) | Placeholder | `world/zones.json` → `ores`, `ore_defaults` | Ore blocks in the template (2026-10-30): copper 10,400, iron 6,356, quartz 2,397, lapis 2,236, coal 2,222, redstone 1,044, gold 815, diamond 559, shiny stone 466, thunder stone 239, sun stone 238, amethyst 238, dusk stone 222, emerald 181, leaf stone 125, ice stone 102, moon stone 100, fire stone 98, water stone 95, netherite 74, dawn stone 64. Per zone in `build/island-report.json` after `tools/make_world.py` |
| Regenerators breakable by players | no; explosions don't hurt veins | Placeholder | `tools/zone_ores.py` → `global.json` | Otherwise a player could remove a vein for good |
| Vein Locator | compass + copper ingot; 75 % chance to break per use (the mod's default) | Placeholder | `tools/zone_ores.py` → `vein_locator.json` | The mod's default recipe needs netherite |
| Drops for mobs the island lacks | Blaze Rod: Carkol 10 %, Torkoal 25 % ×1–2; Ghast Tear: Drifloon 5 %, Dusclops 10 %; Breeze Rod: Whimsicott 10 %; Shulker Shell: Shuckle 10 %, Cloyster 10 %; Nether Star: Charizard 5 % | Placeholder | `datapacks/core/data/cobblesurvival/species_additions/` | Every drop and what consumes it: `docs/pokemon-drops.md` (`tools/drop_audit.py`) |
| Ride stats (speed, stamina, ...) | Cobblemon's own | To tune after play-testing | species `riding` via `species_additions` | |
| Healing while sleeping | off (`healPercent` 0) | Decided (roadmap) | `config/cobblemon/main.json` | |
| Loot container refresh | 1 hour (72,000 ticks of game time) after first opened, all containers | Decided (Adrian, 2026-10-29) | `config/lootr-common.toml` | Tiering by structure/biome later |
| Gamerules in the template | `doMobSpawning false` | Decided (Adrian, 2026-10-28; may be reverted later) | `world/world.json` → `gamerules` | Pokémon spawning is Cobblemon's own `doPokemonSpawning` |
| Border margin | 96 blocks of sea past the outermost coast | Placeholder | `world/world.json` | |
| Pregeneration circle | radius 1,700 around 0,0 | Tooling | `world/world.json` | Must cover the land plus `border_margin`; `make_world.py` stops if it doesn't |
| Server heap for smoke test | 4 GB | Tooling | `tools/smoke_test.py` | Not a gameplay value |
| Dev client heap (Prism) | 6 GB | Tooling | `tools/prism_instance.py --memory` | Not a gameplay value |

Sections to fill as phases land: pasture job cooldowns (Phase 4), hazard damage (Phase 3), field-move cooldowns and caps (Phase 5), machine output (Phase 6), boss attack damage and telegraph times (Phase 7).