Exploration, Cartography, and Resource Discovery¶
Design Goals¶
Exploration should be a real profession and information economy, not just a checkbox that reveals the map once.
See map-tiles-fog-and-cartography.md for the detailed tile, fog-of-war, and map-sharing model.
The Survey Knowledge Economy¶
Survey work produces information. Information is a commodity with real market value:
- Charted map coordinates (Pinpointed or Charted quality) can be sold to other players on the market as Map Items — specific item types that include route strips, site coordinates, and area charts. A Charted ore vein or a previously unknown site location is worth significant coin to players who need that resource or site access.
- Route confirmation improves expedition resolver outcomes for every player using that route — including players who did not run the survey themselves, once the chart is sold or shared.
- Survey skill improves Recipe Parchment discovery probability during high-tier expeditions. A Surveyor in a party increases the chance of rare item drops from the site's loot table. This is a direct mechanical incentive to develop survey skills even for players primarily interested in crafting or combat.
- Seasonal and den drift means charts go stale. A fresh herb-patch coordinate sold during Spring retains value. The same coordinate in Winter may be worthless because the patch has drifted — creating recurring demand for re-survey work across seasons.
When first selecting a Survey expedition type, the expedition setup screen displays a brief summary of these value paths so the player understands what their output is worth before committing.
Core Exploration Loop¶
- choose a survey target or route
- bring scouting tools, supplies, and specialists
- travel and resolve route events
- discover or confirm tiles, sites, hazards, and monster presence
- return with new map knowledge, chart data, coordinates, or rumors
- use, share, or sell the information
Survey Mechanics¶
Discovery Chance Indicator¶
The expedition setup screen for Survey-type expeditions displays a qualitative Discovery Chance indicator, updated live as the player adjusts their Survey skill investment and destination:
| Indicator | Meaning |
|---|---|
| Low | Surveying Untrained or Familiar; route is stable/known |
| Moderate | Surveying Practiced or Skilled; route has meaningful unknowns |
| High | Surveying Veteran or above; frontier or unstable zone |
| Very High | Surveying Expert or Master; deep wilderness or crisis-state region |
This indicator does not expose the exact tile-reveal formula — it gives the player a directional signal so they can make an informed decision before committing. It applies to general map discovery. For Recipe Parchment discovery during high-tier expeditions, see recipe-discovery.md.
How Survey Works in an Expedition¶
A Survey expedition type instructs the expedition resolver to run tile-reveal logic against the route traveled. The reveal logic operates per-tile:
- the character's Surveying skill band determines the tile reveal count — how many tiles are fully revealed per survey point
- the survey method (route strip, area sweep, or site verification) determines which tiles around the path are candidates
- Cartography skill determines how accurately those revealed tiles are packaged into a shareable chart
Surveying Skill — Tile Reveal Count¶
| Skill Band | Tiles revealed per survey point | Notes |
|---|---|---|
| Untrained | 1 | Only the tile currently occupied is confirmed; neighbors remain unknown |
| Familiar | 2 | Occupied tile + 1 adjacent tile |
| Practiced | 3–4 | Corridor travel: occupied + both flanking tiles |
| Skilled | 5–6 | Can sweep a hex cluster; 2-hex-deep corridor |
| Veteran | 8 | Can cover full hex ring around current position |
| Expert | 10–12 | Double ring; useful for wide-area surveys |
| Master | 14+ | Near-saturation of adjacent tiles; enables high-confidence area chart in fewer survey stops |
A survey "point" is one deliberate stop in the expedition to observe and record. An expedition can have multiple survey points; total tile count is the sum across all points. Traveling without stopping yields only Traversed fog state (see map-tiles-fog-and-cartography.md), not full Explored or Charted.
Survey Method¶
| Method | Tile pattern revealed | Best For |
|---|---|---|
| Route Strip | Narrow corridor of tiles along the traveled path | Road confirmation, route security assessment |
| Area Sweep | Hex cluster centered on survey position | Resource site discovery, new zone entry |
| Site Verification | Single tile or site to maximum confidence | Confirming a rumored site, refreshing stale data |
Method is selected by the player at expedition planning time and recorded in the expedition data. Mixed methods are possible if the player builds in multiple survey stops with different intents.
Discovery Quality¶
Not all discoveries are equally confident. The resolver assigns a discovery_quality value to each discovered item.
| Quality | Meaning | Created By |
|---|---|---|
| Rumored | Low-confidence; possibly present | NPC rumors, Traversed fog state, second-hand reports |
| Located | Item confirmed present with approximate position | Practiced+ survey, area sweep |
| Pinpointed | Exact tile known, accessible | Skilled+ survey, area sweep, or site verification |
| Charted | Exact tile, accessibility note, extraction estimate, freshness stamp | Expert+ Cartography packaging of Pinpointed data |
A Rumored entry can be used as a destination hint but not as the basis for a gather expedition without at least Located confirmation. A Charted entry gives full navigation data and is the primary trade-value tier for coordinate sales.
Site Template Matching¶
When the resolver discovers a tile that contains a harvestable resource, a monster den, or a ruin, it checks whether that tile matches a site_template from the world generation table. The match determines the full content profile of the site (resource types, quality tier, den family, ruin depth). Only Charted quality reliably reveals the full profile; lower quality shows partial information.
Resource Depletion and Drift¶
Depletion by Resource Type¶
| Resource Type | Base Depletion Rate | Recovery Model |
|---|---|---|
| Iron ore vein | 10% per extraction event | Full recovery in ~20 real days if untouched; partial at 7 days |
| Rare ore (silver, deep iron) | 20% per event | Full recovery in ~40 real days |
| Herb patch (common) | 15% per gather event | Seasonal reset in 7 real days |
| Herb patch (rare) | 25% per event | Seasonal reset in 14 real days |
| Clay deposit | 5% per event | Very slow depletion; practical recovery in ~10 days |
| Timber (logging zone) | Defined by felling quota; per zone | Active zones replenish at 3% of total stock per day if quota not exceeded |
| Monster den | Den weakened by kill events; collapses on Boss kill | Migrates to a new site after collapse; new location unknown until re-surveyed |
| Fish school | 8% per day fished heavily | Rests if unfished; full recovery in 4–5 days |
| Seasonal hunting ground | Depletes within a season window | Rotates to a different tile at season change |
Depletion visibility: A site's remaining yield is not shown directly. Players infer depletion from reduced extraction outputs and from Freshness warnings on their chart data (see Chart Freshness below).
Den Migration¶
When a monster den is fully cleared (boss kill or sufficient cull events), the den record enters a migrating state. After 1–3 real days, the server assigns a new valid tile within the same biome zone. The new site starts as Unknown fog state — it must be re-surveyed to be usable or tradeable.
This is the primary mechanism that keeps survey work perpetually relevant even in settled areas.
Seasonal Site Drift¶
Herb fields and seasonal hunting grounds track a season_phase value tied to the global season clock. When the season advances, any site marked as season_constrained has its tile reassigned to a new valid tile within valid biome bounds. The reassignment is randomized. Previous chart data for the tile is marked Stale, and new survey work is required.
Chart Freshness¶
Charted tile data ages. A freshness value of 1.0 means the tile was just surveyed; below 0.3 is considered Stale.
freshness_loss = base_decay_rate × (days_since_survey / 7) × freshness_event_modifier
| Tile or site type | Base decay rate per 7 days | Notes |
|---|---|---|
| Road tile | 0.05 | Roads stay reliable; minor freshness loss |
| Open terrain | 0.10 | Moderate drift |
| Forest tile | 0.15 | Creature presence and undergrowth shift |
| Mineral vein | 0.20 | Depletion is real; stale charts overstate yield |
| Herb patch | 0.25 | Seasonal drift accelerates staleness |
| Monster den | 0.30 | Active dens migrate; chart freshness degrades fast after a cull event |
| Dynamic event tile | 1.0 / event | Any active dynamic event immediately marks the tile's chart Stale |
Freshness event modifier: When a known event (raid, storm, magical surge) affects a tile, the event system may apply a multiplier of 2.0–5.0 to the freshness loss for that tick. This reflects the real-world situation where a confirmed survey becomes unreliable after a major disturbance.
Discoverable Content¶
| Category | Biome Affinity | Discovery Value |
|---|---|---|
| Iron ore vein | Rocky hills, hills, mountain | Permanent gather income; high route multiplier impact |
| Rare ore (silver, deep iron) | Mountain, mountain peak | Very high value; supports advanced crafting tiers |
| Common herb patch | Forest, plains, marsh edge | Alchemy and medicine supply |
| Rare herb (altitude or deep forest) | Mountain slope, dense forest interior | Premium alchemy; codex value |
| Fish school | River, lake shore, ocean coast | Reliable food supply; seasonal variation |
| Monster den | Biome-specific per family | Threat mapping; hunt order supply |
| Barrow or expedition site | Settlement edge, old road junction | One-time site reward; codex and recipe unlocks |
| Caravan shortcut | Between biomes, terrain-dependent | Route time reduction; significant logistics value |
| Seasonal hunting ground | Plains, forest edge, hills | Hunt supply; meat and trophy sourcing |
| Water source | Canyon, mountain, underground | Expedition supply station; settlement support |
| Hazard zone | Marsh, unstable terrain | Negative discovery — marks avoidance areas |
Dynamic events can temporarily create, hide, move, or intensify these discoveries. A goblin surge displaces herb gatherers and may reveal previously blocked-off ruins. A flood can expose alluvial ore. A magical surge can create an anomalous site that does not match any known template — these are unique and resolve after the event ends.
Tradable Coordinates and Map Items¶
Map Item Types¶
| Item | Contents | Typical Value |
|---|---|---|
| Route Strip | A narrow corridor of charted tiles along a road or trail | Low–Medium; useful for route planning |
| Zone Chart | A cluster of charted tiles covering a hex area | Medium; zone entry data |
| Site Coordinates | Pinpointed or Charted entry for a specific resource site | High if site is active, rare, and confirmed fresh |
| Hazard Report | Warning data for an unstable, hostile, or contaminated tile | Low coin but standing value with Hall and Physician |
| Site Map | Partial or full interior chart of an expedition site | High; enables preparation, reduces attrition on first run |
| Bestiary Survey | Den location + species confirmed + patrol data | Medium–High; required for Bounty contract submissions |
Map Sale Channels¶
- Archivist Gwydnila — standing buy for any Charted or Site Coordinates quality entry; pays a fixed reference price scaled to rarity and freshness. Primary channel for solo explorers who do not want to negotiate.
- Adventurers Hall survey board — buy orders posted by Hall or guilds requesting specific area coverage. Player fills the request with qualifying chart data; pays the contracted price.
- Player-to-player direct trade — map items are standard inventory items. They can be traded directly or sold through the exchange warehouse. Market price is established by settlement history.
- Guild archive deposit — players who deposit map data into their guild archive earn standing credit with the guild. The archive data becomes available to all guild members who meet the access tier.
- Senaax the Seer — premium buyer for rare-site data, anomalous tiles, and dungeon maps. Pays above Gwydnila's reference price but only buys from characters with Civic Standing of Recognized or higher.
Knowledge Publishing¶
When chart data is published to the Archivist or deposited to the guild archive, the underlying tile knowledge is locked to that snapshot. If the site subsequently changes (depletion, drift, event), the chart item's data becomes Stale while the new ground truth is different. Buyers who use Stale chart data discover the discrepancy only when they arrive at the site — there is no automatic notification.
This is a designed incentive to re-survey rather than rely on old data, and it gives surveyors a recurring income stream on high-traffic areas.
Town Demand Integration¶
Exploration is not isolated from the economy. Town demand drives exploration need.
Medicine shortage: When Trevalkaan's medicine reserve drops below Stable, Physician Kaisaarul may post a Herb Survey order requesting confirmed locations for two or more of the current ration-deficient herbs. This order pays above the normal survey rate and rewards standing with the Shrine Quarter.
Construction project active: When a civic project enters the Build phase, the construction board generates survey orders for nearby stone and timber sources if current supply chains are insufficient. Completing those surveys feeds directly into gather expedition routing.
New village area unlock: If a village security band drops to Threatened or below, the Branch Warden may post a Hazard Survey order to map the threat source location. A complete hazard report is required before the Relief Force order can be targeted correctly.
Exploration as board supply: Survey completion logs feed the discovery system, which in turn feeds the board's order generation engine. A new ore vein discovery automatically creates a Gather order on the board for that site's material. A newly located den generates a Hunt order if the den family is in a threatened state for the region.
Technical Model¶
Core Data Tables¶
| Table | Stores |
|---|---|
map_area |
Named areas with biome type, threat rating, and region assignment |
map_tile |
Individual hex tiles with terrain type, water coverage, and coordinate data |
site_template |
World-gen-authored site profiles (resource types, quality, respawn rules) |
site_instance |
Active site record derived from a template; tracks depletion state and current tile |
route_record |
Confirmed route between two points; includes difficulty, distance, and last-verified date |
map_item |
In-game tradeable chart or coordinate package; includes snapshot of tile data and freshness at time of creation |
tile_snapshot |
Immutable copy of tile data taken when a chart was generated; compared to live data to compute staleness |
map_sheet |
Multi-tile chart item; references a set of tile_snapshots within a geographic bound |
character_tile_knowledge |
Per-character fog state record; one row per tile per character |
guild_map_archive_entry |
Per-guild per-tile chart data and access control |
resource_depletion_state |
Per-site depletion percentage; updated on each extraction event |
Discovery Rules in the Resolver¶
When a Survey expedition resolves:
- For each survey point recorded in the expedition, compute revealed tiles from Surveying band and method
- Advance each revealed tile's fog state to Explored or Charted as appropriate
- For each Charted tile, run site template matching; record any site discoveries to
site_instance - For each new discovery, compute
discovery_qualityfrom skill bands and survey method - Write character tile knowledge rows; write map_item(s) into the character's inventory based on Cartography output
- Apply freshness stamp to all generated chart data
- If any site matches a pending board survey order, mark the order eligible for completion proof
Chart Package Generation¶
Cartography skill determines whether the resolved discovery data can be packaged into a tradeable item:
| Cartography Band | Output |
|---|---|
| Untrained | No chart items generated; tile knowledge written to character only |
| Familiar | Route strip possible; single tile items only |
| Practiced | Zone charts possible; up to 4-tile packages |
| Skilled | Full zone charts; multi-site packages; hazard notes |
| Veteran | High-quality zone charts with confidence rating and route overlay |
| Expert+ | Dungeon maps; bestiary survey packages; publishable to Archivist |
Depletion and Drift Updates¶
Depletion runs on the extraction event trigger, not on a clock. When a character submits a Gather expedition result, the resolver decrements resource_depletion_state.current_yield_fraction by the extraction rate for that resource type.
Drift (seasonal herb move, den migration) runs on the daily settlement tick. The tick checks all site_instance records against their drift_rule field and applies migration or reset logic when the season phase advances.
Store:
map_areamap_tilesite_templatesite_instanceroute_recordmap_itemtile_snapshotmap_sheetcharacter_tile_knowledgeguild_map_archive_entryresource_depletion_state
Use character_tile_knowledge as canonical per-player exploration record. Higher-level map summaries can be derived read models, not separate authoritative knowledge tables unless later docs define them explicitly.
Discovery Rules¶
Survey resolution should generate structured discoveries. A discovery should point to a site or route entity with quality and freshness, not just raw text.
Tradable Coordinates¶
A tradable coordinate or map item should reference a structured site record plus the finder quality. Lower-quality maps can include vague or stale locations, while high-quality maps are more precise and current.
Town Demand Integration¶
If a town needs iron, salt, water, herbs, or timber, its boards and market demand should favor exploration or mapping of sites that can solve that shortage.
Event-linked demands should amplify this further, creating short-lived map and discovery opportunities tied to current conditions.
Related Systems¶
- monster knowledge and encounter tables
- regional markets and map sales
- resource extraction and crafting
- town project planning and caravan routes