deadhead-space-freight-tycoon/memory-bank/game-design-document.md

# Game Design Document — Deadhead: Space Freight Tycoon

**Title:** Deadhead: Space Freight Tycoon ("deadhead" — trucker slang for running empty, a nod to the backhaul mechanic)
**Genre:** Real-time logistics / management tycoon
**Platforms:** Web and mobile (installable PWA, optionally wrapped with Capacitor for app stores)
**Tone:** Soft sci-fi, utilitarian, "American/Euro Truck Simulator in space" — with the focus on management, not piloting

---

## 1. Concept

The player builds a space shipping company from nothing. They start by running jobs for private companies using company ships, save up to buy their first ship, rent a docking bay on Earth, hire pilots, and expand across the solar system — and eventually to nearby stars.

The game is about **logistics decisions**: which jobs to take, which ship and pilot to send, where to open bays, and how to grow. There is no manual flying or landing.

## 2. Design Pillars

1. **Management over simulation** — every interaction is a decision, not a dexterity test.
2. **Put the phone down** — real-time with offline progress; ships keep flying while the app is closed.
3. **Every load goes somewhere for a reason** — contracts come from what each destination produces and needs.
4. **Earned expansion** — new locations are discovered by delivering there, not bought from a menu.
5. **Soft sci-fi** — real solar system locations and distances, but fun beats physics.

## 3. Setting

- Our own solar system, then nearby real stars (late game).
- Ships are classic sci-fi freighters: they take off from a pad, cruise, and land directly at the destination. Think utilitarian haulers with landing struts and big cargo doors, not sleek fighters.
- Distances are based on real planetary positions, so routes like Earth–Mars get shorter or longer over time.

## 4. Core Loop

1. Browse the freight market (contract board) wherever an idle ship is. Every discovered location has one.
2. Choose a ship and pilot, set the throttle, and dispatch.
3. Ship travels in real time (continues while offline).
4. Delivery completes: payout, pilot XP, possible new destination discovered. The ship takes a backhaul from where it landed, or deadheads (flies empty, fuel only) somewhere better.
5. Reinvest: ships, bays, pilots, pilot skills.

## 5. Progression

### Phase 1 — Contract Pilot (tutorial)
- The player is the pilot, flying company-owned ships on Earth ↔ Moon runs.
- Short and fast; the goal is to teach the loop and get the player to their first ship quickly.

### Phase 2 — Owner-Operator
- Buy a first ship, rent a docking bay on Earth, hire a first pilot.
- The player moves into a management role.

### Phase 3 — Fleet Company
- Multiple ships, pilots, and bays across the inner system, belt, and gas giants.
- Automation becomes important (see §12).

### Phase 4 — Interstellar
- A late-game unlock (jump gates or an FTL technology) opens nearby real stars such as Alpha Centauri, Barnard's Star, and TRAPPIST-1.
- Treated as a new map region, similar to a new map expansion in ATS/ETS.

## 6. Time Model

- **Real-time with offline progress.** Closing the app does not pause the game.
- **Compressed game clock:** default **1 real minute = 1 game hour** (configurable for balancing).

| Route (approx.) | Real-time duration at default scale |
|---|---|
| Earth → Moon | A few minutes |
| Earth → Mars | ~1–2 hours (varies with planet positions) |
| Earth → Jupiter | A few hours |
| Outer system | Overnight runs |

## 7. Travel

```
travel time = distance / cruise speed + takeoff/landing overhead
```

- **Overhead** is a fixed cost per trip. Small, nimble ships do best on short hops; big haulers do best on long routes where cruise speed dominates.
- **Throttle setting** per dispatch: *Cruise* (standard) vs. *Push the engines* (faster, more fuel, more wear).
- **Fuel range** limits distance per trip. Longer routes need multi-leg trips with refuel stops, making waypoint bays (e.g., Mars, Ceres) valuable.
- **Launch cost** scales with the departure world's gravity. Earth is the most expensive pad to launch from; the Moon is cheap, which makes a lunar bay a natural hub.

## 8. Ships

Multiple ships are available for purchase, each with different stats.

### Ship Stats
| Stat | Effect |
|---|---|
| Cruise speed | Travel time |
| Cargo capacity | Mass and/or volume per trip |
| Fuel range | Max distance before refueling |
| Hull rating | Event survival, insurance cost, dangerous-cargo eligibility |
| Landing class | Which destinations the ship can land at |
| Upkeep | Maintenance, crew, and docking costs |

### Landing Classes
| Class | Can land at |
|---|---|
| Vacuum | Airless bodies, belt stations |
| Atmospheric | Above + atmospheric worlds and cloud platforms |
| Hardened | Above + hostile worlds (Venus, Io) |

### Example Archetypes
- **Courier** — fast, small hold, short range, low overhead, atmospheric-rated. Great for short or urgent jobs.
- **Freighter** — balanced all-rounder.
- **Bulk hauler** — slow, huge hold, high capacity. Great for long, heavy routes.

Ship tiers should feel like upgrading from a box truck to a top-end rig.

## 9. Destinations

| Type | Examples | Landing need | Main export | Main hazard |
|---|---|---|---|---|
| Atmospheric world | Earth, Mars, Titan | Atmospheric | Manufactured goods, food | High launch cost |
| Airless body | Moon, Mercury, rocky moons | Any | Minerals, research | Low |
| Hostile world | Venus, Io | Hardened | Rare materials | Environmental damage |
| Cloud platform | Jupiter, Saturn (later Uranus, Neptune) | Atmospheric | Fuel, gases (H₂, He-3) | Storms |
| Belt station | Ceres, Vesta, mining outposts | Any | Ore, metals, ice | Debris fields |

