Skip to content

Economy Lifecycle — The Money Loop

How credits are minted, circulated, and destroyed in SectorWars 2102. Sister doc to trading.md, which covers the station pricing engine; this doc covers the macro flow — every faucet, every sink, the target ratios between them, and the levers admins pull when the loop drifts.

A healthy economy has roughly balanced inflow and outflow at the population level, with mild deflationary pressure from sinks so that effort retains meaning. When faucets dominate, prices spiral and rank progression cheapens; when sinks dominate, players cannot afford ships and quit.

1. Sources of credits (faucets)

Every credit in circulation originated at one of these. Citations are target homes for the spawn logic.

1.1 Trade margin

Source: services/gameserver/src/services/trading_service.py (calculate_dynamic_price, SELL_SPREAD = 1.15, BUY_SPREAD = 0.85).

A player who buys low at a surplus station and sells high at a scarcity station extracts the spread. The credits they earn are not minted — they were already attached to the destination station's buying budget. Net effect on money supply: zero per round trip (the station's budget refills slowly via tick_production-driven price recovery, not by direct credit creation).

Status: ✅ Shipped — pricing engine, spread, regen tick all operational.

1.2 Combat loot

Source: services/gameserver/src/services/combat_service.py (loot drop on kill).

When an NPC ship or hostile player ship is destroyed, a fraction of its current_value plus any cargo credits is awarded to the winner. NPC kills mint new credits into the economy (true faucet). PvP kills are zero-sum — they only redistribute.

Target: NPC kill loot ≈ 5–15% of NPC ship current_value, capped per encounter to discourage farm loops.

Status: 🚧 Partial — combat resolution exists; loot drop tables and per-region scaling are 📐 Design-only.

1.3 Mission rewards

Source: services/gameserver/src/services/faction_service.py, plus mission-board components in services/admin-ui/src/components/admin/.

Faction missions and bounties pay flat credit rewards on completion. These are minted by the issuing faction (true faucet). The bounty system in services/gameserver/src/services/bounty_service.py is also a faucet when posted by NPCs and zero-sum when posted by players.

Target: starter missions 500–2,000 cr; mid-game 5,000–25,000 cr; flag-tier 100,000+ cr.

Status: 📐 Design-only — mission engine schema exists; reward generation, scaling and balance tables are not yet shipped.

1.4 Colonist sales

Source: services/gameserver/src/services/planetary_service.py, planets/colonization.md.

Owned planets produce colonists, which the player sells back to Class-0 stations at 30–80 cr/unit (COMMODITY_PRICE_RANGES["colonists"] in trading_service.py). This is redistributive like ordinary trade — but unlike commodity arbitrage, colonist supply originates from a player asset (the planet) rather than a station. The station's colonist budget is a true faucet, since stations buy more colonists than they will ever resell.

Target: a fully-developed planet should yield 1,000–5,000 cr/day in colonist exports.

Status: 🚧 Partial — planets and colonist counters exist; periodic production and selling flow are 📐 Design-only.

1.5 Faction stipends

Source: services/gameserver/src/services/faction_service.py, Reputation model.

Players in good standing with a faction receive periodic credit stipends (small but reliable income for high-rep characters). True faucet.

Target: 100–1,000 cr/day depending on reputation tier and rank.

Status: 📐 Design-only.

1.6 Subscription perks

Source: services/gameserver/src/services/paypal_service.py (SubscriptionTier), models/user.py:subscription_tier.

Galactic Citizens ($5/mo) receive a small monthly credit stipend or accelerated turn regen; Region Owners ($25/mo) receive treasury seeding for their region. See OPERATIONS/monetization.md.

Target: Galactic Citizen ≈ 5,000 cr/month direct credit grant; Region Owner ≈ 100,000 cr seeded into region treasury monthly (used for NPC bounties, infrastructure subsidies — not paid directly to the owner).

Status: 📐 Design-only — subscription tiers exist; perk grants are unimplemented.

1.7 Starting grants

Source: models/player.py (credits = Column(... default=10000)), models/region.py (starting_credits = Column(..., default=1000)).

New characters spawn with 10,000 credits; per-region starting credits override this default. Pure faucet (one-time per character).

Status: ✅ Shipped — default in player model.

2. Sinks of credits

2.1 Port purchases

Source: services/gameserver/src/services/trading_service.py, trading.md.

Buying commodities at a station hands credits to that station's budget. The station's budget is not infinite — it refills slowly via the dynamic-pricing equilibrium. Net effect on money supply: depends on whether the station's budget overflows back into the void or stays bound. Today: bound (station credits are not tracked as explicit liability, so player credits leaving inventory effectively destroy money supply — this is a soft sink).

