25 KiB

Raw Blame History

Change Request CR-026 — Random Events, Radio Calls, and Hull Condition

Numbering note (added when recorded): this request arrived titled "CR-024 — Random Events, Radio Calls, and Hull Condition" for "Phase 24". CR-024 (Fleet Sleep Mode) and CR-025 (Short Away Summary), and Phases 24 and 25, already existed, so it is stored as CR-026 and done as Phase 26: every "24.n" below means 26.n. Its references map to this repo as: "Phase 13 and CR-001 through CR-023" = Phase 13 and CR-001 to CR-025; CR-001 and CR-004 are the same numbers; "CR-005 cargo goods" = CR-007; "CR-006 ship upgrades" = CR-009; "CR-011 local-first" = CR-014; "CR-014 fixed map and fuel tanks" = CR-015; "CR-015 Venus, Jovian moons, belt" = CR-016; "CR-018 completable jobs" = CR-019; "CR-019 independent pilots" = CR-021; "CR-021 shop rest" = CR-023; "CR-022 fleet sleep" = CR-024; "CR-023 away summary" = CR-025. Plan sections 0.3, 0.5 and 12 are the same. Its new decisions CR-024.D1–D9 are recorded as 0.5.143–0.5.151 (D1 = 0.5.143 … D9 = 0.5.151).

On recording: "HQ" is the Bridge (the dashboard), as in CR-021, CR-024 and CR-025. Plan Steps 3.13 (dispatch record creation) and 3.17 (dispatch resolution) are the same numbers.

Project: Deadhead: Space Freight Tycoon Applies to: a build with Phase 13 and CR-001 through CR-023 complete Do this: as Phase 24 Related docs: game-design-document.md §13–14, change-request-pilot-rest.md (CR-004), change-request-cargo-goods.md (CR-005), change-request-ship-upgrades.md (CR-006), change-request-local-first.md (CR-011), change-request-fixed-map-and-fuel-tanks.md (CR-014), change-request-venus-jovian-moons-belt.md (CR-015), change-request-completable-jobs.md (CR-018), change-request-independent-pilots.md (CR-019), change-request-shop-rest.md (CR-021), change-request-fleet-sleep.md (CR-022), change-request-away-summary.md (CR-023), DECISIONS.md

This change request is written for the local-first engine (CR-011).

1. Why

Flying freight should occasionally be eventful, like American Truck Simulator: a debris field, a storm over Jupiter, a distress beacon, a drifting cargo pod worth salvaging. Events give players a reason to check in and something to look forward to, and they give the hull rating and cargo skills a real job.

Decisions from the design discussion:

If the player doesn't answer a radio call in time, the pilot picks the cautious option. Checking in pays off, and idle play never stalls.
Events can damage hulls. Ships get a condition meter, and repairs cost credits and shop time at an HQ. This is also the money sink the economy has been missing. No ship or pilot is ever lost.
Good events too, about one for every two bad ones, so events read as stories, not taxes.
Events are occasional. Most trips are quiet, short hops almost always are, and no ship gets events back to back.

2. How events work

Rolled at dispatch

When a trip starts, the game decides from the trip's seed whether an event will happen, which one, when, and the outcome of every option. Answering a radio call picks among pre-rolled outcomes, so reloading or waiting can't change the result. Catch-up stays deterministic (CR-011, CR-019).

Two kinds

Automatic: just happens and is reported (a flare delay, a tailwind, a micrometeor scratch).
Radio call: the pilot asks for a decision between two or three options, each with clear effects.

Radio calls and the response window

A radio call fires at a pre-rolled point between 20% and 70% of the trip.
The ship keeps flying while waiting. The response window is 30 real minutes, or the time left until arrival if that's shorter.
If the player answers in time, that option's pre-rolled outcome applies. If not, the event's default (cautious) option applies when the window ends.
Effects apply from the moment the event fired. For example, a 3-hour detour pushes arrival back by 3 hours.
Independent pilots (CR-019) get the same radio calls and the same window; the player can answer theirs too. Unanswered, they take the default.
Defaults are chosen so that good events give a small gain by default and a bigger one only if the player answers. That's the reason to check in.

Pacing (so events stay special)

