10 KiB

Raw Blame History

Change Request CR-019 — Only Show Jobs the Fleet Can Complete

Numbering note (added when recorded): this request arrived titled "CR-018 — Only Show Jobs the Fleet Can Complete" for "Phase 18". CR-018 (fuel tuning) and Phase 18 already existed, so it is stored as CR-019 and done as Phase 19: every "18.n" below means 19.n. Its references map to this repo as: "Phase 13 and CR-001 through CR-017" = Phase 13 and CR-001 to CR-018; "CR-002 open markets" and "CR-004" (rest) are the same numbers; "CR-005 cargo goods" = CR-007 (its steps 10E.n are 10G.n, so "10E.3, 10E.8" are 10G.3, 10G.8); "CR-006 ship upgrades" = CR-009; "CR-009 new ships and range" = CR-012; "CR-011 local-first" = CR-014; "CR-014 fixed map and fuel tanks" = CR-015. Plan steps 3.9, 3.11 and 9.4 are the same numbers. Its new decisions CR-018.D1–D4 are recorded as 0.5.114 Completable boards, 0.5.115 Qualifying fleet, 0.5.116 Permanent checks only, 0.5.117 Mid-period changes.

On recording: this repo already has fleet-fitted boards from its own CR-006 "Boards That Fit Your Fleet" (decisions 0.5.52 and 0.5.53), which the request's numbering doesn't include. In CR-006 every band keeps a configured number of open jobs (boardOpenSlotsPerBand) and bands no ship can carry shrink to a preview (boardPreviewSlots). The contract card also highlights a mass no ship there can carry (the weight warning, 0.5.53). This CR replaces all three: boards keep only completable jobs, and permanent-problem badges go. The "HQ" in §2 is a player bay at the location.

Project: Deadhead: Space Freight Tycoon Applies to: a build with Phase 13 and CR-001 through CR-017 complete Do this: as Phase 18 Related docs: change-request-open-markets.md (CR-002), change-request-cargo-goods.md (CR-005), change-request-ship-upgrades.md (CR-006), change-request-new-ships-and-range.md (CR-009), change-request-local-first.md (CR-011), change-request-fixed-map-and-fuel-tanks.md (CR-014), DECISIONS.md

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

1. Why

Contract boards fill up with jobs nobody in the player's fleet can take: too heavy for any ship there, Priority windows no ship can make, destinations out of range, or skill tiers no pilot has. They clutter the board and crowd out real work. From now on, a board only offers jobs at least one of the player's ship-and-pilot pairs could take.

2. Rules

Which ships and pilots count

For a location's board, the qualifying fleet is:

Owned ships at the location (idle, resting crew, or in the shop), plus owned ships in flight to the location that arrive before the board period ends.
Each such ship's assigned pilot, or any unassigned pilot at that location if the player has an HQ there (so they could be assigned).
If no ship qualifies, use the whole fleet: every owned ship and pilot pair, wherever they are. This keeps boards at empty locations useful for deciding where to deadhead.

What "can complete" means

A job is completable if at least one qualifying pair passes every permanent check:

Check	Uses
Cargo fits	Ship's effective capacity (CR-006)
Can land	Landing class
In range	Full-tank reach from the job's origin (CR-014); if the origin doesn't sell fuel, the fuel on board
Not stranded	No-strand rule (CR-009/CR-014)
Fast enough	Priority window, with handling time (CR-005)
Skilled enough	Cargo skill tier and Long Haul requirement (CR-005, plan 3.11)

Temporary conditions are ignored: pilot resting, ship in the shop, not enough fuel on board right now (it can be refueled), and not enough credits. Those still show as reasons in the dispatch sheet.

Generation

When a board is generated (first view in a period, CR-002), the generator produces candidate contracts as it does now and keeps only completable ones until the board is full or a maximum number of attempts is reached (default 200). A board may end up smaller than the configured size if the fleet can do very little there.
First-contact contracts follow the same rule.
The board stores the qualifying fleet's capabilities it was generated against, so results are deterministic and reproducible.

When the fleet changes mid-period

Stored boards stay as generated, but the board view also filters at display time: a job that's no longer completable (for example, the only capable ship left) is hidden.
New capability (a new ship, an upgrade, a spent skill point) shows up on the next board refresh. With 10-minute periods (the rest/board tuning), that's a short wait.

Cards

Card badges for permanent problems ("TOO HEAVY", "TOO SLOW", skill too low) are removed: everything shown can be done by someone. Pairs that can't take a job are still disabled with their reason in the dispatch sheet.
If filtering leaves a board empty: "No jobs here your fleet can take right now. New contracts in mm:ss." with the existing Rest and Deadhead options when a ship is idle there (CR-004).

