Define resource deposit data model for ores and clay #26

New issue

Open

opened 2026-08-19 06:35:33 +01:00 by liamjd · 0 comments

liamjd commented

2026-08-19 06:35:33 +01:00

Owner

Resource placement (docs/resource-prospecting.md, docs/colony-game-resource-types.md) needs a concrete data model before any prospecting/mining work can start. This issue records the decision from discussion and scopes the first-cut implementation.

Decision: deposits are objects, not a per-tile attribute

TerrainGrid already has a per-tile pattern (_levels, Kind derived from it), but a resource deposit should not reuse it. A deposit is an object with:

a resource type
a footprint (a small set of cells, not necessarily contiguous with anything else)
a per-cell richness value within that footprint (so rendering can do the dot-grid density look from Workers & Resources rather than a flat per-deposit number)
discovered/revealed state (mechanism TBD — see Out of scope)

The deciding factor: paired ore deposits are meant to overlap. A tile can legitimately belong to two deposits at once (see below), which a single per-tile slot on TerrainGrid cannot express. Objects also make the sensor-reveal and contract minimum-resource checks cheap (iterate ~10-30 deposits) instead of requiring a full grid scan.

Scope

Ore deposits (iron, copper, gold, lead, zinc, nickel, cobalt, tin, tungsten, molybdenum, iron/manganese, rare earths, etc. — full list in colony-game-resource-types.md) are placed by seeded rejection-sampling against terrain criteria, deterministic from map_seed the same way terrain generation is.
Paired resources (lead+zinc, copper+gold, nickel+cobalt, tin+tungsten+molybdenum, iron+manganese) are placed as two independently-placed, overlapping deposits, not a single dual-resource object. The second resource's placement is weighted toward proximity to existing instances of the first, but not guaranteed — this preserves both pure single-resource deposit edges and richer mixed overlap centres as a deliberate player choice (comparable to adjacent ore patches in Factorio).
Clay is placed by rule-classification rather than scatter-sampling — roughly "low tiles within N tiles of water," for some definition of "low" to be tuned during implementation — but the matching region must be chunked into several smaller, distinct deposit instances rather than left as one sprawling deposit running the length of a shoreline.
Per resource-prospecting.md, deposits are rich by design ("don't expect them to run out during gameplay") — model as effectively non-depleting for now rather than building out depletion tracking nothing currently requires.

Explicitly out of scope for this issue

Stone gets no deposit object at all. It's extractable everywhere but only via a Quarry facility, whose placement is validated directly against terrain slope (binary pass/fail, not a yield gradient). See #27, the terrain-slope-query issue this depends on.
The reveal/fog-of-war mechanic (which resources are visible at map start vs. discovered via sensors) — resource-prospecting.md poses this as an open question and it isn't resolved here.
The "guarantee minimum resources for contract completion" check — no algorithm decided yet.
Exact placement heuristics/thresholds for each ore type (only stone and clay have anything concrete drafted in the docs; the rest is a flavour list of real-world ore pairings, not yet mapped to in-game placement rules).

References

docs/resource-prospecting.md, docs/colony-game-resource-types.md, docs/colony-game-facilities.md (extraction facility types this feeds into).

Resource placement (`docs/resource-prospecting.md`, `docs/colony-game-resource-types.md`) needs a concrete data model before any prospecting/mining work can start. This issue records the decision from discussion and scopes the first-cut implementation. ## Decision: deposits are objects, not a per-tile attribute `TerrainGrid` already has a per-tile pattern (`_levels`, `Kind` derived from it), but a resource deposit should **not** reuse it. A deposit is an object with: - a resource type - a footprint (a small set of cells, not necessarily contiguous with anything else) - a per-cell richness value within that footprint (so rendering can do the dot-grid density look from *Workers & Resources* rather than a flat per-deposit number) - discovered/revealed state (mechanism TBD — see Out of scope) The deciding factor: **paired ore deposits are meant to overlap.** A tile can legitimately belong to two deposits at once (see below), which a single per-tile slot on `TerrainGrid` cannot express. Objects also make the sensor-reveal and contract minimum-resource checks cheap (iterate ~10-30 deposits) instead of requiring a full grid scan. ## Scope - **Ore deposits** (iron, copper, gold, lead, zinc, nickel, cobalt, tin, tungsten, molybdenum, iron/manganese, rare earths, etc. — full list in `colony-game-resource-types.md`) are placed by seeded rejection-sampling against terrain criteria, deterministic from `map_seed` the same way terrain generation is. - **Paired resources** (lead+zinc, copper+gold, nickel+cobalt, tin+tungsten+molybdenum, iron+manganese) are placed as two **independently-placed, overlapping** deposits, not a single dual-resource object. The second resource's placement is weighted toward proximity to existing instances of the first, but not guaranteed — this preserves both pure single-resource deposit edges and richer mixed overlap centres as a deliberate player choice (comparable to adjacent ore patches in Factorio). - **Clay** is placed by rule-classification rather than scatter-sampling — roughly "low tiles within N tiles of water," for some definition of "low" to be tuned during implementation — but the matching region must be **chunked into several smaller, distinct deposit instances** rather than left as one sprawling deposit running the length of a shoreline. - Per `resource-prospecting.md`, deposits are rich by design ("don't expect them to run out during gameplay") — model as effectively non-depleting for now rather than building out depletion tracking nothing currently requires. ## Explicitly out of scope for this issue - **Stone** gets no deposit object at all. It's extractable everywhere but only via a Quarry facility, whose placement is validated directly against terrain slope (binary pass/fail, not a yield gradient). See #27, the terrain-slope-query issue this depends on. - The reveal/fog-of-war mechanic (which resources are visible at map start vs. discovered via sensors) — `resource-prospecting.md` poses this as an open question and it isn't resolved here. - The "guarantee minimum resources for contract completion" check — no algorithm decided yet. - Exact placement heuristics/thresholds for each ore type (only stone and clay have anything concrete drafted in the docs; the rest is a flavour list of real-world ore pairings, not yet mapped to in-game placement rules). ## References `docs/resource-prospecting.md`, `docs/colony-game-resource-types.md`, `docs/colony-game-facilities.md` (extraction facility types this feeds into).

liamjd added the

enhancement

label

2026-08-19 06:35:33 +01:00

liamjd referenced this issue

2026-08-19 06:35:46 +01:00

Add slope/neighbour-gradient query to TerrainGrid #27

liamjd added this to the Untitled Colony Builder project

2026-08-19 19:44:06 +01:00

liamjd referenced this issue

2026-08-20 05:43:42 +01:00

Add Deposit and ResourceDeposits classes for resource placement #29