Skip to content

Ship Systems — Upgrades, Equipment, and Loadouts

How a ship grows from a starter freighter into a specialised platform. The architecture has two distinct extension points — Ship.upgrades (linear stat bumps) and Ship.equipment_slots (modular plug-ins) — that work in parallel.

This doc complements ships.md, which lists ship types and base stats. Here we cover the customisation layer.

Source files: - services/gameserver/src/models/ship.py — Ship, ShipSpecification, UpgradeType, InsuranceType, ShipStatus. - services/gameserver/src/services/ship_service.py — creation, destruction, repair, escape pod handling. - services/gameserver/src/services/ship_upgrade_service.py — UPGRADE_DEFINITIONS, EQUIPMENT_DEFINITIONS, purchase_upgrade, install_equipment.

1. The two-track architecture

1.1 Upgrades — linear stat bumps

Ship.upgrades is a JSONB column on the ships table (models/ship.py:97):

upgrades = Column(JSONB, nullable=False, default=[])

It stores {upgrade_type: current_level}. Levels are integer, start at 0, and cap at the ship-spec-defined max (ShipSpecification.max_upgrade_levels, also JSONB). Each upgrade level applies a fixed delta (e.g. +0.5 speed per Engine level).

Costs follow a geometric progression: each next level costs base_cost * cost_multiplier^current_level. So Engine L1 = 5,000 cr, L2 = 10,000 cr, L3 = 20,000 cr, etc.

Upgrades are permanent — once purchased they stay attached to that ship until the ship is destroyed.

1.2 Equipment slots — modular plug-ins

Ship.equipment_slots is also JSONB (models/ship.py:100):

equipment_slots = Column(JSONB, nullable=False, default={})

It stores {equipment_key: {effects: {...}, installed_at: ...}}. Equipment is flat (no levels), ship-type-restricted (each piece lists compatible_ships), and stacks additively across slots — ship_upgrade_service.get_equipment_effects merges all installed equipment into a single effects dict that combat / trading / movement services consult.

Equipment is removable (📐 Design-only — uninstall flow exists in ship_upgrade_service.py:425+ but resale value mechanics are not finalised).

Status: ✅ Shipped — both the upgrades and equipment_slots columns are populated by ship_upgrade_service, which exposes both purchase_upgrade and install_equipment paths. The two systems run in parallel, not as a replacement for one another.

2. Upgrade categories

Source: services/gameserver/src/services/ship_upgrade_service.py:UPGRADE_DEFINITIONS. All eight upgrade types map to UpgradeType enum values in models/ship.py:35-43.

Upgrade Base cost Multiplier Effect per level UpgradeType enum
Engine 5,000 2.0 speed +0.5 ENGINE
Cargo Hold 3,000 1.8 cargo +30% CARGO_HOLD
Shield 8,000 2.2 max_shields +200 SHIELD
Hull 7,000 2.0 hull_points +300 HULL
Sensor 6,000 2.5 evasion +15% SENSOR
Drone Bay 10,000 2.0 drone capacity +2 DRONE_BAY
Genesis Containment 15,000 3.0 genesis capacity +2 GENESIS_CONTAINMENT
Maintenance System (📐) (📐) reduces failure rate MAINTENANCE_SYSTEM

Status: ✅ Shipped for the first seven. 🚧 Partial for MAINTENANCE_SYSTEM — the enum exists but no entry in UPGRADE_DEFINITIONS (i.e. no cost / effect tuple), so the upgrade is unbuyable today.

2.1 Hull

Source: models/ship.py:ShipSpecification.hull_points, services/gameserver/src/services/combat_service.py.

Each Hull upgrade level adds 300 hull points. Combat damage that exceeds shields hits hull; when hull reaches 0 the ship is destroyed. Hull repair happens at stations via ship_service.repair_ship.

2.2 Engine

Source: models/ship.py:Ship.base_speed, models/ship.py:Ship.current_speed.

Each Engine upgrade adds +0.5 speed. Higher speed reduces time-to-arrival between sectors and improves combat evasion (along with sensor upgrades).

2.3 Shield

Source: models/ship.py:ShipSpecification.max_shields, shield_recharge_rate.

Each Shield level adds 200 max shields. Shields regenerate per-tick at the spec's shield_recharge_rate. Upgrades do not change the recharge rate — that's set by the ship spec.

