Expedition Generation Model

Purpose

This file defines the concrete technical model for expedition offer generation.

Expeditions should not appear as a loose pile of hand-authored quests. They should be generated from structured base types, local state, targets, rewards, and event modifiers.

Core Rule

An expedition offer should be a resolved combination of:

• base_type
• board_source
• board_context
• region
• target
• urgency
• reward_class
• event_modifiers

Everything the player sees on a board should come from that contract plus compact display projections.

Offer Contract

Each expedition offer should have at least:

• offer_id
• template_id
• base_type
• region_id
• area_id
• board_source
• board_context_snapshot_ref
• target_type
• target_ref
• urgency_band
• source_priority_score
• town_urgency_score
• event_severity_score
• control_window_score
• reward_class
• difficulty_band
• recommended_group_size
• event_modifier_set
• generation_reason_tags
• expires_at
• seed

Optional but useful fields:

• required_knowledge_tags
• suggested_loadout_tags
• special_supply_tags
• event_instance_ref
• control_window_ref
• public_work_ref

Base Type

base_type should be one of the core expedition classes:

• Hunt
• Gather
• Survey
• Escort
• Rescue
• Delve
• Bounty
• Caravan
• Boss Omen Or Event Hunt

That field drives validation, reward composition, and board grouping.

Region And Area Binding

Every generated offer should bind to a real location context.

• region_id identifies the broader climate and economy context
• area_id identifies the actual target zone or route zone

This is what makes regional identity and town need matter.

Target Model

target_type should be explicit.

Recommended target types:

• monster_family
• named_target
• resource_site
• route_segment
• site_instance
• shipment
• survivor_group
• event_instance
• tile_cluster

target_ref should point to the authoritative source record, not to display text.

Urgency Model

Urgency should be a small readable band, not a hidden timer only.

Recommended bands:

• routine
• active
• urgent
• critical

Urgency should affect:

• board ordering
• expiry window
• reward multiplier
• event or town impact if ignored

Reward Class

Every offer should advertise a dominant reward class.

Recommended classes:

• loot
• materials
• knowledge
• renown
• state_stabilization
• mixed

This helps the board stay readable.

Event Modifier Set

Dynamic events should not create a separate expedition framework.

Instead, attach modifiers to the offer.

Examples:

• storm_window
• blight_response
• refugee_pressure
• route_disrupted
• predator_surge
• festival_demand
• quarantine_zone

Modifiers should be authoritative data, not display-only flavor.

They can affect:

• target availability
• difficulty
• urgency
• reward profile
• tile or route state

Board Context Snapshot

Offer generation should not read half a dozen live systems separately while scoring a board refresh. Each board source should first materialize one compact immutable snapshot.

Recommended snapshot fields:

• board_source
• source_ref
• town_ref if relevant
• town_urgency_score
• worst_reserve_class
• route_pressure_score
• highest_event_severity
• active_event_refs
• control_state
• control_window_ref if active or previewed
• control_window_phase
• control_window_score
• public_work_priority_refs
• generated_at

This snapshot becomes the single authoritative input for one generation run.

Direct Input Consumption

Mission boards should consume the new town, event, and governance signals directly rather than translating them back into vague flavor categories.

Town Urgency

Town boards and logistics-heavy boards should read the town pressure model as a normalized 0-100 score.

Recommended rule:

town_urgency_score = clamp(reserve_deficit × 0.45 + route_pressure × 0.20 + event_pressure × 0.20 + project_priority × 0.15 - recent_completion_relief, 0, 100)

Where the input terms come from the town simulation layer, not from expedition templates.

Town urgency should drive:

• how many board slots are reserved for stabilization work
• whether routine opportunities are suppressed by emergencies
• expiry windows for shortage-sensitive offers
• reward emphasis toward state_stabilization, materials, or mixed

Event Severity

The generator should read event_instance.severity_score directly.

Recommended rules:

• board_event_severity = max(severity_score) for active events visible to the board scope
• candidate_event_severity = linked event severity for event-bound offers
• non-event town offers may still inherit 25-50% of board_event_severity as spillover pressure if the event affects routes, reserves, or local safety

Event severity should drive:

• how many event-response offers appear
• whether the board spawns rescue, escort, survey, or hunt variants
• additional reward and danger modifiers
• how aggressive expiry windows become

Control Window Inputs

Guild and contested-town boards should read scheduled control windows directly from governance state.

Recommended rule:

control_window_score = clamp(phase_bonus + contested_bonus + destabilized_bonus + town_urgency_score × 0.25 + strategic_value_bonus, 0, 100)

Suggested phase bonuses:

• preview: 25
• active: 60
• closing: 80

Suggested state bonuses:

