CAVES BIBLE — tiered ore caves + generation

STATUS: filled v1. Caves are instanced scenes (like the house/shop interiors) reached from overworld

ore-veins. Tier gates the resource table + danger + darkness. Resources defined in RESOURCES.md;

POWER/enemy bands in BALANCE.md. Mining needs the right pickaxe tier (EQUIPMENT.md).

CAVE TIERS (5) — each its own scene, look, enemy band, and ore table

Fields: Tier — region access · look/dark · enemy band · resource spawn table (weights) · gem chance · pick needed.

1. T1 Surface Adit — R1–2 · shallow, dim, timbered · band 1 · Copper 55 / Iron 20 / Leather-node 10 / bare rock 15 · gems: none · Iron Pick (or hammer slow).
2. T2 Iron Drift — R3–4 · deeper, lantern-needed · band 2 · Iron 45 / Bronze 25 / Copper 15 / Coal 12 / Emerald 3 · gems: Emerald only · Iron Pick.
3. T3 Steelvein Deep — R5–7 · dark, dripping · band 3 · Iron 25 / Steel-ore 28 / Silver 18 / Coal 12 / Emerald 8 / Ruby 6 / Sapphire 3 · Steel Pick.
4. T4 Glittervault — R8–10 · black, glittering walls · band 4 · Silver 22 / Gold 20 / Iron 14 / Sapphire 10 / Topaz 10 / Ruby 8 / Emerald 8 / Diamond 3 · Steel/Veil Pick.
5. T5 Tearreach (Black Vault) — R11–12, deep/instanced · near-lightless, Veil-cold · band 5 · Gold 22 / Silver 14 / Diamond 8 / Black Diamond 3 / rare rich veins · Veil Pick only.

ORE-GENERATION ALGORITHM (per cave scene)

Deterministic seed = hash(caveId, tier, dayOrEntryIndex) (instanced caves can roll fresh each entry; fixed

veins use a stable seed). Steps:

1. Layout — build a scene grid (~40×28): carve floor, set wall ring, place entrance + occasional deeper-stair

to a higher-tier sub-cave (an instanced cave inside a cave).

1. Rock substrate (always add rock squares) — scatter ROCK_TEXTURE tiles across ~18–30% of the interior

(denser at higher tier). These are the minable backdrop and read as "this is a mine."

1. Ore veins — pick V vein seeds (V ≈ 6 + tier·4). Each seed grows a cluster via short random-walk

(size 3–9, bigger at higher tier). Roll each vein's RESOURCE from the tier's weighted table → tint the

cluster with that resource's palette (RESOURCES.md hex) so veins read by colour.

1. Gem pockets — rare small clusters (1–3 tiles) gated by tier (gems T2+, Diamond T4+, Black Diamond T5);

placed away from the entrance (risk = reward).

1. Hazard/light — caves are dark; the player's lantern pool is the safe zone (light gear matters). Spawn

enemies from the cave's band; deeper = darker + nastier.

1. Mining rule — a vein only yields if the equipped pick tier ≥ the ore's tier (gates Diamond/Black-Diamond

behind the Steel/Veil pick — the grind gate).

OVERWORLD VEINS → entrances

• Scatter rock-texture vein squares across every region (per the request: always some rock squares on the

map). Two kinds:

• Surface node — mine a little ore in place (quick, low yield, region-tier resource).
• Instanced cave mouth (flagged) — entering generates a full instanced cave of the region's tier via the

algorithm above; fresh roll each entry (or per-vein stable seed if you want it to persist). This is where the

real ore/gem grind lives.

• Vein density scales by region; higher regions expose higher-tier mouths (and the gems that gate top gear).

CROSS-REFS

RESOURCES.md (what spawns) · BALANCE.md (enemy/pick bands) · PROCGEN-EQUIPMENT.md (what the ore becomes) ·

EQUIPMENT.md (pick tiers). Implementation = a build task (new cave scene + genCave(seed,tier) + vein objects

on the overworld) for the integration pass.