Ships¶
Ship lifecycle from acquisition through maintenance, upgrades, insurance, and destruction. Detailed type-by-type stats live in definitions.md.
Acquisition¶
| Method | Notes |
|---|---|
| First-login claim | New players get one of 4–6 starter ships based on persuasion outcome. See first-login.md. |
| Shipyard purchase | Most ships available for credits at any port with shipyard facilities. |
| Salvage | Recovered from abandoned ships in contested sectors. |
| Faction reward | Higher reputation tiers (e.g. Federation Battlecruiser at Exalted) — design only, not in code. |
| Crafting (TradeDock) | Player-built ships via the shipyard system. See economy/trading.md. |
| Genesis side-effect | Advanced Genesis sacrifices a Colony Ship — that's a destruction path, not acquisition. |
The only craft-only ship is the Warp Jumper: 500,000 cr construction cost, 3–5 days at a Class 7+ shipyard, requires Quantum Shards + Photonic Crystals, limit 1 per player.
Active ship & ownership¶
A player can own multiple ships but has exactly one active ship at a time (Player.current_ship_id). Only the active ship moves, fights, and trades. Switching ships is a 0-turn action while docked.
Ships destroyed in combat go to ShipStatus.DESTROYED; the player auto-transfers to their escape pod.
Code: models/player.py, models/ship.py, services/ship_service.py.
Maintenance system¶
Implemented in models/ship.py:maintenance JSONB and services/ship_service.py:
- Each ship has a Maintenance Rating 0–100% (starts 100% on purchase).
- Decay rate per real day varies by ship class:
| Ship | Decay/day |
|---|---|
| Light Freighter, Fast Courier, Scout Ship | −1% |
| Cargo Hauler, Colony Ship, Defender | −2% |
| Carrier, Warp Jumper | −3% |
Performance bands¶
| Rating | Speed | Combat effectiveness | Fuel use | Failure risk |
|---|---|---|---|---|
| 90–100% | +5% | +5% | −5% | 0 |
| 75–89% | 0 | 0 | 0 | 0 |
| 50–74% | −5% | −5% | +5% | 0 |
| 25–49% | −15% | −20% | +20% | 5%/jump minor |
| 10–24% | −30% | −40% | +50% | 15%/jump major |
| 0–9% | −50% | −75% | +100% | 30%/jump catastrophic |
Failure types (models/ship.py:FailureType): MINOR / MAJOR / CATASTROPHIC.
- Minor → temporary system loss (sensors, etc.).
- Major → ship immobilized until repaired.
- Catastrophic → 20% destruction chance, otherwise hull dropped to ~1%.
Repair options¶
- Basic (any shipyard) — 5% of ship value per +10% rating, 6h.
- Emergency (any shipyard, even mid-failure) — 10% of ship value per +10%, 2h.
- Premium (Class I / Military) — 15% of ship value per +10%, 1h, +2% temporary speed/combat for 48h.
- Self-repair — Maintenance Kit (5,000 cr, 1 cargo). Restores up to 25% rating per kit; 12h game time; 15% chance of error reducing to 15% effectiveness.
🚧 Partial — model fields exist, repair flows exist; the dynamic decay loop and failure-rolling on jumps are largely design-stage in the current codebase.
Upgrades¶
Eight upgrade types (models/ship.py:UpgradeType); detailed upgrade and equipment loadouts in ship-systems.md:
| Type | Effect (max) |
|---|---|
| ENGINE | +0.5 sectors/turn speed |
| CARGO_HOLD | +30% storage |
| SHIELD | +200 shield points |
| HULL | +300 hull points |
| SENSOR | +15% encounter avoidance |
| DRONE_BAY | +2 bays |
| GENESIS_CONTAINMENT | +2 Genesis capacity (only for Genesis-compatible ships) |
| MAINTENANCE_SYSTEM | Auto-deploys maintenance kits when rating < 65% |
Upgrades stored in Ship.upgrades JSONB. Purchased at shipyards; price varies by sector tech level. Upgrades are 0-turn actions.
Service: services/ship_upgrade_service.py.
Insurance¶
models/ship.py:InsuranceType:
| Tier | Coverage | Deductible |
|---|---|---|
| BASIC | 50% of ship value | 5% |
| STANDARD | 75% | 10% |
| PREMIUM | 90% | 15% |
Purchased at friendly ports. Payout is immediate on destruction, allowing rapid replacement. Insurance does not cover cargo or installed upgrades.
Destruction & escape pod¶
When ship.hull <= 0:
- Ship status set to
DESTROYED. - Player auto-ejected to escape pod (
Player.current_ship_idupdated). - Cargo lost. Credits retained (they live on
Player, not the ship). - Insurance payout calculated and credited if applicable.
- Combat log entry written.
- Personal-reputation hooks fire (see combat.md).
If the player manually ejects (abandons ship intact), the ship becomes claimable by any other player in the sector.
Escape pods: - Indestructible. - Movement turn cost is much higher than any standard ship. - Can dock with a teammate's ship for free transport.
Cargo & special equipment¶
Ship.cargo JSONB tracks per-commodity quantities. Hard cap = ship type's cargo_capacity modified by upgrades and the Cargo Hauler's +15% bonus.
Special equipment slots (Ship.equipment_slots JSONB):
- Quantum Field Harvester — 50,000 cr, only on Scout / Fast Courier / Defender / Warp Jumper.
- Cloaking — has_cloaking boolean.
- Genesis containment — genesis_devices count vs max_genesis_devices.
- Mines — mines count vs max_mines.
- Auto-maintenance — has_automated_maintenance.
Player-facing affordances¶
- Ship dashboard shows hull / shields / fuel / cargo bars.
- Maintenance warnings at 75% / 50% / 25% / 10% thresholds.
- Upgrade interface at shipyards with before/after stat preview.
- Insurance purchase UI at friendly ports.
- Quick swap between owned ships when docked.
Source map¶
| Topic | Path |
|---|---|
| Ship model + enums | services/gameserver/src/models/ship.py |
| Ship specifications seed | services/gameserver/src/core/ship_specifications_seeder.py |
| Ship service | services/gameserver/src/services/ship_service.py |
| Upgrade service | services/gameserver/src/services/ship_upgrade_service.py |
| API routes | services/gameserver/src/api/routes/ship_upgrades.py, admin_ships.py |
| Movement (turn cost lookup) | services/gameserver/src/services/movement_service.py |
| Combat (destruction handling) | services/gameserver/src/services/combat_service.py:_handle_ship_destruction |