Skip to content

Quantum Resources

The two-tier exotic-material chain that powers late-game infrastructure: Quantum Shards (raw, gathered) refine into Quantum Crystals (assembled, consumed). Crystals are the keystone material for player-built warp gates, Genesis-tier construction, and end-game equipment.

Overview

Item Form Source Stack Cargo cost
Quantum Shard Raw Nebulae, anomalies, salvage, black market, trade Integer 1 unit/shard
Quantum Crystal Refined 5 Shards refined at SpaceDock or Class-3+ station Integer 1 unit/crystal

Both items are first-class entries in models/resource.py:ResourceType (QUANTUM_SHARDS, QUANTUM_CRYSTALS).

Why two tiers

Splitting raw shards from refined crystals serves several goals:

  • Gathering pacing — shards drop in small numbers from many sources, so progress is visible early.
  • Refining as a credit gate — the 10,000 cr refining fee is the v1 anti-stockpile mechanism; conversion is instant. A timed RefineJob queue is a deferred option for a future balance pass.
  • Player-economy depth — shards are tradeable in bulk; crystals are a more concentrated, higher-margin commodity.
  • Loss surfaces — destroyed Warp Jumpers drop unused shards and crystals separately, giving combat salvage richer texture.

Status: ✅ Shipped — resource enums, inventory storage, nebula harvesting (POST /quantum/harvest), and PvP combat-loot transfer. 🚧 Partial — refining and the remaining consumption pipelines (see per-section markers below).

Nebula types and field strengths

Nebulae are defined at the cluster level during galaxy generation; member sectors with type = NEBULA inherit the cluster's nebula type. All nebulae yield Quantum Shards as their primary resource; field strength is monotonic from Crimson (richest) to Obsidian (sparsest), and each type carries a distinct secondary effect for gameplay differentiation.

Nebula type Color color_hex Quantum field strength Shard yield per harvest Secondary effect Spawn weighting
Crimson Red #DC143C 80–100 2–3 Mild combat advantage (heat-glow concealment) Frontier 40%, Border 30%
Azure Blue #1E90FF 60–80 1–3 Stable warp formation in-cluster Federation 50%, Border 20%
Emerald Green #00FF7F 50–70 1–2 Production bonus on adjacent planets Federation 30%
Violet Purple #9370DB 40–60 1–2 Rare-spawn bias (exotic encounters) Border 30%, Frontier 30%
Amber Yellow/Orange #FF8C00 20–40 0–1 Hull damage hazard while traversing Border 20%, Frontier 20%
Obsidian Black #2F4F4F 0–20 0–1 (rare ×5 crit, ~1-in-50) Sensor masking; severe warp disruption Federation 20%, Frontier 10%

The color_hex values are the canonical galaxy-map render colors written into Cluster.nebula_properties.color_hex at generation time.

Status: 🚧 Partial — SectorType.NEBULA is generated and zone-weighted nebula type distributions exist in galaxy_service.py, but per-cluster nebula_type and quantum_field_strength fields are not yet persisted on models/cluster.py.

Five shard sources

1. Nebula harvesting (primary)

Equip a Quantum Field Harvester module and dock-out into a sector whose cluster carries a nebula type. Per-attempt:

  • Credit cost: none.
  • Turn cost: 8 turns (HARVEST_NEBULA_TURN_COST).
  • Real-time cooldown: 2 hours per attempt.
  • Yield: rolled against the nebula's quantum field strength (see table above).
  • Critical yield: ~1-in-50 attempts roll a multiplier (×2 typical, ×5 in Obsidian).

Status: ✅ Shipped — POST /quantum/harvest (services/gameserver/src/api/routes/quantum.py:141) calls quantum_service.harvest_nebula (services/gameserver/src/services/quantum_service.py:801) to roll yield against the nebula's field strength, credit shards to the player's quantum wallet, and arm the 2-hour per-ship cooldown.

2. Anomaly investigation (secondary)

Sector special features (SectorType.ANOMALY / spatial anomalies generated via galaxy services) can drop shards on investigate.

Outcome Probability Result
Nothing 60% Wasted turns
1 shard 25% +1
2 shards 10% +2
Ambush 4% NPC encounter
Jackpot 1% +5 shards

Investigation cost: 20 turns + 30 minutes real-time.