2.4 Cargo

Source: models/ship.py:ShipSpecification.max_cargo, Ship.cargo (JSONB).

Each Cargo Hold level adds +30% to base cargo capacity. Cargo holds commodities for trading (see economy/trading.md) — bigger cargo means more profit per haul.

2.5 Sensor

Source: models/ship.py:ShipSpecification.scanner_range, evasion.

Each Sensor level adds +15% evasion. Sensors also affect scan range (📐 Design-only — current implementation only applies the evasion bonus). Higher evasion = lower hit probability against the ship in combat.

2.6 Weapons

Source: models/ship.py:ShipSpecification.attack_rating, models/ship.py:Ship.combat (JSONB).

Weapons are not in UpgradeType — they're driven by attack_rating from the ship spec, which is fixed at ship purchase. To get a stronger gun, buy a stronger ship, or install combat-class equipment (📐 Design-only — no combat equipment in EQUIPMENT_DEFINITIONS yet, only quantum_harvester, mining_laser, planetary_lander).

Status: 📐 Design-only — the upgrade-vs-equipment split deliberately excludes weapons. The intent is that weapons remain a ship-class signature, with equipment offering tactical modifiers (stealth, ECM, target lock) rather than raw firepower.

2.7 Drone bay

Source: models/ship.py:ShipSpecification.max_drones, models/drone.py, services/drone_service.py.

Each Drone Bay level adds +2 drone capacity. Drones are deployable assets — attack drones, defence drones, and mines (Player.attack_drones, Player.defense_drones, Player.mines).

2.8 Genesis bay

Source: models/ship.py:ShipSpecification.max_genesis_devices, models/ship.py:Ship.genesis_devices.

Each Genesis Containment level adds +2 device slots. Only ships with ShipSpecification.genesis_compatible = true can install this upgrade (typically Carrier and Warp Jumper). See galaxy/genesis-devices.md.

2.9 Maintenance

Source: models/ship.py:Ship.maintenance (JSONB), models/ship.py:Ship.has_automated_maintenance, models/ship.py:FailureType enum.

Ships accumulate wear that produces FailureType events (NONE / MINOR / MAJOR / CATASTROPHIC). The MAINTENANCE_SYSTEM upgrade reduces the failure rate; has_automated_maintenance (boolean flag) makes maintenance run continuously without docking.

Status: 🚧 Partial — maintenance JSONB exists; failure roll logic and the MAINTENANCE_SYSTEM upgrade economy are 📐 Design-only.

3. Equipment catalogue

Source: services/gameserver/src/services/ship_upgrade_service.py:EQUIPMENT_DEFINITIONS.

Key Cost Compatible ships Effects
quantum_harvester 25,000 Scout, Fast Courier, Defender, Warp Jumper passive_income: 100
mining_laser 35,000 Cargo Hauler, Colony Ship, Defender mining_efficiency: 1.5
planetary_lander 20,000 Colony Ship, Light Freighter, Cargo Hauler landing_bonus: 1.25

Status: ✅ Shipped — all three equipment types installable. 📐 Design-only — additional equipment (combat ECM, stealth modules, scientific scanners, fleet command link) is planned but not yet defined.

3.1 How equipment effects apply

ship_upgrade_service.get_equipment_effects(ship) returns a merged dict. Other services consume:

  • passive_income → applied per-tick by an idle-income job (📐 Design-only — periodic credit grant scheduler).
  • mining_efficiency → multiplier on raw resource yields when mining (📐 Design-only — mining gameplay loop).
  • landing_bonus → multiplier on planet-side production / colonist throughput (📐 Design-only — ties into planets/colonization.md).

The pipe (read merged effects → apply at use site) is in place; the use sites that consume these specific effects are mostly 📐 Design-only.

4. Insurance

Source: models/ship.py:InsuranceType (NONE / BASIC / STANDARD / PREMIUM), models/ship.py:Ship.insurance (JSONB), services/ship_service.py:_calculate_insurance_payout.

Insurance is paid via periodic premium and pays a fraction of Ship.purchase_value on destruction:

Tier Target premium / wk Target payout
NONE 0 0%
BASIC 1% of value 25%
STANDARD 2% of value 50%
PREMIUM 4% of value 80%

Status: 📐 Design-only — InsuranceType enum and _calculate_insurance_payout exist; the premium billing loop and tier-to-payout-fraction table are not finalised.

