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 real-time gate — the 24-hour refine timer prevents fast-stockpiling of crystals via burst harvesting.
  • 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 and inventory storage. 🚧 Partial — gathering, refining, and 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 special_type = NEBULA inherit the cluster's nebula type. Quantum field strength drives shard yield per harvest.

Nebula type Color Quantum field strength Shard yield per harvest Spawn weighting
Crimson Red 80–100 2–3 Frontier 40%, Border 30%
Azure Blue 60–80 1–3 Federation 50%, Border 20%
Emerald Green 50–70¹ 1–2 Federation 30%
Violet Purple 40–60¹ 1–2 Border 30%, Frontier 30%
Amber Yellow/Orange 20–40 0–1 Border 20%, Frontier 20%
Obsidian Black 0–20¹ 0–1 (rare crit yield 5) Federation 20%, Frontier 10%

¹ Approximate. Legacy spec gives Emerald 40–60, Violet 70–90, Obsidian 50–70 with stealth/sensor effects rather than shard yields. The values above re-anchor the table to a monotonic shard-yield curve consistent with Crimson > Azure > Emerald > Violet > Amber > Obsidian. Tune in services/gameserver/src/services/galaxy_service.py (nebula type → field-strength roll) when nebula generation lands.

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: 1,000 cr.
  • Turn cost: 15 turns.
  • 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: 🚧 Partial — harvester module is on ship-spec roadmaps but not yet wired into services/gameserver/src/services/; nebula sectors are generated, but no harvest endpoint exists.

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 100% of victim's unused shards/crystals variable
Destroyed warp gate 0% (Crystal is consumed at activation) —

Status: 📐 Design-only — drop tables not implemented; combat resolver does not currently emit quantum loot.

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 25k + Harvester 50k) = 75,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.special_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 ≥ 1,000 credits and ≥ 15 turns.
  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: 🚧 Partial — preconditions enforceable from existing models, but no services/gameserver/src/services/quantum_service.py:harvest_nebula exists yet. Sector-level depletion is 📐 Design-only.

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 24 real-time hours
Failure rate 0% (deterministic; the 24h timer is the cost)
Cancel Refund shards but lose 25% of fee
Concurrency Multiple jobs per player allowed; one per station per player
Capacity Class-3 stations process 1 job at a time; SpaceDock processes up to 5 in parallel

Refining flow

  1. Player docks at a Class-3+ station or SpaceDock.
  2. Submit a refine job with 5 shards and 10,000 cr — server deducts both up-front, creates a job row.
  3. Stations expose a refining_queue JSONB array on the station record; jobs include player_id, started_at, completes_at.
  4. At completion, the server credits 1 Quantum Crystal to the player's inventory and emits a notification.
  5. The crystal need not be picked up at the station — it appears in the player's inventory wherever they are.

Status: 📐 Design-only — refining endpoint and station-side queue not implemented. Crystals are constructible only via direct admin grant today.

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/crystals enumerated in ResourceType; storage falls through the generic resource path. 🐛 Bug — models/aria_personal_intelligence.py:ARIAQuantumCache is not the player's quantum-resource ledger; it caches ARIA ghost-trade superposition states. The naming overlap is misleading. Player shard/crystal counts must live on a dedicated player-inventory row (target: PlayerInventory.quantum_shards, PlayerInventory.quantum_crystals), not aria_quantum_cache.

Uses

Consumer Quantum Crystals required Notes
Player-built warp gate (initialize) 1 Consumed at activation. See warp-gates.md.
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.

Cost-to-craft summary (one Crystal)

Step Time Cost
Gather 5 shards (Crimson, average yield 2.5/harvest) 2 harvests × (15 turns + 2 h cooldown) ≈ 4 h real 2,000 cr
Refine 5 → 1 crystal 24 h real 10,000 cr
Total per Crystal ~28 h real, 30 turns 12,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