Status: 📐 Design-only — no anomaly investigation endpoint exists.

3. Combat salvage (rare)

Defeated NPC hulls or destroyed enemy gates may drop shards.

Source Drop rate Yield
Quantum Smuggler NPC 5% 1–2
Rogue Scientist encounter 15% 1–3
PvP Warp Jumper kill (pre-expedition) 100% of victim's unused shards/crystals variable
PvP Warp Jumper kill (mid-Phase-2 of a gate expedition) 100% of victim's remaining shards/crystals — but the gate-expedition Crystal has already been consumed at Phase 1 beacon deploy and is not in cargo to drop variable, excludes the expedition Crystal
Destroyed warp gate 0% (Crystal consumed at Phase 1 beacon deploy, not at the gate itself) —

Status: ✅ Shipped (PvP Warp Jumper kill) — on a PvP kill the combat resolver transfers 100% of the victim's quantum shards and crystals to the victor via combat_service._transfer_quantum_wallet (services/gameserver/src/services/combat_service.py:4091). 📐 Design-only — the NPC-hull and destroyed-gate drop tables (Quantum Smuggler, Rogue Scientist) are not yet implemented.

4. Black market (Fringe Alliance ports)

Lawless ports (policing < 2) controlled by the Fringe Alliance carry small shard inventories.

  • Stock: 1–2 shards every 7 real-time days.
  • Price: 50,000–100,000 cr per shard (10–20× implied resource value).
  • Reputation gate: negative Federation standing required.

Status: 📐 Design-only — black market port type and reputation-gated stock not implemented.

5. Player trade

Direct exchange between players via team treasury, station markets, or escrowed trades. No system-imposed price floor.

Common trade patterns:

  • Specialist gatherer + builder — dedicated nebula-runner sells shards in bulk to a Warp Jumper pilot.
  • Team pool — team members deposit shards into the team treasury; team-funded warp gates draw from it.
  • Crystal arbitrage — refining a crystal at a fast SpaceDock and reselling near a high-traffic gate-construction zone.

Status: 🚧 Partial — generic player-to-player trading exists; quantum-shard-specific listings rely on the standard market path in services/realtime_market_service.py.

Quantum Field Harvester (ship module)

A bolt-on cargo-bay module that enables shard extraction in nebula sectors.

Attribute Value
Purchase cost 50,000 cr
Install location Class-7+ Technology Port
Install time 24 real-time hours
Compatible ships Scout, Fast Courier, Defender, Warp Jumper
Stock equipment on Warp Jumper
Slot flag (target) Ship.quantum_harvester_slot: bool
Removable Yes (refunds 25% of purchase cost)

Total entry cost for a new player (Scout 30k + Harvester 50k) = 80,000 cr to start gathering.

Status: 📐 Design-only — quantum_harvester_slot column and install endpoint are not present in models/ship.py.

Harvest mechanics

Preconditions

  1. Player ship is in a sector where sector.type = NEBULA and the cluster carries a nebula type.
  2. Ship has Quantum Field Harvester equipped (Ship.quantum_harvester_slot = True — target column).
  3. Ship is docked-out (in space, not at a station).
  4. Player has ≥ 8 turns (no credit cost).
  5. Ship's harvester is off cooldown (2-hour real-time per ship).
  6. Player cargo has at least 1 free unit.

Resolution

  1. Server reads the cluster's nebula_type and quantum_field_strength (target fields).
  2. Roll attempt_success ~ uniform(0, 100) < quantum_field_strength. Failure yields 0 shards but still costs credits and turns (sunk cost; partial refund of 50% of credits on miss is a design option).
  3. On success, draw shard_count uniformly from the nebula type's yield range.
  4. Roll crit ~ uniform(0, 1) < 0.02. On crit, multiply yield by the nebula's critical multiplier (×2 default; ×5 in Obsidian).
  5. Add shards to player cargo; deduct credits and turns; start the 2-hour cooldown timer on the ship row.
  6. Emit a real-time event on the WebSocket bus so the client UI updates without polling.

Concurrency and anti-abuse

  • Per-ship cooldown — switching ships does not stack harvests; the cooldown lives on the ship row to prevent multi-ship harvest bursts from a single sector.
  • Per-sector soft cap — a single sector cannot yield more than ~50 shards/day across all harvesters before the field "depletes" temporarily (24h regen). Design.
  • Locking — the harvest endpoint takes with_for_update on the ship row to serialize concurrent attempts.