5. Ship destruction & escape pod

Source: services/ship_service.py:destroy_ship, _ensure_escape_pod, _transfer_emergency_cargo.

When a ship is destroyed: 1. Ship.is_destroyed = true, Ship.status = ShipStatus.DESTROYED. 2. An ESCAPE_POD ship is created for the player if they don't already have one. The escape pod is a special ShipType.ESCAPE_POD — minimal cargo, no weapons, indestructible to non-PvP. 3. A small fraction of the destroyed ship's cargo (emergency cargo) transfers to the escape pod. 4. If insurance was active, the payout credits are added to Player.credits.

Status: ✅ Shipped — destruction → escape pod transition works end-to-end.

6. Ship types and loadouts

The ship types live in models/ship.py:ShipType:

ESCAPE_POD, LIGHT_FREIGHTER, CARGO_HAULER, FAST_COURIER, SCOUT_SHIP,
COLONY_SHIP, DEFENDER, CARRIER, WARP_JUMPER

Each has a ShipSpecification row with base stats, max_upgrade_levels (which upgrades it accepts and how high), and acquisition_methods. See ships.md for base stats; here we cover example loadouts — what a player should build toward depending on play-style.

6.1 Scout build (exploration)

Base ship: SCOUT_SHIP — high speed, high evasion, low cargo, no genesis bay.

Recommended upgrades (in order): 1. Sensor L1–L3 (max evasion: +45%) 2. Engine L1–L2 (max speed boost) 3. Shield L1 (survival buffer) 4. Cargo Hold L1 (small)

Recommended equipment: quantum_harvester (passive income while exploring deep space).

Total investment to fully kit: ~150,000 cr.

6.2 Cargo Hauler build (trader)

Base ship: CARGO_HAULER — large cargo, slow, modest defence.

Recommended upgrades: 1. Cargo Hold L1–L4 (max cargo: +120%) 2. Engine L1–L2 (offset baseline slowness) 3. Shield L1–L2 (defend valuable cargo) 4. Hull L1

Recommended equipment: mining_laser (extra resource yield from sectors), planetary_lander (improved colonist trade with own planets).

Total investment to fully kit: ~250,000 cr.

6.3 Defender build (combat / escort)

Base ship: DEFENDER — balanced offense/defence, high attack rating.

Recommended upgrades: 1. Hull L1–L4 (max hull: +1,200) 2. Shield L1–L4 (max shields: +800) 3. Drone Bay L1–L3 (max drones: +6) 4. Sensor L1–L2 (improved combat evasion)

Recommended equipment: quantum_harvester (passive income while patrolling), or 📐-Design-only future combat equipment (ECM, stealth).

Total investment to fully kit: ~500,000 cr.

6.4 Colony Ship build (colonist hauler)

Base ship: COLONY_SHIP — high max_colonists, modest cargo.

Recommended upgrades: 1. Cargo Hold L1–L3 2. Hull L1–L2 (lots of valuable cargo) 3. Shield L1 4. Engine L1

Recommended equipment: planetary_lander (mandatory), mining_laser.

6.5 Carrier build (fleet flagship)

Base ship: CARRIER — many drones, genesis-compatible.

Recommended upgrades: 1. Drone Bay L1–L5 (massive drone swarm) 2. Genesis Containment L1–L3 (carry multiple genesis devices) 3. Hull / Shield L1–L4 4. Cargo Hold L1–L2

Equipment slots: large; intended for end-game tactical equipment (📐 Design-only).

6.6 Warp Jumper build (cross-region)

Base ship: WARP_JUMPER — quantum_jump_capable, warp_creation_capable.

Recommended upgrades: 1. Engine L1–L3 (jump cooldown reduction — 📐 Design-only effect) 2. Shield L1–L3 3. Genesis Containment L1–L2 4. Sensor L1–L2

Equipment: quantum_harvester. End-game logistics ship — fewest in number, most strategic value.

6.7 Fast Courier build (high-value cargo)

Base ship: FAST_COURIER — fast, small cargo, highly evasive.

Recommended upgrades: 1. Engine L1–L4 (max speed) 2. Sensor L1–L3 (max evasion) 3. Shield L1 4. Cargo Hold L1

Use case: hauling exotic_technology and luxury_goods on long routes where speed matters more than volume.

7. Cross-references