Genesis Devices¶

The only mechanism for creating new planets in the universe. Three tiers, each with its own cost, formation time, and outcome distribution.

Tier matrix¶

Source: services/gameserver/src/services/genesis_service.py:GENESIS_TIERS.

Tier	Cost (cr)	Sacrifices ship?	Habitability range	Resource richness	Size range
basic	25,000	No	40–60	0.5–1.0	3–6
enhanced	75,000	No	55–75	0.8–1.5	4–7
advanced	250,000	Yes — Colony Ship	70–90	1.2–2.0	5–9

Pricing is tier-based per device. The advanced tier consumes the Colony Ship.

Planet-type weights¶

Each tier rolls a planet type from a weighted distribution. TERRA is reserved for the Capital Sector welcome planet (one per region, generated at universe creation) and is never Genesis-rolled — see ADR-0014. Genesis biases toward OCEANIC (the closest Earth-like target in the post-AU1 12-type taxonomy) at higher tiers.

basic: | Type | Weight | |------|-------:| | OCEANIC | 50 | | DESERT | 20 | | ICE | 15 | | VOLCANIC | 10 | | MOUNTAINOUS | 5 |

enhanced: Oceanic 60, Desert 20, Ice 10, Volcanic 5, Mountainous 5.

advanced: Oceanic 80, Desert 10, Ice 5, Volcanic 3, Mountainous 2.

Higher tiers bias heavily toward Oceanic (best Earth-like target) and away from hostile types.

The Genesis-rollable set is the 5 non-TERRA terraforming targets: OCEANIC, DESERT, ICE, VOLCANIC, MOUNTAINOUS. The other PlanetType enum values are not Genesis-rollable and reach the universe only via natural sources (bang-imported planets, special encounters, operator-seeded sectors): the canonical biomes GAS_GIANT, JUNGLE, ARCTIC, and TROPICAL (nexus_generation_service generates JUNGLE and TROPICAL as colonizable worlds; GAS_GIANT is a real but uncolonizable body), the welcome-world type TERRA, the hostile BARREN, and ARTIFICIAL.

Ship capacity¶

GENESIS_CAPACITY_BY_SHIP:

Ship	Genesis capacity
Light Freighter	0
Cargo Hauler	2
Colony Ship	5
Defender	3
Carrier	5
Warp Jumper	1

The Advanced Genesis path (which sacrifices the Colony Ship) only needs 1 advanced device.

Ships with active Genesis devices suffer: - ~50 cargo units consumed per device for containment. - −20% max travel speed (safety protocols). - −50% drone capacity. - −100 max hull and shields each.

Colony Ship Terraforming Modules grant a −30% Genesis sequence-time bonus when the Colony Ship is the lead vessel of the deployment (solo) or the sacrificed vessel (advanced tier). In team genesis, the bonus applies only when the Colony Ship is the active deployer — a Colony Ship merely present in the team formation grants no bonus.

Formation process¶

Standard tier (basic / enhanced)¶

Acquire devices at a Class 9 Research Station (1–3 in stock, 7-day refresh) or Class 7+ Technology Port. ✅ Enforced (ADR-0088, dev 7062bbb): Federation reputation tier 7 / Heroic — personal_reputation ≥ 250 (the "level ≥ 8" intent, set to a reachable bar; see ADR-0088).
Travel to an empty, non-protected sector. ✅ Enforced (ADR-0088): ≥ 5 jumps from Federation Space; ≥ 2 sectors from any other planet; and a single player may own at most ~25% of a region's planets (anti-monopoly; first planet always allowed). ADR-0088.
Initiate the Genesis sequence:
basic: 1 device.
enhanced: 3 devices.
The 48-hour formation timer (GENESIS_FORMATION_HOURS = 48) runs server-side. The player is free to leave the sector — the forming planet is invulnerable on its own (see Formation-window protection).
During the sequence, the player has a reduced turn cap (50/day) — design.
On completion, devices are consumed and a planet is generated using the weighted distribution.
Ownership auto-assigned to the deploying player.

Aborting the sequence loses all devices.

Formation-window protection¶

While a Genesis-created planet has formation_status == "forming" (the 48h window for basic/enhanced; effectively zero seconds for advanced, which sets formation_status = "complete" on creation), the planet is invulnerable:

Cannot be landed on — the landing endpoint rejects with "this planet is still forming" (services/gameserver/src/api/routes/planets.py — landing handler checks planet.formation_status == "forming").
Cannot be attacked — the attack_planet path must reject ship-vs-planet combat against a forming target (services/gameserver/src/services/combat_service.py:attack_planet).
Genesis device cannot be reclaimed — devices are consumed at deployment and the forming planet has no salvage path.
The deploying player can leave the sector freely without aborting the sequence; formation completes purely on the server-side timer in GenesisService.check_formation_status (services/gameserver/src/services/genesis_service.py). The lock-to-sector requirement only applies to Genesis Teams (see below), where any member leaving collapses the sequence.

Once formation_status flips to "complete", the planet enters the normal lifecycle and is defenseless until the Outpost citadel finishes its initial drone deployment.

✅ Fixed (2026-06-13, 2e930dd) — the formation_status == "forming" guard is now enforced on combat_service.attack_planet (before turn deduction) and on player_combat._execute_planet_assault (before the no-defenses check, so a freshly-formed defenseless planet returns "still forming" rather than "no defenses to assault"). Proven live: an authenticated assault on a forming planet returns 400 "This planet is still forming and cannot be attacked" (control: a non-forming defenseless planet returns "no defenses to assault"); the planet took no damage and the attacker spent no turns. The WPN combat-target list also omits forming planets (defense-in-depth). Verified in FINDINGS.md Gameplay verifications.

Advanced tier (Colony Ship sacrifice)¶

Pilot a Colony Ship with at least 1 advanced device.
Initiate the sacrifice sequence in a valid empty sector.
Colony Ship is consumed immediately + devices consumed.
Player auto-transferred to escape pod.
Planet generates immediately (no 48-hour wait).
Starts at Settlement phase (citadel level 2), 5,000 colonists, +10% production bonus, 4 automated turrets, basic shield generator.

This bypasses the standard Outpost phase entirely — it's the express lane to a viable colony at the cost of a ~500k Colony Ship hull.

Planetary registration¶

