Sector-Resident Entities

Ships, Planets, Stations, and Genesis Devices.

---

Ship

Source: services/gameserver/src/models/ship.py

Purpose: A player-owned vessel; tracks position, cargo, combat readiness, and special equipment.

Fields:

name	type	constraints	notes
id	UUID	PK
name	String(100)	not null
type	Enum ship_type	not null	ESCAPE_POD, LIGHT_FREIGHTER, CARGO_HAULER, FAST_COURIER, SCOUT_SHIP, COLONY_SHIP, DEFENDER, CARRIER, WARP_JUMPER
owner_id	UUID FK players.id	not null, CASCADE
sector_id	Integer	not null	matches Sector.sector_id (integer), not the UUID
base_speed, current_speed	Float	not null
turn_cost	Integer	not null
warp_capable	Boolean	default false
is_active	Boolean	default true
status	Enum ship_status	default DOCKED	DOCKED/IN_SPACE/IN_COMBAT/DESTROYED/MAINTENANCE
maintenance	JSONB	not null
cargo	JSONB	not null	commodity → quantity
has_cloaking	Boolean	default false
genesis_devices, max_genesis_devices	Integer	defaults 0
mines, max_mines	Integer	defaults 0
has_automated_maintenance	Boolean	default false
combat	JSONB	not null	shields/hull/etc.
attack_turn_cost	Integer	nullable	per-ship combat initiation cost (added in migration d2e3f4a5b6c7)
upgrades	JSONB	default []
equipment_slots	JSONB	default {}	added in migration d2e3f4a5b6c7
insurance	JSONB	nullable
is_destroyed, is_flagship	Boolean	defaults false
purchase_value, current_value	Integer	not null

Relationships: - owner → Player (FK owner_id). - flagship_of back-ref via Player.current_ship_id (post-update cycle). - sector → Sector joined on integer sector_id. - genesis_device_objects → GenesisDevice (1:many). - fleet_membership → FleetMember (1:1).

ShipSpecification

Source: services/gameserver/src/models/ship.py (same file)

Purpose: Static balance data per ShipType — base cost, hull, shield, cargo, drone, evasion, attack/defense ratings, etc. One row per ship type.

Key fields: type (unique), base_cost, speed, turn_cost, max_cargo, max_colonists, max_drones, max_shields, shield_recharge_rate, hull_points, evasion, genesis_compatible, max_genesis_devices, warp_compatible, warp_creation_capable, quantum_jump_capable, scanner_range, attack_rating, defense_rating, attack_turn_cost, maintenance_rate, construction_time, fuel_efficiency, max_upgrade_levels (JSONB), special_abilities (JSONB), acquisition_methods (JSONB), faction_requirements (JSONB).

---

Planet

Source: services/gameserver/src/models/planet.py

Purpose: Habitable / colonizable body in a sector; the long-form economic and defensive base for players.

Fields:

name	type	constraints	notes
id	UUID	PK
name	String(100)	not null
sector_id	Integer	not null	integer alongside UUID
sector_uuid	UUID FK sectors.id	nullable, CASCADE
owner_id	UUID	nullable	not a FK constraint — ownership is also tracked via the player_planets association table
type	Enum planet_type	not null	TERRAN/DESERT/OCEANIC/ICE/VOLCANIC/GAS_GIANT/BARREN/JUNGLE/ARCTIC/TROPICAL/MOUNTAINOUS/ARTIFICIAL
status	Enum planet_status	default UNINHABITABLE	UNINHABITABLE/HABITABLE/COLONIZED/DEVELOPED/TERRAFORMING/DYING/RESTRICTED
size, position	Integer	defaults 5 / 3	1-10; orbital position
gravity	Float	default 1.0
planet_type	String(50)	nullable	secondary string variant for API compatibility
specialization	String(50)	nullable
atmosphere	String	nullable
temperature, water_coverage, habitability_score, radiation_level	numeric	various
resource_richness	Float	default 1.0	0.0-3.0 multiplier
resources	JSONB	default {}
special_resources	ARRAY(String)	default []
fuel_ore, organics, equipment, fighters	Integer	defaults 0	stockpiles
colonized_at	DateTime	nullable
population, max_population	BigInteger	defaults 0	widened in migration dbbfad27a7ef
population_growth	Float	default 0.0
colonists, max_colonists	Integer	default 0 / 10000
fuel_allocation, organics_allocation, equipment_allocation	Integer	defaults 0
economy, production	JSONB	defaults	production has fuel/organics/equipment/research keys
production_efficiency	Float	default 1.0
factory_level, farm_level, mine_level, research_level	Integer	defaults 0
defense_level, shields, weapon_batteries, defense_turrets, defense_shields, defense_fighters	Integer	defaults 0
last_attacked, last_production	DateTime	nullable
active_events	JSONB	default []
under_siege	Boolean	default false
siege_started_at, siege_attacker_id	mixed	nullable	siege state added in migration a1b2c3d4e5f6
citadel_level	Integer	default 0	0-5 (migration e3f4a5b6c7d8)
citadel_upgrading	Boolean	default false
citadel_upgrade_started_at, citadel_upgrade_complete_at	DateTime	nullable
citadel_safe_credits, citadel_safe_max	BigInteger	defaults 0
citadel_drone_capacity	Integer	default 0
citadel_max_population	BigInteger	default 0
genesis_created	Boolean	default false
genesis_device_id	UUID FK genesis_devices.id	nullable
genesis_tier	String(20)	nullable	basic/enhanced/advanced (migration a3f7c2d91e54)
formation_status	String(20)	nullable	forming/complete
formation_started_at, formation_complete_at	DateTime	nullable
region_id	UUID FK regions.id	nullable