Rule	Default
Events per trip	At most one
Chance per trip	`min(35%, 2% + 0.4% × trip game hours) × route multiplier`
Route multipliers	Earth↔Moon and Jupiter-system local loop ×0.5; legs crossing the asteroid belt ×1.3; arrivals at Jupiter system or Venus ×1.2 (multipliers stack)
Ship cooldown	After any event, that ship has none on its next 2 trips
Fleet pacing	At most one radio call per 45 real minutes across the whole fleet. A radio call rolled inside that window is dropped (the trip is quiet).
Good to bad	Weights give roughly 1 good event for every 2 bad ones
Tutorial	No events
Grace period	No events on the player's first 3 trips after the deal
First event	The first event a company ever gets is the Derelict Cargo Pod radio call (a good one), on the next eligible trip of at least 6 game hours, so the system is introduced with a reward

Balance targets (Step 24.9): 8–15% of all trips in a typical mid-game fleet get an event; Earth↔Moon runs 3% or less; long hauls 35% or less.

3. Event catalog (starting values, all in content)

"Hull damage" amounts are reduced by the ship's hull rating (§4). Payout losses never take a job below zero, and a contract always completes.

Bad and neutral events

Id	Kind	Can happen on	Effect or options (default in bold)
`solar-flare`	Automatic	Legs of 24+ game hours	+2 to 4 h delay
`micrometeor-strike`	Automatic	Legs of 24+ game hours	Hull −5 to 10%
`engine-hiccup`	Automatic	Any leg; 2× as likely if hull is below 50%	+1 to 2 h delay
`debris-field`	Radio call	Legs crossing the asteroid belt	Go around: +3 h · Push through: 35% chance hull −10 to 20%, 10% chance lose 10% of cargo pay, otherwise no delay
`storm-approach`	Radio call	Arrivals in the Jupiter system or at Venus	Hold in orbit: +3 h · Land now: 40% chance hull −10 to 15%
`customs-hold`	Radio call	Arrivals at Earth or Mars	Pay the inspection fee: 3% of payout (min 100 cr) · Wait it out: +5 h
`hazmat-leak`	Radio call	Dangerous cargo; chance halved for each Dangerous Cargo level above the job's tier	Vent part of the load: lose 15% of cargo pay · Seal it and slow down: +2 h, 30% chance hull −10%
`load-shift`	Radio call	Heavy cargo; chance halved for each Heavy Cargo level above the job's tier	Re-secure: +2 h · Keep going: 25% chance lose 10% of cargo pay
`spoilage-risk`	Radio call	Priority contracts with perishable goods (Hydroponic Produce, Cloud-Grown Botanicals, Medical Supplies, Subsurface Ocean Samples)	Push the engines: burn 15% more fuel for the leg, keep the window (if fuel aboard; otherwise the other option is the default) · Ease off: +2 h, may miss the Priority window

Good events

Id	Kind	Can happen on	Effect or options (default in bold)
`solar-tailwind`	Automatic	Legs of 12+ game hours	−1 to 2 h (never below 50% of the trip)
`grateful-client`	Automatic	Any contract	+10% tip on delivery
`derelict-pod`	Radio call	Any leg of 6+ game hours	Salvage it: +1 h, bonus cargo worth 15–40% of the job's payout, paid on delivery (needs 10% free hold space) · Log it and fly on: +5% of payout as a salvage-rights fee
`distress-beacon`	Radio call	Any leg of 12+ game hours	Stop and help: +4 h, reward 20–50% of payout and +50% XP for the trip · Relay the coordinates: +5% of payout
`spot-freight`	Radio call	Any leg passing within the inner system or belt	Take on a small extra load: +1 h, +15–25% of payout (needs 10% free hold space) · Pass

Missing a Priority window because of an event removes the Priority bonus only; the base payout is still paid.

4. Hull condition and repairs

Rule	Detail
Condition	Every ship has a hull condition from 0 to 100%. New ships start at 100%. Condition never goes below 5%: ships are never destroyed.
Hull rating	Each point of hull rating reduces both the chance and the amount of hull damage by 10% (max 50%).
Below 50%	The ship can't take Dangerous cargo. In the dispatch sheet: "Hull too damaged for hazardous cargo: repair at an HQ". This is a temporary condition for CR-018 (jobs aren't hidden).
Below 25%	Hull damage chances from events are doubled, and the Fleet card shows a red "Needs repair" warning.
Repairs	At an HQ, using the CR-006 shop: cost = missing condition % × ship model price × 0.5% per point; shop time = 1 real minute per 2% missing (min 5 minutes). Always repairs to 100%. Shop time counts as rest (CR-021).
Hull Plating upgrade	The upgrade deferred in CR-006 is added: +1 hull rating per level, three levels, same cost and shop-time rules as other upgrades.

