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-018-fuel-tuning.md

7.3 KiB
Raw Blame History

Change Request CR-018 — Fuel Tuning

Numbering note (added when recorded): this request arrived titled "CR-017 — Fuel Tuning" for "Phase 17". CR-017 (tutorial XP and skill point prompt) and Phase 17 already existed, so it is stored as CR-018 and done as Phase 18: every "17.n" below means 18.n. Its references map to this repo as: "Phase 13 and CR-001 through CR-016" = Phase 13 and CR-001 to CR-017; "CR-014 fixed map and fuel tanks" = CR-015 (its steps 14.n are 15.n; its §3 and §4 are CR-015 §3 and §4; its "CR-014.D5" Auto default is plan 0.5.97 Refueling); "CR-015" (Venus, Io, Europa and the belt) = CR-016 (§3 is its reach additions, decision 0.5.102); "CR-010 veteran Clipper" = CR-013 (its "10J.3" is CR-013's Step 10M.3, written there as 10J.3); "CR-011 local-first" = CR-014. "Plan 12.1" is the same. Its new decisions CR-017.D1–D4 are recorded as 0.5.110 Base fuel price, 0.5.111 Deal ships full, 0.5.112 Manual by default, 0.5.113 Low-fuel warning.

On recording: the deal's ships do not start empty in this build; they start with a quarter tank (user decision during CR-015, config.deal.tankShare 0.25, DECISIONS "Deal ships come with a quarter tank"), which kept the first Market purchase in its balance window. D2 (0.5.111) replaces that decision: tankShare becomes 1.

Project: Deadhead: Space Freight Tycoon Applies to: a build with Phase 13 and CR-001 through CR-016 complete Do this: as Phase 17 Related docs: change-request-fixed-map-and-fuel-tanks.md (CR-014), change-request-veteran-clipper.md (CR-010), change-request-local-first.md (CR-011), DECISIONS.md

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

1. Why

Playtesting after CR-014: auto top-up keeps the player at 0 cr. Every landing spends all available cash on fuel, so the player can never save for ships, upgrades, or loan payments. Three changes:

  1. Lower the base fuel price, with a balance check so fuel is a sensible share of what a job pays.
  2. The deal's ships start with full tanks. The Courier and Clipper from Halvorsen's deal are created separately from purchased ships and may currently start empty, so the first landings buy whole tanks at Earth's price.
  3. Manual refueling is the default. New ships, including the deal's ships, start on Manual. Auto top-up remains an option per ship.

2. Rules

Rule Detail
Base fuel price Lowered. Start at half the current value, then tune until the balance check below passes. Location multipliers (CR-014/CR-015) are unchanged.
Fuel-to-payout check For each ship model, on the routes it can fly, the fuel cost of a typical loaded leg (bought at the origin's price) is 15–25% of the median payout of contracts on that route that fit the ship. Measured over generated boards.
Deal ships The deal's Courier and Clipper are created with full tanks, valued at Earth's fuel price for the tank's average price.
Default refuel policy Manual for every new ship: deal ships and purchased ships. Players can switch any ship to Auto top-up.
Low-fuel warning Because ships no longer refuel on their own, a ship's Fleet card shows a Low fuel warning when its tank can't fly its longest "yes" leg from its current location (CR-014 §4 / CR-015 §3). The existing "Refuel here first" button in the dispatch sheet stays as the main way to refuel.

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 live in packages/content.
  • Save migration: every existing ship's refuel policy is set to Manual (no player chose Auto on purpose; it was the default). Fuel levels and credits are unchanged.
  • Update existing tests whose expectations change (default policy, fuel costs in summaries and dispatch sheets, deal state). Update progress.md after every step.
  • Stop for the user's review at the end of Phase 17.

4. Decisions

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

  • CR-017.D1 Base fuel price. Lowered and tuned to the fuel-to-payout check (§2).
  • CR-017.D2 Deal ships full. The deal's ships start with full tanks (extends CR-014's "new ships delivered full" to ships created by the deal).
  • CR-017.D3 Manual by default. New ships default to Manual refueling (replaces CR-014 CR-014.D5's Auto default). Auto top-up still exists and behaves as before.
  • CR-017.D4 Low-fuel warning. As in §2.

5. Steps — Phase 17

Step 17.1 — Sim: fuel-to-payout balance check

  • Add a balance test that, for each ship model and each route it can fly, generates boards, takes contracts that fit the ship, and compares fuel cost for the leg (at the origin's price) with the median payout.
  • Test: The check runs and reports, per ship and route, the fuel share of payout. (It will fail until Step 17.2.)

Step 17.2 — Content: lower the base fuel price

  • Halve the base fuel price, run the check, and adjust until every ship and route lands in 15–25%. Change only the base price unless a single route can't fit; then note it in DECISIONS.md rather than changing location multipliers.
  • Test: The Step 17.1 check passes for every ship model and route.

Step 17.3 — Engine: deal ships start full; Manual by default

  • The accept-deal command creates the Courier and Clipper with full tanks.
  • Every newly created ship (deal or purchase) has refuel policy Manual.
  • Save migration per §3.
  • Test: After accepting the deal, both ships have full tanks and Manual policy. A purchased ship arrives full and on Manual. Landing a ship on Manual changes neither its fuel nor credits. An older save migrates with every ship on Manual and fuel and credits unchanged. Switching a ship to Auto still tops up on landing.

Step 17.4 — Client: low-fuel warning and policy display

  • Fleet cards show a Low fuel warning per §2. The ship detail's policy toggle shows Manual as the default.
  • Test: Component test: a Clipper at Earth with less fuel than its Earth→Mars leg needs shows Low fuel; after refueling, the warning clears. A new ship's detail shows Manual selected.

Step 17.5 — Plan amendments and regression

  • Apply the amendments in §6.
  • Run the full suite.
  • Test: CI is green. The Phase 12 balance script meets all timing targets with the new fuel price and Manual default (the simulated player refuels with "Refuel here first" when a leg needs it). Manual check: on a fresh account, accept the deal, confirm both ships are full and on Manual, fly several Earth–Moon jobs, and confirm credits grow.

6. Amendments

Where Change
Plan 0.5 Add CR-017.D1–D4; amend CR-014.D5 (default policy).
CR-014 §3 "Auto top-up (default)" becomes "Manual (default)"; base fuel price lowered.
CR-014 14.4, 14.6 tests Default policy is Manual.
CR-010 10J.3 Deal ships are created with full tanks.
Plan 12.1 The simulated player refuels before a leg when needed instead of relying on Auto top-up.

7. Out of scope

Changing how Auto top-up spends money (a cash reserve or partial fills), fuel price drift, refueling notifications, and anything else in implementation-plan.md §0.3.