Relationships: - owner → Player (many-to-many via player_planets association). - sector → Sector (FK sector_uuid). - genesis_device → GenesisDevice (the device that formed this planet). - formation → PlanetFormation (1:1). - region → Region.

player_planets (association)

Columns: player_id, planet_id (composite PK), acquired_at. Both FKs CASCADE delete.

---

Station

Source: services/gameserver/src/models/station.py

Purpose: Trade/service hub in a sector; also the locus for the haggling AI and player-acquirable ownership.

Fields:

name	type	constraints	notes
id	UUID	PK
name	String(100)	not null
sector_id	Integer	not null
sector_uuid	UUID FK sectors.id	nullable, CASCADE
owner_id	UUID	nullable	many-to-many via player_stations
station_class	Enum station_class	not null	CLASS_0…CLASS_11; encodes trading pattern (mining/agri/industrial/distribution/collection/black-hole/nova/luxury/etc.)
type	Enum station_type	not null	TRADING/MILITARY/INDUSTRIAL/MINING/SCIENTIFIC/SHIPYARD/OUTPOST/BLACK_MARKET/DIPLOMATIC/CORPORATE
status	Enum station_status	default OPERATIONAL	OPERATIONAL/DAMAGED/UNDER_CONSTRUCTION/UNDER_ATTACK/LOCKDOWN/ABANDONED/RESTRICTED
size	Integer	default 5	1-10
faction_affiliation	String	nullable
trade_volume	Integer	default 100
market_volatility	Integer	default 50	0-100
commodities	JSONB	not null	per-commodity (ore/organics/equipment/fuel/luxury_goods/gourmet_food/exotic_technology/colonists) blob with quantity, capacity, base_price, current_price, production_rate, price_variance, buys, sells
trader_personality	JSONB	not null	type, haggling_difficulty, preferred_appeal_types, memory_duration, trust_level, quirks
price_modifiers	JSONB	default {}
services	JSONB	not null	ship_dealer, ship_repair, ship_maintenance, ship_upgrades, insurance, drone_shop, genesis_dealer, mine_dealer, diplomatic_services, storage_rental, market_intelligence, refining_facility, luxury_amenities
service_prices	JSONB	default {}
defenses	JSONB	not null	defense_drones, max_defense_drones, auto_turrets, defense_grid, shield_strength, patrol_ships, military_contract
ownership	JSONB	nullable	player ownership details when claimed
last_market_update	DateTime	server default now
market_update_frequency	Integer	default 6	hours
reputation_threshold	Integer	default 0	min reputation to dock
is_quest_hub, is_faction_headquarters, is_player_ownable	Boolean	defaults false/false/true
acquisition_requirements	JSONB	not null	min_trade_volume, min_faction_standing, base_price, special_missions
last_attacked	DateTime	nullable
is_destroyed	Boolean	default false
recovery_time	DateTime	nullable
active_events	JSONB	default []
special_services	ARRAY(String)	default []
region_id	UUID FK regions.id	nullable

Relationships: - owner → Player (many-to-many via player_stations). - sector → Sector (FK sector_uuid). - market → Market (1:1, cascade delete) — see ./economy.md. - region → Region.

player_stations (association)

Columns: player_id, station_id (composite PK), acquired_at.

---

GenesisDevice

Source: services/gameserver/src/models/genesis_device.py

Purpose: Deployable terraforming device; deploys to a sector to form a planet. Tracks process phase, success chance, and result.

Fields:

name	type	constraints	notes
id	UUID	PK
name	String(100)	not null
serial_number	String(50)	unique, not null
type	Enum genesis_type	not null	STANDARD/ENHANCED/SPECIALIZED/ADVANCED/EXPERIMENTAL/QUANTUM
status	Enum genesis_status	default INACTIVE	INACTIVE/DEPLOYING/ACTIVE/COMPLETED/FAILED/UNSTABLE/ABORTED
owner_id	UUID FK players.id	not null
creator_faction	String	nullable
ship_id	UUID FK ships.id	nullable	when stored on a ship
sector_id	Integer	nullable	when deployed
planet_id	UUID FK planets.id	nullable	target planet
deployed_at	DateTime	nullable
terraforming_power	Integer	default 100
terraforming_types	ARRAY(String)	default []
resource_generation, special_features	JSONB / ARRAY	defaults
phase, total_phases	Integer	default 0 / 1
progress	Float	default 0.0	0.0-1.0
estimated_completion	DateTime	nullable
resource_consumption	JSONB	default {}
stability	Float	default 1.0
failure_chance	Float	default 0.0
security_level	Integer	default 1
access_code	String	nullable
result_planet_type	String	nullable
result_planet_quality	Float	nullable	0.0-2.0
result_resources, result_special_features	JSONB / ARRAY	nullable

Relationships: - owner → Player. - ship → Ship, planet → Planet (the resulting planet). - formations → PlanetFormation (1:many, cascade delete).

PlanetFormation

Source: services/gameserver/src/models/genesis_device.py

Purpose: Per-deployment record of a Genesis device's formation process; produces a Planet.

Fields: id, genesis_device_id (FK), sector_id, original_conditions JSONB, started_at, completed_at, estimated_duration (hours), current_phase, total_phases, is_completed, is_failed, failure_reason, resulting_planet_id (FK planets.id), formation_log JSONB, anomalies JSONB.

Relationships: genesis_device → GenesisDevice; resulting_planet → Planet.