rory
/
deadhead-space-freight-tycoon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
deadhead-space-freight-tycoon/memory-bank/change-requests/CR-010-veteran-pilot-profit...

9.3 KiB
Raw Blame History

Change Request CR-010 — Inherited Veteran Pilot and Profit-Share Pay

Numbering note (added when implemented): this request arrived titled "CR-007 — Inherited Veteran Pilot and Profit-Share Pay" for "Phase 10G", applying to "CR-001 through CR-006". CR-007 to CR-009 and Phases 10G–10I already existed, so it is stored as CR-010 and done as Phase 10J: every "10G.n" below means 10J.n. Decision 0.5.12 is replaced in place; the new 0.5.51 and 0.5.52 are recorded as 0.5.69 Deduction order and 0.5.70 Veteran pilot (0.5.51–0.5.68 were in use). "CR-001 decision 0.5.24" (the loan) is plan §0.5.32 in this repo. "CR-001 through CR-006" means the build as it stands (CR-001 to CR-009).

Project: Deadhead: Space Freight Tycoon Applies to: a build with Phases 1–10 and CR-001 through CR-006 complete Do this: as Phase 10G, after Phase 10F and before Phase 11 Related docs: implementation-plan.md, change-request-faster-start.md (CR-001), change-request-pilot-rest.md (CR-004), game-design-document.md, DECISIONS.md

1. Why

Two related changes to pilots:

  1. The deal comes with a veteran pilot. The player takes over the retiring owner's business, so his last hire comes with it. Today, when the avatar must rest, the player's only ship sits idle. With a second pilot at the Earth HQ, the player can swap crews and keep flying, which teaches the rest-and-swap system in the first session. The veteran has a skill the avatar lacks (Heavy Cargo 1), so choosing who flies is a real decision.
  2. Hired pilots earn a share of profit instead of a flat fee. A flat per-delivery fee can eat most of a cheap Moon run, or more once fuel is counted. A share of profit (payout minus fuel) guarantees the business always keeps the larger share of a profitable job and never pays a pilot on a losing one.

2. How it works

The veteran

Rule Detail
When Created when the player accepts the CR-001 deal.
Where At Earth, unassigned. The avatar crews the Courier as before.
Who A fixed name and short bio from content (for example "Rosa Kell, Halvorsen's pilot for twelve years").
Level Level 2, with one skill point already spent on Heavy Cargo (Heavy Cargo 1) and the remaining earned points unspent.
Rules Same as any hired pilot: profit-share pay, duty and rest, assign and unassign only at a bay.

Profit-share pay

pilot pay = max(0, payout − fuel cost) × pilot profit share

Case Pilot pay
Hired pilot, profitable contract Profit share of (payout − fuel)
Hired pilot, fuel ≥ payout 0
Avatar 0 (exempt)
Deadhead or tutorial run 0

Example (default share 0.25): payout 400 cr, fuel 150 cr → pilot gets 62.5 cr, business keeps 187.5 cr before loan repayment.

Order of deductions on resolution: payout − pilot pay − loan repayment (CR-001 decision 0.5.24 applies to what remains after pilot pay). Fuel was already charged at dispatch.

3. 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 names live in packages/content.
  • Credits round the same way they already do elsewhere; use that rounding for pilot pay and say so in DECISIONS.md.
  • Resetting the dev and test databases is fine. Schema migrations are still required if any are needed.
  • Update existing tests whose expectations change. Update architecture.md for schema or API changes and progress.md after every step.
  • Stop for the user's review at the end of Phase 10G.

4. Decisions

Record these in DECISIONS.md and implementation-plan.md §0.5.

  • 0.5.12 (replaced) Pilot pay. Hired pilots earn max(0, payout − fuel cost) × pilot profit share per contract delivery. The avatar is exempt. Deadheads and tutorial runs pay nothing.
  • 0.5.51 Deduction order. On resolution: pilot pay is taken from the payout first; loan repayment (0.5.24) is calculated on what remains.
  • 0.5.52 Veteran pilot. Accepting the deal also creates the veteran per §2. The veteran is a normal hired pilot in every respect except how they were acquired.
  • CR-001 goal change. Goal 4 "Hire your first pilot" becomes "Fly a contract with [veteran's name]".
  • CR-001 timing target change. "Hire first pilot: 30–45 minutes" becomes "Buy a second ship: 30–45 minutes".

5. Steps — Phase 10G