5. Notifications and UI

Notifications (native): for trips the player dispatched, a local notification is scheduled at each radio call's fire time: "Debris field ahead — Rosa needs a call." Independent pilots' trips are decided during catch-up, so they can't be scheduled ahead (as in CR-019). Respects the Notifications toggle and fleet sleep (CR-022 doesn't suppress events on trips already in flight).
Radio calls in the app: a radio-call card with the event text, options and their effects, and a countdown. Several pending calls queue as "Radio calls (2)". HQ shows a badge while any are pending. Answering is a manual decision (CR-022).
Results: automatic events and answered or defaulted calls appear in delivery summaries, the Logbook (CR-023), and as highlights in the "while you were away" pop-up (good outcomes and hull damage rank just below discoveries and level-ups).
Ship status: Fleet cards show a hull condition bar; ship detail has Repair when at an HQ and below 100%.

6. Rules for this change

All rules in implementation-plan.md §0.1 apply: steps in order, one commit per step, each step's test must pass, packages/sim stays pure, all numbers and event text live in packages/content.
The event roll, outcome pre-rolls, and outcome application are pure functions in packages/sim.
The answer command and the repair command are manual decisions (CR-022 flag).
Save migration: every ship's hull condition is 100%; dispatches already in flight get no event; the company is marked as not having had its first event.
Update architecture.md and progress.md as you go. Stop for the user's review at the end of Phase 24.

7. Decisions

Record these in DECISIONS.md and implementation-plan.md §0.5, using the next free numbers (labeled CR-024.D1–D9 here; note the mapping).

CR-024.D1 Events rolled at dispatch, including every option's outcome, from the trip seed.
CR-024.D2 Radio calls with a response window of 30 real minutes or the time left, whichever is shorter; the default (cautious) option applies if unanswered.
CR-024.D3 Pacing per §2: one per trip at most, chance by trip length and route, 2-trip ship cooldown, one radio call per 45 real minutes fleet-wide, no events in the tutorial or the first 3 trips after the deal, first event is the Derelict Cargo Pod.
CR-024.D4 Catalog per §3, roughly one good event per two bad.
CR-024.D5 No total losses. Contracts always complete; cargo losses reduce pay; ships never go below 5% condition.
CR-024.D6 Hull condition and repairs per §4.
CR-024.D7 Hull Plating upgrade added (+1 hull rating per level).
CR-024.D8 Notifications for radio calls on player-dispatched trips (native only).
CR-024.D9 Independent pilots get the same events and defaults.

Removes "random events" from the deferred list (implementation-plan.md §0.3).

8. Steps — Phase 24

Step 24.1 — Content

Add the event catalog (§3): id, kind, eligibility conditions, weight, good/bad flag, text, options with effects and outcome chances, default option. Add pacing config (§2), hull and repair config (§4), and the Hull Plating upgrade.
Test: Content validates. Every radio call has exactly one default. Every option's chances sum to at most 100%. Good-event weight is about one third of the total (between 28% and 38%).

Step 24.2 — Sim: event roll at dispatch

A pure function that, given the trip (route, cargo, ship, pilot, durations), the ship's recent event history, the fleet's scheduled radio calls, and the company's event state, returns either "quiet" or an event with fire time, options, pre-rolled outcomes, and default.
Test: Same inputs give the same result. No events in the tutorial or the first 3 trips after the deal. The first event is the Derelict Cargo Pod on the first eligible 6+ hour trip. No event on a ship's next 2 trips after one. No two radio calls within 45 real minutes across the fleet. Over 100,000 simulated trips: Earth↔Moon events at 3% or less, long hauls at 35% or less, and eligibility rules respected (no hazmat leaks without Dangerous cargo, no debris off belt-crossing legs, and so on). Higher Dangerous/Heavy skill lowers leak/shift rates as specified.

Step 24.3 — Sim: applying outcomes

A pure function that applies a chosen (or default) option's pre-rolled outcome: delay or speed-up to arrival, hull change, cargo pay change, bonus pay, extra XP, extra fuel burn, Priority window check.
Test: A 3-hour detour moves arrival by exactly 3 game hours from the fire time. A tailwind never shortens a trip below 50%. Cargo losses never make pay negative. A delay past the Priority window removes only the Priority bonus. Salvage and spot freight require 10% free hold space; without it, those options are unavailable. Choosing an option always yields its pre-rolled outcome, whenever it's chosen.