• contested: 10
• destabilized: 20

Control-window score should drive:

• guild-board patrol, escort, delivery, and survey offers
• emergency logistics and militia-support work on town boards when the settlement is contested
• renown and influence weighting for offers tied to the control window

Input Weight Table

Different boards should weight the same inputs differently.

Board Source	Town Urgency Weight	Event Severity Weight	Control Window Weight	Main Use
town_board	0.55	0.30	0.15	shortages, projects, local safety
guild_board	0.20	0.20	0.60	control windows, civic support, strategic prep
event_board	0.10	0.80	0.10	direct event response
regional_caravan_board	0.45	0.20	0.35	route recovery, supply movement, convoy defense
faction_board	0.30	0.40	0.30	regional security and policy pressure

Generation Inputs

Offer generation should pull from local and regional state such as:

• town deficits and surpluses
• route stability
• monster pressure
• active event instances
• undiscovered or stale tile clusters
• resource site availability
• guild or faction policy where relevant

The generator should prefer the precomputed board-context snapshot over rereading raw live tables during scoring.

Candidate Scoring Model

Each eligible offer candidate should receive a comparable priority score.

Recommended rule:

candidate_score = template_weight + board_source_weight + town_input + event_input + control_input + target_availability_bonus + scarcity_bonus + route_bonus - duplicate_penalty - saturation_penalty + seed_jitter

Where:

• town_input = town_urgency_score × board_town_weight
• event_input = candidate_event_severity × board_event_weight
• control_input = control_window_score × board_control_weight

Candidate score should decide:

• whether an offer appears this refresh
• how high it ranks on the board
• whether it upgrades from routine to active, urgent, or critical
• whether a board slot is consumed by a shortage response, control-window action, or background opportunity

Offer Shape By Input

The generator should bend base expedition types according to the direct inputs.

• high town_urgency_score from food, water, medicine, or building deficits should favor Gather, Caravan, Escort, and Survey offers tied to real supply relief
• high route pressure plus high event severity should favor Escort, Rescue, and Survey offers over generic hunts
• high monster pressure plus event severity should favor Hunt, Bounty, and Boss Omen Or Event Hunt
• active control_window_score should favor Escort, Caravan, Survey, Hunt, and Rescue variants that award influence or stabilize the settlement
• prosperity without crisis should unlock lower-urgency luxury, tournament, or opportunity offers instead of emergency work

Generation Flow

1. collect board scope and permissions from one town, guild, or area source
2. materialize one board_context_snapshot from town, event, route, and governance state
3. derive slot mix from board source plus town_urgency_score, highest_event_severity, and control_window_score
4. choose eligible base_type candidates by weighted rules
5. bind a valid target and area or route context
6. score candidates with direct town, event, and control-window inputs
7. calculate urgency band, difficulty band, reward profile, and expiry window
8. attach event modifiers, reason tags, and board ordering score
9. write offer projections, expire displaced offers, and cache the public board read model

This should happen on cadence or on meaningful local-state changes, not every time a player opens the board.

Board Mix Rules

Boards should not just sort a global candidate list. Each board source should reserve space for different mission families.

Town Board

Recommended size: 8-12 offers.

• 50% stabilization work when town_urgency_score >= 50
• 20-30% event-response work when an active local event exists
• 10-20% project or civic-support work
• remaining slots for routine local opportunities

If town_urgency_score >= 75, suppress most luxury or low-impact background offers.

Event Board

Recommended rule:

event_offer_slots = min(5, 1 + floor(candidate_event_severity / 25))

Each active event should try to expose multiple response vectors rather than one generic card: for example hunt, delivery, escort, survey, or rescue depending on the event family.

Guild Board

If a control window is active or closing:

• 55-65% control-window scoring work
• 20-25% civic stabilization work in the contested town
• 15-20% preparation or scouting work for the next wave

If no control window is active, the guild board should shift toward logistics, public works, and strategic prep instead.

Regional Caravan Board

Prioritize deficits, route disruption, and contested logistics. This board should react strongly when towns are strained, events break routes, or a control window puts caravan lanes at strategic risk.

Urgency, Expiry, and Reward Derivation

Urgency should be derived from the same direct inputs that created the offer.

Recommended rule:

offer_urgency_score = max(candidate_score, town_urgency_score, candidate_event_severity, control_window_score)

Map to visible bands:

• 0-24: routine
• 25-49: active
• 50-74: urgent
• 75-100: critical

Expiry guidance:

• routine: 24-72 hours
• active: 12-36 hours
• urgent: 6-18 hours
• critical: 2-8 hours

Reward guidance:

• town-urgency-driven offers should bias toward materials, reserve relief, renown, and civic reputation
• high-severity event offers should bias toward state_stabilization, rare drops, and high-risk payout
• control-window offers should bias toward renown, influence credit, treasury support, and route control rather than only raw coin

Refresh Triggers

Offer regeneration should run when one of these changes materially affects the board context:

• a town reserve class changes band
• route pressure or service state changes enough to alter board priority
• an event spawns, changes phase, changes severity band, or resolves
• a control window enters preview, active, closing, or resolved state
• a contested town becomes destabilized, controlled, or open
• a public work starts, stalls, or completes

This keeps boards synchronized with the simulation without refreshing on every page load.

Board Sources

Offers should originate from specific sources:

• town board
• guild board
• event board
• regional caravan board
• faction board

board_source matters because it affects permissions, reward type, and display grouping.

It should also affect which direct inputs dominate generation. A town board should never behave like an event board, and a guild control board should never ignore active control windows.

Offer Reason Tags

Each offer should store one or more machine-readable reason tags explaining why it exists.

Recommended tags:

• shortage:food
• shortage:medicine
• event:storm_surge
• event:predator_surge
• control:preview
• control:active_window
• control:closing_push
• project:granary
• route:washed_road

The client can surface one primary reason tag and keep the rest for filtering and tooltips.

Records

Templates And Rules

Store:

• expedition_template
• expedition_generation_rule
• expedition_reward_profile
• expedition_modifier_template
• expedition_board_mix_rule

Generated Offers

Store:

• expedition_board_context_snapshot
• expedition_generation_run
• expedition_offer
• expedition_offer_modifier
• expedition_target_ref
• expedition_board_projection
• expedition_offer_reason

Acceptance Snapshot

When a player accepts an offer, snapshot the offer into:

• expedition_instance
• expedition_acceptance_snapshot
• expedition_reward_commitment

The live expedition must not keep reading a mutable board offer after acceptance.

See unified-board-item-and-player-contract-model.md for how generated offers and player-posted contracts share one board-item projection. See expedition-acceptance-and-settlement-model.md for how accepted board items freeze into immutable expedition snapshots and settlement writebacks.

Validation Rules

The generator must validate that:

• the target still exists
• the area is still valid
• required event state is still active if event-bound
• required control window is still in a valid phase if control-bound
• the offer does not duplicate an already-open exclusive target unless intended
• the expiry window is long enough to be actionable
• the board-context snapshot is fresh enough for urgent and critical offers

Examples

Survey Offer

• base_type: Survey
• board_source: town board
• region_id: Ashwood Wilds
• target_type: tile_cluster
• target_ref: stale north-route tiles
• urgency_band: active
• town_urgency_score: 42
• event_severity_score: 18
• control_window_score: 0
• reward_class: knowledge
• event_modifier_set: route_disrupted
• generation_reason_tags: route:washed_road, shortage:building

Gather Offer

• base_type: Gather
• board_source: event board
• region_id: Frontier Marches
• target_type: resource_site
• target_ref: herb bloom cluster
• urgency_band: urgent
• town_urgency_score: 58
• event_severity_score: 67
• control_window_score: 0
• reward_class: materials
• event_modifier_set: blight_response
• generation_reason_tags: event:blight_response, shortage:medicine

Rescue Offer

• base_type: Rescue
• board_source: event board
• region_id: Frontier Mine Belt
• target_type: survivor_group
• target_ref: collapse incident 184
• urgency_band: critical
• town_urgency_score: 64
• event_severity_score: 83
• control_window_score: 0
• reward_class: state_stabilization
• event_modifier_set: route_disrupted, mine_collapse
• generation_reason_tags: event:mine_collapse, route:washed_road

Guild Control Escort Offer

• base_type: Escort
• board_source: guild board
• region_id: South March Road
• target_type: shipment
• target_ref: civic reserve grain convoy 44
• urgency_band: urgent
• town_urgency_score: 61
• event_severity_score: 25
• control_window_score: 78
• reward_class: mixed
• event_modifier_set: route_disrupted, control_window
• generation_reason_tags: control:active_window, shortage:food

Read Model Rule

The client should not render raw generation tables.

Expose compact board views such as:

• base type label
• destination or route
• urgency tag
• reward class
• primary reason tag
• event modifiers
• time remaining

That keeps the board readable in a browser UI.

Coordinator Rule

Use one local coordinator per board source where possible.

Examples:

• one town board coordinator per settlement
• one regional caravan coordinator per logistics hub
• one event board coordinator per area cluster

That keeps generation local and avoids one giant world quest scan.

Related Systems

• missions and expeditions
• expedition types
• unified board item and player contract model
• expedition acceptance and settlement model
• dynamic events and world state
• system simulation patterns
• town simulation and supply