Status: ✅ Shipped — quantum_service.harvest_nebula (services/gameserver/src/services/quantum_service.py:801) enforces the preconditions, rolls yield against field strength, credits the player wallet, and arms the 2-hour per-ship cooldown. 📐 Design-only — sector-level depletion soft-cap.

Nebula harvesting mechanic

📐 Design-only. This section formalizes the per-attempt nebula harvesting loop that backs Nova Scientific Institute reputation gains and Lumen Crystal sourcing. It refines and extends the higher-level Harvest mechanics flow above with sub-type specifics, equipment ladders, depletion behaviour, and rep hooks.

Where harvesting happens

Harvesting resolves only in sectors whose Sector.type = NEBULA. Nebula sectors comprise roughly 10% of the galaxy (per the cluster-level distribution in generation.md). Each nebula sector inherits its sub-type from the parent cluster and exposes a single per-sector field state used by harvest, depletion, and replenishment.

Harvesting uses the canonical 6-color taxonomy from Nebula types and field strengths above; the legacy 4-sub-type names (Emerald, Violet) were inconsistent forks of the canonical color set and are retired. Per-color harvest properties:

Color Approx. share of all sectors Shard yield multiplier Lumen Crystal drop Notable secondary effect
Crimson ~2% 1.0× (baseline, highest) 0.2% per harvest Highest-value Nova Scientific data; heaviest depletion
Azure ~3% 0.5× 0% Mid yield; stable harvesting
Emerald ~3% 0.3× (low Shard) 1% per harvest The canonical Lumen Crystal source (was "Emerald" in the legacy table)
Violet ~2% 0.3× 0% Sensor occlusion strongest here; preferred for stealth (was "Violet" in the legacy table)
Amber ~1% 📐 Design-only 📐 Design-only Hull damage hazard while traversing per the field-strengths table; harvest properties tuned in a future pass
Obsidian <1% 📐 Design-only 📐 Design-only Sensor masking + severe warp disruption; harvest properties tuned in a future pass

Crimson is the highest-yield classification and the rarest. Emerald trades raw Shard throughput for the Lumen Crystal pull. Violet is yield-equivalent to Emerald on Shards but offers stealth instead of the Crystal drop. Amber and Obsidian round out the ambient-flavor palette and will receive harvest tuning when the long-tail balance pass lands.

Equipment required

The Quantum Field Harvester equipment slot is the single gating module. Source of truth for the equipment definition is ship-systems.md (EQUIPMENT_DEFINITIONS.quantum_harvester). Compatible ship classes are Scout, Fast Courier, Defender, and Warp Jumper — no other hull may install the harvester.

Harvester upgrade level Yield multiplier Notes
L0 (stock install) 1.0× Default state on purchase.
L1 1.25× First upgrade tier.
L2 1.5× Second upgrade tier.
L3 2.0× End-game tier; required for top-band Crimson yields.

The harvester upgrade ladder is multiplicative with the nebula sub-type multiplier. Upgrade purchase costs and install venues are 📐 Design-only and live with the canonical equipment definition in ship-systems.md.

The Sensor equipment ladder (📐 Design-only — see ship-systems.md) interacts with harvesting at L3: Sensor L3 reduces field instability and adds a flat +1 Shard per harvest on top of the rolled yield band. Sensor levels below L3 have no harvest effect.

Per-attempt mechanic

A harvest attempt costs 8 turns — slightly more than asteroid mining (cross-link to ../economy/mining.md) because the quantum field is unstable and stabilising it consumes additional ship time. The attempt resolves in a single server tick:

  1. Validate preconditions per the existing Harvest mechanics → Preconditions list (gates on turns and equipment; no credit cost).
  2. Read the sector's nebula sub-type and current depletion state.
  3. Roll a Shard count uniformly from the sub-type's yield band, scaled by harvester_multiplier × sub_type_multiplier.
  4. If Sensor L3 is fitted, add a flat +1 Shard.
  5. Roll the Lumen Crystal drop using the sub-type's drop rate.
  6. Apply per-sector depletion (see Nebula depletion below).
  7. Credit Shards (and any Crystal drop) to player cargo; deduct turns; emit a real-time event.