Unchanged

The tutorial board (always fits the loaner).
How cargo classes, goods, Priority, and shippers are chosen (CR-005); filtering naturally shifts the mix toward what the fleet can carry.

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.
The completability check is one pure function in packages/sim, reused by the generator, the display filter, and the dispatch sheet, so they never disagree.
Save migration: stored boards from before this change are discarded and regenerate on next view.
Update existing tests whose expectations change (board contents, card badges, the CR-005 class-mix baseline test, which should run with a "full capability" fleet fixture). Update architecture.md and progress.md as you go.
Stop for the user's review at the end of Phase 18.

4. Decisions

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

CR-018.D1 Completable boards. Boards contain only jobs at least one qualifying ship-and-pilot pair can complete, per §2.
CR-018.D2 Qualifying fleet. Ships at or arriving at the location, with their pilots or assignable pilots there; the whole fleet if none.
CR-018.D3 Permanent checks only. Rest, shop, fuel on board, and credits don't affect completability.
CR-018.D4 Mid-period changes. Display-time filtering hides jobs that stopped being completable; new capability appears at the next refresh.

5. Steps — Phase 18

Step 18.1 — Sim: completability check

Add a pure function: given a contract and a list of ship-and-pilot capability snapshots (effective stats, landing class, skills, location), return whether any pair can complete it and, per pair, the first failing permanent check.
Add a function that builds the qualifying fleet for a location per §2.
Test: One test per permanent check, each with a pair that fails only that check. A job is completable if any one pair passes. Resting, in-shop, low-fuel, and no-credit states don't change the result. A location with no ships returns the whole fleet as qualifying.
Amended by CR-026: A hull below 50% can't take Dangerous cargo, but that's a temporary reason (hull-too-damaged), not a permanent check: boards don't hide those jobs.

Step 18.2 — Sim: generation keeps only completable jobs

The board generator takes the qualifying fleet snapshot and keeps only completable candidates, up to the board size or the attempt limit. First-contact candidates are filtered the same way.
Test: Over 1,000 boards with assorted fleet fixtures, no generated contract fails the completability check for its fleet. With only a level-0 avatar in a Courier at Earth, every board is full and every job is Standard, fits the Courier, and goes to the Moon. With a fleet that can do almost nothing, generation stops at the attempt limit and returns a smaller board without error. Same inputs still give identical boards. The CR-005 class-mix test passes with a full-capability fleet fixture.

Step 18.3 — Engine: boards, filtering, and migration

Board generation passes the qualifying fleet snapshot and stores it with the board. Board reads filter out jobs that are no longer completable for the current qualifying fleet.
Save migration discards stored boards from before this change.
Test: Generating a board, then selling or moving away the only ship that could take a heavy job, hides that job on the next read. Buying a bigger ship mid-period doesn't add jobs until the next period. An older save migrates with no stored boards, and boards regenerate on view.

Step 18.4 — Client: cards and empty state

Remove permanent-problem badges from contract cards. Keep the dispatch sheet's per-pair reasons.
Add the empty-board message from §2.
Test: Component test: no card shows TOO HEAVY, TOO SLOW, or a skill-too-low badge. An empty filtered board shows the message with the refresh countdown, plus Rest and Deadhead when a ship is idle there.

Step 18.5 — Plan amendments and regression

Apply the amendments in §6.
Run the full suite.
Test: CI is green. The Phase 12 balance script still meets all timing targets, and its simulated player never sees a job it can't complete. Manual check: with only the deal's Courier and Clipper, browse the Earth board and confirm every job can be dispatched with one of them.

6. Amendments

Where	Change
Plan 0.5	Add CR-018.D1–D4.
Plan 3.9	Board generation filters by the qualifying fleet (18.2).
Plan 9.4	Cards drop permanent-problem badges; empty-board message (18.4).
CR-005 10E.3, 10E.8	Class-mix test uses a full-capability fleet fixture; "TOO SLOW" card badge removed.
CR-002	Stored boards also record the fleet snapshot (18.3).

Amended by CR-021: Independent pilots choose only from these completable boards (the board the player sees, minus first contacts, the first-look window and the job the player has open); the board rules don't change.

7. Out of scope

A "show all jobs" toggle, regenerating boards immediately when the fleet changes, hiding jobs based on credits or fuel on board, and anything else in implementation-plan.md §0.3.

10 KiB Raw Blame History Unescape Escape