Step 24.4 — Sim: hull condition and repairs

Pure functions: damage after hull rating (including Hull Plating) and the below-25% doubling; condition floor at 5%; repair cost and shop time.
Test: Hull rating 3 reduces a 20% hit to 14%. Condition never goes below 5%. A ship at 40% can't take Dangerous cargo (dispatch reason). Repair cost and time match the formulas.

Step 24.5 — Engine: events in play and catch-up

Dispatch stores the rolled event on the dispatch record. The resolution loop and catch-up fire events at their time; automatic events apply immediately; radio calls become pending until answered or the window ends, then apply.
Commands: answer radio call (manual decision), repair ship (uses the shop, manual decision).
Independent pilots' trips use the same flow.
Save migration per §6.
Test: From the same save, catching up 8 hours in one go and in pieces gives identical results, including defaulted calls. Answering within the window applies the chosen outcome; answering after it fails. An Independent pilot's unanswered call takes the default. Repairing at an HQ restores 100%, charges the right cost, and puts the ship in the shop; repairing away from an HQ fails.

Step 24.6 — Client: radio calls

The radio-call card (§5) with options, effects, and a countdown; the queue when several are pending; the HQ badge.
Test: Component tests: a pending call shows its options and countdown; answering calls the engine and removes it from the queue; an expired call disappears and its result appears in the summary; two pending calls show "Radio calls (2)".

Step 24.7 — Client: hull and results

Hull condition bar on Fleet cards, "Needs repair" warning below 25%, Repair in ship detail at an HQ, the Hull Plating upgrade in the upgrade shop, and the dispatch reason for damaged hulls with Dangerous cargo.
Event results in delivery summaries, the Logbook, and as "while you were away" highlights per §5.
Test: Component tests for each element with seeded state; highlight ordering matches §5.

Step 24.8 — Notifications

Schedule radio-call notifications for player-dispatched trips at fire time; cancel if the trip or company changes; respect the Notifications toggle.
Test: With a mocked scheduler: a dispatch with a rolled radio call schedules one notification at its fire time; a quiet trip schedules none; an Independent pilot's trip schedules none; turning notifications off cancels them.

Step 24.9 — Balance

Extend the Phase 12 balance script with events on.
Targets: 8–15% of trips have an event in a typical mid-game fleet; good-event share 28–38%; a player who always takes defaults earns at least 93% of the no-events baseline; a player who answers every call well earns at least as much as the no-events baseline; repairs cost 5–10% of mid-game income. Tune weights, chances, and repair cost, not the targets.
Test: All targets met with default content. All CR-001, CR-019, and CR-022 timing and income targets still hold.

Step 24.10 — Plan amendments and regression

Apply the amendments in §9.
Run the full suite.
Test: CI is green. Manual check: on a fresh account, fly past the grace period and confirm the first event is the Derelict Cargo Pod; answer it; later, let a radio call expire and confirm the default applied; damage a hull and repair it at an HQ.

9. Amendments

Where	Change
Plan 0.3	Remove "random events" from deferred.
Plan 0.5	Add CR-024.D1–D9.
Plan 3.13, 3.17	Dispatch records carry an event; resolution applies its outcome (24.2–24.5).
CR-006	Hull Plating upgrade added.
CR-011	Resolution loop and catch-up fire events; notification scheduler adds radio calls.
CR-018	Hull below 50% is a temporary reason, not a hidden-job rule.
CR-019	Independent pilots get events and defaults.
CR-022	Answer and repair are manual decisions.
CR-023	Event results become highlights.
`game-design-document.md` §13	Updated by the designer.

Amendments

Amended by CR-027: Hull damage and wear that take an Independent crew's hull below the auto-repair threshold (40% by default) book a repair at the nearest reachable HQ; Manual crews see "Repair recommended".
Amended by CR-028: Event outcomes are toasts while the player is here; radio calls keep their card.

10. Out of scope

Losing ships or pilots, insurance, piracy, reputation effects, multi-step event chains, events at docked locations (depot shortages, price spikes), pilot traits that change defaults, and anything else in implementation-plan.md §0.3.

25 KiB Raw Blame History Unescape Escape