Status: ✅ Shipped (purchase flow), 📐 Design-only (explicit station treasury accounting).

2.2 Ship costs

Source: services/gameserver/src/services/ship_service.py:create_ship, models/ship.py:ShipSpecification.base_cost.

New ship purchases. Hard sink — credits leave the player's wallet and are not credited to any other player. Costs scale by ship type: Scout ≈ 25K, Cargo Hauler ≈ 80K, Defender ≈ 150K, Carrier ≈ 500K, Warp Jumper ≈ 1M.

Status: ✅ Shipped — base costs in ShipSpecification.

2.3 Ship upgrades

Source: services/gameserver/src/services/ship_upgrade_service.py (UPGRADE_DEFINITIONS).

Each upgrade level applies a geometric cost multiplier (typical: 2.0x per level). See gameplay/ship-systems.md. Hard sink.

Upgrade Base cost Multiplier
Engine 5,000 2.0
Cargo Hold 3,000 1.8
Shield 8,000 2.2
Hull 7,000 2.0
Sensor 6,000 2.5
Drone Bay 10,000 2.0
Genesis Containment 15,000 3.0

Status: ✅ Shipped — costs and multipliers live in UPGRADE_DEFINITIONS.

2.4 Equipment slots

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

Modular equipment (Quantum Harvester 25K, Mining Laser 35K, Planetary Lander 20K). Hard sink. See gameplay/ship-systems.md.

Status: ✅ Shipped.

2.5 Citadel & planet upgrades

Source: services/gameserver/src/services/citadel_service.py, services/gameserver/src/services/planetary_service.py.

Building or upgrading a citadel on an owned planet, or constructing planetary infrastructure (production, defense, terraforming), drains hard credits from the player.

Target: tier-1 citadel ≈ 250K, tier-5 citadel ≈ 5M, terraforming ≈ 1M per biome shift.

Status: 🚧 Partial — citadel model exists; cost tables and upgrade tree are 📐 Design-only.

2.6 Taxes

Source: models/region.py:tax_rate (DECIMAL(5,4), constraint 0.05–0.25), services/gameserver/src/services/regional_governance_service.py, services/gameserver/src/services/migration_service.py (region defaults).

Every market transaction in a region is taxed. The tax goes to the region's treasury (which funds NPC bounties, infrastructure, and — once the design is finalised — the region owner's payout share).

Tax rates per region type:

Region type Tax rate Source
Central Nexus 0.00% migration_service.py:126 ("No taxes in Central Nexus")
Terran Space (Sector 1 / starter) 2.0% galaxy_service.py:681,1091
Player-owned (default) 5.0% floor – 25.0% ceiling, default 10.0% models/region.py:100,134, valid_tax_rate constraint
Region Owner can adjust within 5–25% regional_governance_service.py:117

Status: ✅ Shipped — tax_rate column with constraint exists. 🚧 Partial — collection on every transaction and treasury credit are not uniformly applied yet.

2.7 Repairs

Source: services/gameserver/src/services/ship_service.py:repair_ship.

Repair cost scales with damage % and ship current_value. Hard sink at the station's repair bay.

Target: 0.5% of current_value per 1% hull repaired; full repair of a 200K ship from 50% hull ≈ 50,000 cr.

Status: 🚧 Partial — repair_ship exists; cost model is rough.

2.8 Insurance premiums

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

Players pay periodic premiums to keep insurance active. On ship loss, the policy pays out a fraction of purchase_value. Premiums are a hard sink; payouts are a faucet, but the spread (premium total > expected payout) guarantees insurance is net deflationary at the population level.

Target premiums: BASIC 1%/wk of ship value, STANDARD 2%, PREMIUM 4%. Payouts: 25% / 50% / 80%.

Status: 📐 Design-only — insurance field exists, payout calc stubbed; premium billing loop not yet implemented.

2.9 Warp gate construction

Source: services/gameserver/src/services/galaxy_service.py, models/warp_tunnel.py.

Player-built warp tunnels between sectors are extremely expensive (millions of credits) and consume materials. End-game sink.

Target: 5M cr + 10K equipment + 5K exotic_technology per tunnel.

Status: 📐 Design-only — model exists; construction flow not implemented.

2.10 Genesis device costs

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

Genesis devices terraform planets or create them from raw sectors. Each device costs in the millions and is the canonical end-game sink.

Target: 2M–10M cr per device depending on type.

Status: 🚧 Partial — model and service skeleton exist; cost tables and triggering mechanics are 📐 Design-only.

2.11 Subscription fees (out-of-game, real currency)