The 50% credit-refund-on-miss design option from the higher-level harvest section does not apply to this loop — Sensor L3 already eliminates the miss surface.

Yield bands per harvest

Yield bands are stated for harvester L0 and L3 with no Sensor bonus; intermediate harvester levels interpolate by the multiplier ladder above. Sensor L3 adds +1 Shard to every band's lower and upper bound.

Color Harvester L0 band Harvester L3 band Lumen Crystal drop
Crimson 2–4 Shards 4–8 Shards 0.2% per harvest
Azure 1–2 Shards 2–4 Shards 0%
Emerald 0–1 Shards 0–2 Shards 1% per harvest
Violet 0–1 Shards 1–2 Shards 0%

A Crimson nebula with a Warp Jumper running harvester L3 + Sensor L3 therefore yields 5–9 Shards per attempt (4–8 band, +1 sensor bonus), which sets the upper bound for solo extraction throughput.

Lumen Crystal sourcing

Lumen Crystals have two canonical sources — primary harvest drops, plus a refining path at high-class stations.

Primary: nebula harvest drops. - Emerald nebulae: 1% per harvest. The dominant source. - Crimson nebulae: 0.2% per harvest. A rare bonus on the highest-Shard color. - Azure and Violet nebulae do not drop Lumen Crystals. - Amber and Obsidian harvest properties are 📐 Design-only (see the canonical color table).