At deploy the founder also chooses a registration tier — a separate axis from the device tier (which sets the world's quality). Registration sets the world's legal status and is charged as a Planetary Registration Fee on top of the device sequence cost. See ADR-0084.

Tier	On the public registry / star-charts?	Federation legal protection?	Fee
Clandestine	No — off the books	No	flat 60,000
Registered (default)	Yes, under the founder's name	No	flat 10,000
Chartered	Yes	Yes — protected	`10,000 + 40,000 × (1 − repFactor)`, `repFactor = clamp(personal_reputation/1000, 0, 1) × 0.75` (≈50k at low rep → 20k at +1000)

Chartered confers Federation protection: assaulting a chartered planet is a crime that costs the aggressor −50 personal reputation. Founding a chartered world nudges the founder +25 reputation. Protection grows cheaper as the founder's standing rises.
Clandestine is genuine privacy: the world is absent from the public registry and the registry lookup below. Privacy ≠ invisibility — the planet still physically forms and orbits in its sector; only the records hide it.
Status is stored at planet.active_events['registration_status'] (no migration); a missing key reads as registered (visible). A planet can be upgraded later (Clandestine → Registered/Chartered) by paying the difference.

Registry lookup (black-market intel)¶

Prying into a commander's holdings is only available through less-reputable channels — the SpaceDock Black Market, gated on negative personal reputation (personal_reputation < 0). POST /api/v1/registry/lookup {playerName} returns the named player's Registered + Chartered planets (name, sector, type, status) for 50,000 cr. Clandestine worlds never appear — even the black market can't list what was never filed; that asymmetry is the point of the privacy premium. Unknown names (404) and targets with no visible holdings are never charged. You must know the name — you cannot enumerate the galaxy.

Restrictions¶

Sector must be empty at deploy time — zero planets, stations, or anomalies present. (Pre-flight cap of MAX_PLANETS_PER_SECTOR = 5 is the absolute upper bound for sectors that already host natural / bang-imported planets, but Genesis itself only deploys into sectors that are currently empty.)
Cannot deploy in protected sectors (e.g. the Capital Sector and adjacent fedspace anchor sectors — first fedspaceSize sectors of the region, default 10 — and faction capital areas).
Cannot deploy within 5 jumps of Federation Space (design).
Cannot deploy within 2 sectors of an existing planet (minimum spacing — design).
Anti-monopoly: single player capped at ~25% of planets in any region (design).
Rate limit: max 3 device purchases per real week per account (design).
Sequence participation: max 1 every 14 days per player (design).

🚧 Partial — most of the rate-limit and anti-monopoly logic exists as design constants; code currently enforces basic empty-sector and ownership rules.

Genesis teams¶

Multiple players can pool devices for a shared planet: - All members must be in the sector throughout the 48h sequence (definition below). - At least one ship must be Genesis-capable. - If any team member leaves the sector (definition below), the sequence fails and devices are lost. - Ownership shares record contribution percentages. - Colony Ship sacrifice variant: sacrificing player gets 50%, remainder split per agreement.

"In the sector" — detection criteria¶

📐 Design-only. The 48h Genesis-Team sequence runs a per-tick presence check on every team member. Each member is considered "in the sector" if any of:

Their Player.current_sector_id matches the formation sector.
Their ship is docked in a Carrier hangar that is itself in the formation sector — hangar passengers count as in-sector for the duration the carrier remains.
They are in an escape pod in the formation sector — the auto-eject from a destroyed ship does not count as leaving, and the pod's continued presence in the sector keeps the team-member presence flag set.
They are within a 15-minute reconnect grace after a network disconnect. The presence check tolerates a 15-minute gap; reconnects within that window restore presence without firing the failure path. Disconnects beyond 15 minutes count as a sector departure.

A member is considered to have left the sector if any of:

They warp to a different sector under their own power.
Their ship is tractor-towed out of the sector by a hostile (non-team) player — hostile extraction counts as a sector departure even though the member did not initiate it. The towed-out player chose to be in a sector with hostile tractor-equipped ships; the towing is a real-world consequence.
They disconnect for more than 15 minutes without reconnecting.
They explicitly abandon the formation via a player action.

A team-mate-initiated tow that keeps the member in the formation sector does not count as departure (the member stays in-sector).

🚧 Partial / Planned — multi-player Genesis is documented in design; code path supports single-player creation.

Anti-cheat / safety¶

All Genesis transactions are atomic with rollback on failure.
48h sequence runs server-side with heartbeat verification.
Planet type rolled with cryptographically secure RNG (server-side).
Genesis device serial numbers tracked to prevent duplication.

Player-facing affordances¶

Genesis purchase UI at Research Stations with rarity warnings, ship-capacity preview, refresh countdown. (✅ shipped 2026-06-16 — the SpaceDock genesis store sells a single fungible Genesis Device at a flat 25k with a live ship-capacity orb display and a "N of 3 acquisitions left this week" readout; the fictional 3-tier "success rate / process hours" cards are gone. Tier + sequence cost are chosen at deploy.)
Genesis sequence UI showing 48-hour progress with progressive planet-formation visuals. (✅ shipped 2026-06-14 — a deploy-moment animation, and a live in-progress readout in the Colonial Registry: forming planets show a 🌱 TERRAFORMING badge + marching progress bar + "Nd Nh left" countdown off formationStartedAt/formationCompleteAt, auto-completing on read.)
Three-mode selector (Basic / Enhanced / Advanced).
Emergency abort button (with clear "all devices lost" warning).
Genesis Team coordination panel for shared planet creation.
Mobile push notifications for sequence milestones.

Source map¶

Topic	Path
Genesis service	`services/gameserver/src/services/genesis_service.py`
Genesis device model	`services/gameserver/src/models/genesis_device.py`
Planet model + types	`services/gameserver/src/models/planet.py`
Genesis API routes	`services/gameserver/src/api/routes/genesis.py`
Ship Genesis-capacity column	`services/gameserver/src/models/ship.py` (`max_genesis_devices`)
Related: terraforming	planets/terraforming.md
Related: colonization	planets/colonization.md

Status: ✅ Shipped — genesis deploy commits end-to-end (verified live: purchase increments ship.genesis_devices; deploy consumes one device, creates a forming planet, and lazily completes to a COLONIZED colony on the owned-planets fetch). Genesis rolls only the canon-rollable set — OCEANIC / DESERT / ICE / VOLCANIC / MOUNTAINOUS — at the tier weights above; the other canonical types (TERRA, GAS_GIANT, JUNGLE, ARCTIC, TROPICAL, BARREN, ARTIFICIAL) reach the universe via natural sources rather than Genesis (ADR-0014), not a validator bug. ✅ Deploy UX hardened (2026-06-14, a61022b): the player's chosen colony name is now honored (the legacy route passes planetName into deploy_genesis_device; it was silently discarded before — proven: deploy "Maxhaven Prime" → planet named "Maxhaven Prime"). The deploy panel defaults the target to the player's current sector (was a raw sector-id type-in), the "🌌 Deploy Genesis" control is labeled/discoverable in the Colonies screen (was a bare icon, only shown in the zero-planets empty state), and the misleading client type-picker (showed non-canon terran/frozen, missing volcanic, and was ignored) is replaced with an honest "biome is determined by the device" note. ✅ Basic + Enhanced tiers shipped (2026-06-14, b59ab42): deploy now offers a tier selector — basic fuses 1 device (25k cr, hab 40–60), enhanced fuses 3 (75k cr, hab 55–75) into one richer world. deploy_genesis_device consumes the canon device count (GENESIS_DEVICE_COST) and pre-checks the player carries enough; the legacy route takes a tier param. This fixes "deploy only does one at a time." Proven live: enhanced consumed 3 devices → 1 oceanic planet at hab 75, −75k cr; basic consumed 1 (3→2); enhanced rejected with only 2 devices ("needs 3"). See FINDINGS. A canon-blessed deploy-moment animation plays on success. ✅ Advanced tier shipped (2026-06-14, c6f7ac1): all three tiers are now offered at deploy. Advanced (250k cr + 1 device) sacrifices the player's Colony Ship and builds the colony instantly at Settlement — status COLONIZED, citadel L2, 5,000 colonists, +10% production (the L2 citadel bonus), 4 turrets, basic shield — no 48h wait (ADR-0013). The pilot ejects to an escape pod via ship_service.destroy_ship(cause="genesis_sacrifice") (a voluntary consume: all cargo transfers to the pod, no insurance payout — sacrificing an insured hull for a planet must not double-dip). The client tier card is gated on flying a Colony Ship and a two-step "confirm sacrifice." Proven live: deploy advanced → planet COLONIZED/complete, citadel 2, 5,000 colonists, 4 turrets, shield 1; Colony Ship destroyed; player in ESCAPE_POD; −250k cr; device consumed. See FINDINGS. ✅ Buy-side canon + forming-planet visual (2026-06-16, 438373c): the SpaceDock genesis store no longer sells fictional standard/advanced/experimental tiers with fake "success rate" stats — it sells one fungible Genesis Device at a flat 25k, enforces the canon 3/week acquisition limit (was unlimited; the limit moved to acquisition where canon puts it, and deploy no longer double-counts it) with a "N of 3 left this week" readout, and shows real ship capacity. Proven live: 3 buys at −25k each (remaining 2/1/0); the 4th rejected by the weekly limit. And a still-forming planet now renders distinctly in the sector viewport — celestial_service emits formation_status in the /sectors/{id}/system snapshot (proven: a forming planet's body carries formation_status: "forming"), and SolarSystemViewscreen draws an accretion halo + inward-spiralling dust + a pulsing containment ring + a "GENESIS FORMING…" label, with the tooltip reading "GENESIS TERRAFORMING IN PROGRESS". See FINDINGS. ✅ Planetary registration shipped (2026-06-16, 3d887a2, ADR-0084 Accepted): the deploy charge is now a Planetary Registration Fee with three tiers (Clandestine 60k / Registered 10k / Chartered rep-scaled), charged on top of the device sequence cost — see the "Planetary registration" section above. Chartering grants +25 reputation and Federation protection (assaulting a chartered planet costs the aggressor −50 rep); a black-market registry lookup (50k, negative-rep only) surfaces a named player's non-clandestine planets. Proven live (deploy fees + rep-scaling + nudge; lookup inclusion/exclusion + 403/404/charge gates; combat penalty). See FINDINGS.

Economy resolved (ADR-0084): the former "double-charge" is now two named, justified line items — the 25k device acquisition + the registration fee at deploy (the reframed sequence charge). No longer an open question.