Source: services/gameserver/src/services/paypal_service.py. See OPERATIONS/monetization.md.

Real-money subscriptions ($5 / $25 / $50 per month) are not in-game credit sinks but they fund the operator. Mentioned here because they intersect with in-game perks.

3. Faucet-vs-sink target ratio

The economy targets a mild net sink at steady state — sinks should slightly exceed faucets so that effort retains value and credits do not inflate to meaninglessness. Concretely:

  • Daily aggregate faucet (mission rewards + combat loot + colonist sales + stipends) per active player: target 15,000–30,000 cr/day by mid-game.
  • Daily aggregate sink (upgrades + repairs + insurance + taxes + ship purchases amortised) per active player: target 20,000–35,000 cr/day by mid-game.
  • Net per-player drain: 5,000 cr/day mid-game, scaling up at end-game where citadels and genesis devices dominate.

For new players (first 10 hours), the ratio reverses — faucets dominate so the player accumulates the buffer needed to upgrade their first ship. This is the wealth ramp.

4. Inflation indicators

Source: services/gameserver/src/services/economy_analytics_service.py (get_economic_metrics, _calculate_inflation_rates, _calculate_money_supply, _calculate_health_score), models/market_transaction.py:EconomicMetrics.

The admin dashboard surfaces:

  • Total credits in circulation (EconomicMetrics.total_credits_in_circulation) — daily snapshot. Rising trend = inflationary.
  • Credit velocity (EconomicMetrics.credit_velocity) — transactions per credit per day. Falling = stagnation; spiking = bubble.
  • Average commodity prices vs spec mid-points — drift toward the price ceiling indicates demand pressure / scarcity. Drift toward the floor indicates oversupply.
  • Wealth distribution / Gini coefficient (_calculate_wealth_distribution) — high concentration suggests faucets are reaching whales but not new players.
  • Market liquidity — ratio of credits to outstanding inventory.
  • Health score — composite 0–100, rendered on the admin Economy Dashboard.

Status: ✅ Shipped — analytics service computes all of the above. 🚧 Partial — total_credits_in_circulation only updates if EconomicMetrics rows are written by a periodic job; that scheduler is 📐 Design-only.

UI: services/admin-ui/src/components/pages/EconomyDashboard.tsx.

5. Balancing levers (admin controls)

When the analytics dashboard signals drift, an operator can pull these levers without a code deploy. All exposed in the admin Economy Dashboard.

Lever Effect Source of truth
Adjust regional tax_rate (5–25%) Throttles a primary sink models/region.py, regional_governance_service.py:117
Adjust Region.starting_credits Slows or accelerates the wealth ramp for new arrivals models/region.py:103
Adjust Player.turns regen More turns → more activity → faster faucet and sink throughput services/ranking_service.py (turn bonuses)
Adjust commodity production_rate (per station) Loosens or tightens supply, shifts margins Station.commodities JSONB, trading_service.py:tick_production
Adjust commodity base_price (per station) Direct price floor lift/drop Station.commodities.base_price
Adjust mission/bounty payouts Direct faucet throttle faction_service.py, bounty_service.py
Adjust upgrade base_cost / cost_multiplier Direct sink throttle ship_upgrade_service.UPGRADE_DEFINITIONS
Adjust insurance premium / payout ratios Tunes deflationary pressure ship.InsuranceType, ship_service._calculate_insurance_payout
Mint or burn credits via admin grant Emergency intervention; logged in audit trail services/audit_service.py, admin player editor
Pause production tick Hard freeze — used during economic exploits investigation scheduler (📐 Design-only)

Status: ✅ Shipped — tax_rate, starting_credits, ship base costs, upgrade definitions are all editable. 🚧 Partial — many levers require direct DB edits today rather than admin-UI controls. 📐 Design-only — unified "Economy Levers" panel.

6. Cross-region economics

Source: services/gameserver/src/services/regional_governance_service.py, models/region.py, OPERATIONS/multi-regional.md.

Each region runs its own economy: - Independent tax_rate. - Independent commodity stock and price equilibria (stations are scoped to a region via Station.region_id). - Independent treasury (the destination of taxes).

Galactic Citizens (paid tier) can move credits and goods across regions through the Central Nexus. This arbitrage between regions is intentional — it's the macro-trade game-loop that emerges once a player saturates one region's local margins.

Region owners control their region's tax_rate, can issue regional NPC bounties from the treasury, and can subsidise infrastructure (citadels, warp gates) for resident players.

Status: 🚧 Partial — region-scoped tax rate works; cross-region arbitrage and treasury-funded subsidies are 📐 Design-only.

7. Cross-references