Secondary: Shard-to-Crystal refining at Class-5+ stations. A Class-5 (or higher) station with a quantum_refining service consumes 100 Quantum Shards to produce 1 Lumen Crystal, with a 12-hour real-time refining timer (half the Quantum Crystal refine for the higher-tier Lumen output). The refining service is gated by the same exotic_technology-class venue list as Quantum Crystal refining. This path lets gate-builders convert abundant Shard supply into the rarer Crystal at a credit cost (the station's refining fee, ~10,000 cr per job) — making Lumen Crystals scarce-but-reachable rather than blocked behind 1% RNG.

Both paths feed the same Player.lumen_crystal_inventory count; downstream consumers (warp gates, Warp Jumper builds) don't distinguish source.

Combined per-gate demand: 50 Lumen Crystals (30 at Phase 3 anchor + 20 in the Warp Jumper recipe — see ./warp-gates.md). At 1% Emerald drop that's ~50 lucky harvests; via refining that's 5,000 Shards (achievable in days of dedicated harvesting). The two paths can be mixed. Per ADR-0037.

Nebula depletion

Per-sector depletion mirrors the asteroid-field model documented in ../economy/mining.md, with three states (Healthy, Light depletion, Heavy depletion) and a self-replenishment timer that ticks regardless of player presence.

Sub-type Depletion per harvest Heavy-depletion threshold Full-reset replenishment
Crimson Heaviest (most fragile) After ~10 harvests in 24 h 14 real-time days
Azure Light After ~30 harvests in 24 h 5 real-time days
Emerald Light After ~30 harvests in 24 h 5 real-time days
Violet Light After ~30 harvests in 24 h 5 real-time days

While a sector is in Light depletion, yield bands shift down by 1 (lower and upper bound). While in Heavy depletion, harvest attempts return 0 Shards and 0 Crystals but still cost turns. Depletion state is per-sector, not per-cluster, so adjacent nebula sectors of the same sub-type replenish independently.

Faction reputation hooks

📐 Design-only. Cross-link to factions-and-teams.md#reputation-triggers for the underlying reputation API and decay rules.

Trigger Reputation effect
Harvest Quantum Shards in any nebula +1 Nova Scientific Institute rep per 3 Shards harvested
First-scan a nebula sector before any harvest +15 Nova Scientific Institute rep (one-shot per sector, intelligence value)
Harvest in a Crimson nebula specifically +1 Nova Scientific Institute rep per Shard (4× the baseline rate; Nova prizes high-field-strength data)
Lumen Crystal drop reported to a Nova-flagged station +10 Nova Scientific Institute rep per Crystal
Harvest in a nebula adjacent to an Astral Mining-influence sector with no Astral Mining license +5 Frontier Coalition rep per harvest, −5 Astral Mining Consortium rep per harvest

The Crimson-specific bonus stacks on top of the baseline "+1 NS / 3 Shards" hook. The asymmetric Astral Mining contest is the primary three-way tension surface for nebula harvesters: Frontier Coalition gains rep for contested extraction, Astral Mining loses rep at the same magnitude, and the player keeps the harvest output regardless.

Combat and hazard interaction

Nebulae occlude long-range scans (canonical per ../economy/black-market.md) and additionally:

  • Reduce ship current_speed by 25% while the ship is inside a nebula sector. Movement turn costs are unchanged; the speed reduction surfaces in encounter resolution and chase mechanics.
  • Disable Quantum Jump origination from inside a nebula sector. A Warp Jumper must travel to a clear-space sector before initiating Phase 1 of a Quantum Jump (cross-link to ./sectors.md#quantum-jump-warp-jumper).

Violet nebulae apply the strongest occlusion factor among the four sub-types and are the preferred staging environment for stealth play; Crimson sits at the standard nebula occlusion level. Cross-link to ./sectors.md for sector-level runtime mechanics.

PvP interaction

Mirroring asteroid mining (cross-link to ../economy/mining.md), harvesting freezes the ship in place for the duration of the attempt: Ship.status = MINING. While MINING:

  • The ship cannot move, dock, or initiate combat actions.
  • Incoming combat from another player or NPC immediately cancels the harvest. The cancelled harvest yields 0 Shards and 0 Crystals, and the player is refunded 50% of the 8-turn cost (4 turns returned).
  • The 50% turn refund applies regardless of whether the interrupting attacker successfully damages the ship.
  • The harvester upgrade and Sensor upgrade are not damaged by an interrupted harvest.

Combat interrupts are the dominant PvP pressure surface against solo Crimson harvesters — a Crimson nebula's depletion fragility plus its 14-day replenishment make a contested Crimson sector an attractive denial target.

Refining shards into crystals

5 Quantum Shards → 1 Quantum Crystal, performed at any Class-3+ station or SpaceDock.

Attribute Value
Inputs 5 Quantum Shards
Output 1 Quantum Crystal
Refining fee 10,000 cr
Refining time Instant (services/gameserver/src/services/refining_service.py)
Failure rate 0% (deterministic)
Concurrency Multiple jobs per player allowed

Refining flow

  1. Player docks at a Class-3+ station or SpaceDock (Quantum Crystal refine) or Class-5+ station (Lumen Crystal refine per ADR-0037).
  2. Submit a refine request — server runs an atomic shard-consumption transaction per ADR-0049: SELECT Player FOR UPDATE, validate quantum_shard_inventory >= required, decrement inventory, deduct 10,000 cr, credit 1 Quantum Crystal. All in one transaction. Concurrent refining attempts referencing the same shard inventory hit the row-lock and fail the inventory check.
  3. The crystal appears in the player's inventory immediately; no pickup or queue step required.

A timed RefineJob queue (24h timer per job, multiple slots per station) is a deferred design option for a future balance pass and is not part of the v1 shipped model.

Status: ✅ Shipped — services/gameserver/src/services/refining_service.py handles instant 5-shard → 1-crystal conversion at 10,000 cr at any Class-3+ station or SpaceDock.

Storage

Shards and Crystals occupy player cargo holds at 1 unit per piece (matching the standard cargo unit cost). A Light Freighter with 100 cargo can carry up to 100 shards (= 20 crystals' worth). Shards and crystals stack as integers on the player's inventory record (currently held in PlayerInventory / equivalent quantum-resource columns or generic resource map).

Status: ✅ Shipped — shards and crystals are stored as Player.quantum_shards and Player.quantum_crystals columns on the Player model (services/gameserver/src/models/player.py); the ARIAQuantumCache model (models/aria_personal_intelligence.py) caches ARIA ghost-trade superposition states and is unrelated to the quantum-resource ledger.

Uses

Crystal uses

Consumer Quantum Crystals required Notes
Player-built warp gate (Phase 1 beacon deploy) 1 ✅ Shipped. warp_gate_service.deploy_beacon consumes 1 Quantum Crystal (PHASE1_QUANTUM_CRYSTALS) at Phase 1 beacon deploy at the source sector — not at the destination focus anchor. Locks Crystal-risk to the source side of the expedition; mid-travel combat losses do not drop the Crystal. See warp-gates.md and ADR-0029.
Warp Jumper construction 1,000 shards (no crystals) Quantum drive component.
Genesis Device (advanced tier) 1 (target) Future enhancement; see genesis-devices.md.
ARIA neural enhancement TBD Future.
End-game weapons TBD Future.

The dominant consumer for the foreseeable game phase is warp-gate construction.

Shard uses

Consumer Quantum Shards required Notes
Crystal refining (per Crystal) 5 See refining shards into crystals.
Warp Jumper construction 1,000 One-time hull material cost; see warp-gates.md.
Quantum Charge refining (per Quantum Jump activation) 1 ✅ Shipped — quantum_service.refine_charge (services/gameserver/src/api/routes/quantum.py:109, POST /quantum/refine-charge). 1 Quantum Shard → 1 Quantum Charge on the piloted Warp Jumper at any Class-3+ station or SpaceDock; charge consumed at Quantum Jump commit. Per-jump cost on the Warp Jumper's directional FTL; see ADR-0030.
Far-band quantum scan 1 📐 Design-only. Per Far-band scan only — short-range scans do not consume shards.

Cost-to-craft summary (one Crystal)

Step Time Cost
Gather 5 shards (Crimson, average yield 2.5/harvest) 2 harvests × (8 turns + 2 h cooldown) ≈ 4 h real 0 cr
Refine 5 → 1 crystal Instant 10,000 cr
Total per Crystal ~4 h real, 16 turns 10,000 cr

A complete warp-gate build (1 Crystal) therefore prices the quantum portion at ~12,000 cr; the bulk of the gate cost lives in the deployment fees and the Warp Jumper itself. See warp-gates.md for the full economic breakdown.

Status: 📐 Design-only — Genesis advanced-tier crystal consumption is not currently coded; current advanced tier sacrifices the Colony Ship instead.

Player-facing affordances

  • Cargo screen shows shards and crystals as separate stackable lines, with a tooltip explaining the 5-to-1 conversion.
  • Sector view in a nebula sector exposes a "Harvest" button when a Quantum Field Harvester is fitted; greyed out when on cooldown, with a real-time countdown.
  • Galaxy map highlights nebula clusters by tint (Crimson red, Azure blue, etc.); hovering shows the inferred field-strength range.
  • Station services menu at Class-3+ stations exposes a "Refine Quantum Shards" entry with current job count and queue position.
  • Notifications fire on harvest success (with yield), critical-yield triggers, refine completion, and shard transfer between players.
  • Black-market shard listings show in the port UI only for players whose Federation reputation gates them in (negative standing required).

Status: 🚧 Partial — generic cargo and station UIs exist; quantum-specific harvest and refine UIs are 📐 Design-only until the backing services land.

Anti-cheat / safety

  • Harvest, refine, and shard-grant endpoints are server-authoritative and atomic — no client-side yield resolution.
  • Yield rolls use a cryptographically secure RNG (matching the standard set in generation.md for Genesis device rolls).
  • Per-ship cooldown timestamps are stored on the ship row, not derived client-side.
  • Shard and crystal grants are written inside the same transaction as the resource deduction (credits, turns) to prevent double-credit on failure.
  • Refine jobs are heartbeated server-side; cancellation is a separate explicit endpoint.

Source map

Topic Path
Resource type enum (Shard/Crystal) services/gameserver/src/models/resource.py:ResourceType
Player inventory (target columns) services/gameserver/src/models/player.py (target)
Quantum harvest service (target) services/gameserver/src/services/quantum_service.py (target)
Harvester module on ship services/gameserver/src/models/ship.py (quantum_harvester_slot — target)
Nebula generation services/gameserver/src/services/galaxy_service.py
Nebula sector flag services/gameserver/src/models/sector.py:SectorType.NEBULA
Cluster nebula properties (target) services/gameserver/src/models/cluster.py (nebula_type, quantum_field_strength — target)
Refining service (target) services/gameserver/src/services/refining_service.py (target)
Anomaly investigation (target) services/gameserver/src/services/anomaly_service.py (target)
Black-market shard stock (target) services/gameserver/src/services/port_service.py (target)
ARIA quantum cache (NOT inventory) services/gameserver/src/models/aria_personal_intelligence.py:ARIAQuantumCache