Step 10G.1 — Content: config and veteran

  • Replace the GameConfig field "pilot pay per delivery (flat fee)" with "pilot profit share" (default 0.25, must be between 0 and 1).
  • Add a veteran pilot entry: name, short bio line, starting level (2), and starting skill allocation (Heavy Cargo 1).
  • Test: Config validates; the profit share is between 0 and 1. The veteran's starting skill allocation does not exceed the skill points a level-2 pilot has. The veteran's skill references an existing skill.
  • Amended by CR-013: The veteran's starting skill is Expensive Cargo 1 (Step 10M.1).

Step 10G.2 — Sim: profit-share pay

  • Replace the flat fee in dispatch resolution with the profit-share formula (decision 0.5.12) and apply the deduction order (decision 0.5.51).
  • Test: A hired pilot on a 400 cr payout with 150 cr fuel earns 62.5 cr (with the project's rounding). Fuel greater than or equal to payout gives zero pilot pay. The avatar earns zero. A deadhead and a tutorial run earn zero. With a loan balance, repayment is calculated on payout minus pilot pay. Credits added + pilot pay + loan repayment = payout, for a range of inputs. Update the Step 3.17 tests that assumed a flat fee.

Step 10G.3 — Sim: goal change

  • Change goal 4 in the onboarding goals (CR-001 Step 10A.5) to "Fly a contract with the veteran": complete when any contract delivered by the veteran has resolved.
  • Test: The goal is incomplete when only the avatar has delivered and complete after one resolved contract flown by the veteran. A deadhead by the veteran does not complete it.
  • Amended by CR-013: Goal 4 is now "Complete a Priority contract", by any pilot (Step 10M.2).

Step 10G.4 — Server: veteran on the deal

  • Accepting the deal (CR-001 Step 10A.8) also creates the veteran per §2, in the same transaction.
  • Test: After accepting, state has exactly two pilots at Earth: the avatar crewing the Courier, and the veteran unassigned at level 2 with Heavy Cargo 1 and the correct number of unspent skill points. The veteran is not exempt from pilot pay. A failed or repeated accept creates no veteran. When the avatar must rest at Earth, the avatar can be unassigned and the veteran assigned to the Courier and dispatched immediately.
  • Amended by CR-013: The veteran starts crewing the deal's Clipper, not unassigned (Step 10M.3).

Step 10G.5 — Client: deal modal and pilot card

  • The deal modal (CR-001 Step 10A.13) lists the veteran by name with their bio line, for example "…and Rosa Kell, who's flown for me for twelve years."
  • The veteran's card on the Pilots screen shows the bio line.
  • Test: Component test: the modal shows the veteran's name and bio from content; the Pilots screen shows the veteran's bio, level, and Heavy Cargo 1.

Step 10G.6 — Client: pilot share in dispatch and summaries

  • The dispatch sheet shows a "Pilot share" line between fuel and net profit for hired pilots, and no line for the avatar. Net profit accounts for it.
  • Delivery summaries show the pilot's share as its own line when it's above zero.
  • Test: Component test: for a hired pilot the sheet shows the share and a net profit matching the sim; for the avatar there's no share line. A summary for a hired pilot's delivery shows the share line.

Step 10G.7 — Plan amendments and regression

  • Apply the amendments in §6 to implementation-plan.md and CR-001's text.
  • Run the full suite.
  • Test: CI is green. Manual check: on a fresh account, accept the deal and confirm the veteran is at Earth; fly the avatar until mandatory rest at Earth; swap in the veteran, take a Heavy contract the avatar couldn't, and confirm the summary shows the pilot share and goal 4 becomes claimable.
  • Amended by CR-013: The rest-and-swap manual check is replaced by CR-013's: accept the deal on a fresh account, dispatch the Courier and the Clipper at the same time, and complete a Priority contract with the Clipper to unlock goal 4 (Step 10M.5).

6. Amendments

Where Change
Plan 0.5.12 Replaced by profit-share pay (10G.2).
Plan 0.5 Add 0.5.51 and 0.5.52.
Plan 2.1 Config field change (10G.1).
Plan 3.17 Profit-share formula and deduction order (10G.2).
Plan 9.5 Pilot share line in the dispatch sheet (10G.6).
Plan 12.1 Replace "first pilot hired between 30 and 45 minutes" with "second ship bought between 30 and 45 minutes". Add a check that the veteran flies at least one contract in the first session. Re-check all targets with profit-share pay; adjust content values, not thresholds.
CR-001 10A.5 Goal 4 changed (10G.3).
CR-001 10A.8 Deal also creates the veteran (10G.4).
CR-001 10A.13 Deal modal lists the veteran (10G.5).
CR-001 §2 targets "Hire first pilot" target replaced as above.

7. Out of scope

Pay share that scales with pilot level, salaries, pilot morale or loyalty, pilots leaving or being poached, additional inherited assets, and anything else in implementation-plan.md §0.3.