### Gas Giant Cloud Platforms
- Floating industrial platforms in the upper atmosphere.
- The system's fuel refineries: fuel is cheapest here and most expensive near Earth.
- Isolated company towns that import parts, food, and supplies (good backhaul opportunities).
- Storm events can delay departures or damage hulls; Jupiter is rougher than Saturn.

### Asteroid Belt Stations
- Mining and ore-processing stations. Export heavy raw materials; import equipment, supplies, and people.
- Routes through the belt carry debris and collision risk; hull rating matters and hazard pay increases.
- **Ceres** acts as the major hub and refuel waypoint, the gateway to the outer system.
- Station variety: large established stations, rough mining outposts, and possibly a shady independent station offering high-risk contracts.

## 10. Docking Bays & Discovery

- **Every discovered location has a contract board** (its freight market), like the job markets in American/Euro Truck Simulator. Any idle ship can pick up work wherever it is, so backhauls are always possible and a ship is never stranded.
- **Docking bays are HQs** (like ATS garages), rented at a discovered location. A bay is where pilots are hired, where newly bought ships are delivered, and where pilots can be unassigned. A bay does **not** control where contracts are offered.
- A location must be **discovered** before it has a board, a bay can be rented there, or ships can deadhead there. Discovery happens only by **completing a delivery to that location**.
- Contracts to undiscovered destinations appear occasionally on discovered locations' boards as well-paying "first contact" or survey jobs, giving players a path to expand.

## 11. Pilots

Pilots are hired, assigned to ships, and gain **XP** from deliveries. XP is spent on skills that unlock better contracts and improve results.

### Skills
| Skill | Effect |
|---|---|
| Long haul | Access to longer routes; better fuel efficiency on long trips |
| Heavy cargo | Access to heavy loads; reduces speed penalty from heavy cargo |
| Expensive cargo | Access to high-value cargo |
| Dangerous cargo | Access to hazardous cargo, tiered by hazard class |
| Fragile cargo | Access to medical, biological, and instrument cargo |
| Urgent delivery | Access to just-in-time contracts with time bonuses |
| Fuel efficiency | Reduced fuel use and wear |

**Design rule:** skills should change outcomes (speed, failure chance, fuel use), not just unlock job tiers, so every level-up changes the player's math.

### Pilot Location
- A pilot is wherever their ship is. Pilots only travel by flying a ship.
- Pilots are hired at one of the player's bays and can only be unassigned at a bay, so they never get stranded.

### Pilot Tension
- Salaries scale with level.
- High-level pilots may be poached by rivals.

## 12. Contracts & Economy

### Contract Generation
- Every destination **produces** some goods and **needs** others. Contracts are generated from these flows.
- Backhaul matters: the best routes avoid flying home empty.
- Each discovered location has one contract board per player per refresh period. Contracts expire when the period ends.
- Payout is fixed when a contract is offered; travel time and fuel depend on the distance at departure.

### Payout Factors
- Distance
- Cargo type (heavy, high-value, dangerous, fragile)
- Urgency and deadline
- Destination hazard
- Client reputation

### Money Sinks
- Fuel (priced by location)
- Maintenance and wear
- Insurance (scales with cargo value and danger)
- Pilot salaries
- Docking bay rent

### Reputation
- Standing with client companies is a second progression axis alongside money.
- Higher reputation unlocks better contracts; sometimes taking a lower-paying job is worth it for standing.

### Automation (Mid/Late Game)
- Standing routes and auto-accept rules (for example, "take any heavy cargo job on Moon–Mars above X credits").
- Prevents micromanagement from becoming a chore at large fleet sizes.

## 13. Events & Risk

Events are rolled at dispatch time (see §14) and can include:
- Solar flares (delays)
- Gas giant storms (delays, hull damage)
- Belt debris (hull damage)
- Piracy (cargo loss, mitigated by hull rating and pilot skill)
- Customs holds (delays)

## 14. Technical Architecture

### Offline Progress
- Every trip is **deterministic from its dispatch record**. Nothing simulates while the app is closed.
- The dispatch record stores: departure timestamp, origin, destination, ship, pilot, cargo, throttle setting, and RNG seed.
- Arrival time, current position, and events are all derived from that record.
- **Events are pre-rolled at dispatch** from the seed, so reopening the app can't reroll outcomes (prevents save-scumming).
- On load, the client gets the current time from the server, resolves completed dispatches (payouts, XP, pilots returning), and shows in-flight ships at their interpolated positions.

### Backend
- **Server-authoritative time**, so changing the device clock has no effect.
- **Cloud saves** so web and mobile share one game state.

### Notifications
- Web Push for arrivals and events (supported on installed PWAs, including iOS 16.4+).
- A Capacitor wrapper is an option for more reliable notifications and app-store distribution.

## 15. Open Questions

- Visual style
- Exact contract generation and payout formulas
- Ship roster: number of ships, prices, and stat values
- Interstellar unlock mechanic: jump gates vs. ship-based FTL
- Single-player only, or leaderboards and other social features?
- Monetization model, if any
- Tech stack: framework and rendering for the map and UI