TradeDock & Shipyard¶

📐 Design-only. TradeDocks are rare premium hubs that combine an upgraded trading floor with a 12-slip player shipyard. No tradedocks table, slip-rental service, or construction-event RNG path exists yet. The status marker is omitted on individual subsections to reduce noise — assume 📐 throughout unless a subsection says otherwise. Adjacent ship-construction infrastructure (the Warp Jumper crafting reference in gameplay/ships.md) is partially scaffolded but is not the slip-rental flow described here.

Overview¶

A TradeDock is a multi-purpose station combining an advanced trading floor with full shipyard facilities. It is distinct from the standard Class-0 through Class-11 stations described in trading.md; a TradeDock does not sit in the class enumeration at all and operates under its own pricing and service rules.

Three things define a TradeDock:

Premium trading hub — better spreads, bulk discounts, zero transaction fee, 10× the inventory of a normal port.
Player shipyard — 12 rented construction slips that build ships over 3–14 real-time days.
Economic anchor — a regional centre of gravity around which trade routes, resource gathering, and team coordination form.

Scarcity¶

TradeDocks are rare strategic infrastructure — only 4–8 across the entire galaxy at any time. They are seeded at galaxy generation and never spawn dynamically.

Region	TradeDocks
Central Nexus	3
Terran Space	1
Player-owned region (≥ 500 sectors)	0 or 1
Player-owned region (< 500 sectors)	0

Players in small regions must travel to a neighbouring region — typically the Central Nexus — to access TradeDock services. See galaxy/generation.md for placement rules.

Ownership¶

TradeDocks are NPC-controlled neutral infrastructure. They cannot be captured, ownership-transferred, or destroyed. A region owner can fund construction of a new TradeDock as a one-time region-scale project (see Discovery & access below).

Premium trading mechanics¶

A TradeDock's commodity floor is faster, deeper, and cheaper than a Class-0 port. The standard pricing engine described in trading.md still applies, but the spreads, fees, and inventory caps are different:

Aspect	Standard port (Class 0+)	TradeDock
Sell spread (`midpoint × …`)	1.15	1.05–1.10
Buy spread	0.85	0.90–0.95
Transaction fee	2.0%	0.0%
Inventory cap	1× capacity	10× capacity
Bulk discount	none	5% per 1,000 units, capped at 20%
Cargo insurance available	sometimes	always

Effective price compression: a TradeDock is 10–15% better on either side of the spread than a Class-0 port. Combined with the bulk discount, a 4,000-unit purchase reaches the 20% cap.

Bulk discount detail¶

Applied to buys (player purchasing from the dock):

Units in single transaction	Discount
1–999	0%
1,000–1,999	5%
2,000–2,999	10%
3,000–3,999	15%
4,000+	20% (cap)

The discount applies on top of the better TradeDock spread; reputation and personal-rep modifiers from trading.md stack on top of the discounted price.

Rare commodities¶

TradeDocks broker commodities that are not procedurally generated at standard ports. The catalogue includes:

Advanced ship components — hull plating, shield generators, engine cores.
Rare construction materials — titanium alloys, photonic crystals, quantum shards.
Specialised equipment — advanced sensors, experimental weapons, luxury fittings.

These materials feed both the shipyard's resource bundles below and the warp-tunnel and Genesis pipelines described in galaxy/genesis-devices.md. Photonic crystals and quantum shards specifically gate Warp Jumper construction; see the Bang-bottleneck note in trading.md.

Trade services¶

In addition to the commodity floor, every TradeDock offers:

Cargo insurance — protects against piracy losses on the next jump.
Market trend ARIA integration — premium price predictions.
Trade route optimisation — suggested round-trip routes.
Long-term commodity storage — rented warehouse slots, persists across sessions.
Priority docking — TradeDock berths never queue; instant docking guaranteed.

Shipyard — overview¶

Each TradeDock operates 12 construction slips. Slips rent by the day and are consumed serially — one ship per slip at a time, no parallel builds in the same slip.

The shipyard exists to make ship ownership a project, not a transaction. A built ship is meaningfully different from a purchased one:

Stat bonuses (5–15% across hull / shields / cargo / speed) applied at completion.
Custom name, paint scheme, and builder signature ("Crafted with pride by [Player]").
Unlockable modifications via construction events (see Construction events).
Higher resale value (+20%).
Lower total cost (30–50% cheaper) if the player gathers their own resources.

Versus pre-fab purchase at a standard shipyard, the trade-off is time and effort for discount and quality.

Construction phases¶

Every build progresses through four phases regardless of ship type:

Frame Assembly — 0–25%. Hull structure assembled.
Systems Integration — 25–50%. Engines, power, life support installed.
Outfitting — 50–75%. Cargo bays, defensive systems, sensors fitted.
Final Assembly — 75–100%. Testing, calibration, quality assurance.

Phase boundaries gate certain mechanics (the keel-laid milestone fires at the start of Frame Assembly; hull-complete fires at the end of Systems Integration; see Milestone payments).

Slip rental¶

Slips are reserved on a first-come, first-served basis. When all 12 slips at a TradeDock are occupied, a waiting list forms. Reservations require an initial deposit equal to 10% of the total project cost (rent + labour + resource market value).

Per-ship rental table¶

Ship type	Build days	Slip deposit	Total project cost
Light Freighter	3	50,000 cr	200,000 cr
Scout Ship	4	75,000 cr	300,000 cr
Fast Courier	5	100,000 cr	400,000 cr
Cargo Hauler	5	100,000 cr	500,000 cr
Defender	7	200,000 cr	800,000 cr
Colony Ship	10	300,000 cr	1,500,000 cr
Warp Jumper	12	500,000 cr	2,500,000 cr
Carrier	14	500,000 cr	2,000,000 cr

(The Warp Jumper remains the only craft-only ship in the galaxy — it cannot be purchased pre-fab at any port. See gameplay/ships.md.)

The total project cost above is the canonical "all-in if you buy every resource at market" figure. A player who self-gathers resources will spend substantially less in net credits — see Cost comparison.

Rental mechanics¶

Daily rent is charged at server reset (00:00 UTC) for as long as the slip is occupied.
Players may pre-pay up to 30 days of rent at booking.
Missed rent pauses construction immediately — no progress accrues until rent is paid.
Three consecutive days unpaid → the project is cancelled and all delivered resources forfeited (see Cancellation & refund).
Slip occupants can lock the slip behind a team-only flag (see Team coordination workflows) but the rent obligation transfers along with the lock.

Cost comparison¶

For a Defender (build cost reference: pre-fab ≈ 70,000 cr at a standard shipyard):

Path	Net credits	Net time	Stats
Pre-fab purchase	70,000 cr	instant	base
Player-built (self-gather all resources)	~41,000 cr	7 days + gathering	+5–15% bonus
Player-built (buy all resources at market)	~126,000 cr	7 days	+5–15% bonus
Player-built (mix: gather common, buy rare)	~66,000 cr	7 days + light gathering	+5–15% bonus

The "sweet spot" — gather the bulk commodities (ore, technology, equipment), buy the exotic materials — saves credits versus pre-fab and still earns the construction bonuses.

Resource delivery¶

Each ship type has a fixed construction bundle that must be delivered to the slip over the build's duration. Resources are deposited at the dock's resource intake; once delivered they cannot be reclaimed.

Bundle composition¶

Ship type	Ore	Technology	Equipment	Exotic Tech	Photonic Crystals	Quantum Shards
Light Freighter	1,200	600	400	—	—	—
Scout Ship	500	300	200	—	—	—
Fast Courier	800	500	350	100	—	—
Cargo Hauler	2,500	800	1,200	—	—	—
Defender	2,000	1,500	1,000	500	—	—
Colony Ship	4,000	2,000	1,500	200	—	—
Carrier	5,000	3,000	2,500	1,000	500	—
Warp Jumper	3,000	2,000	1,500	2,000	500	1,000

(Numbers for Light Freighter, Scout, Defender, Cargo Hauler, Carrier, and Warp Jumper are anchored to legacy spec; Fast Courier and Colony Ship are extrapolated to fit the same structure since legacy did not specify them.)

Delivery rules¶

Threshold for keel-laid milestone: 25% of every resource type must be delivered before construction can advance past Frame Assembly.
Threshold for hull-complete milestone: 100% of ore, technology, and equipment plus 50% of any exotic materials.
Threshold for final commissioning: 100% of every resource.
Late delivery penalty: if the project misses a phase threshold by its scheduled day, a 5% daily cost overrun is added to the labour fee for as long as the shortfall persists, and the slip's build clock pauses (extending elapsed real-time days but not the labour-fee accrual).
Resources delivered by team-mates count toward the project's bundle (see Team coordination workflows); the delivering player gets contribution credit on the project ledger.

Sourcing options¶

Self-gather — trade routes, mining, planetary production. Cheapest but slowest.
Market purchase — buy directly at the TradeDock's premium floor or at a standard port. Fastest but most expensive.
Team contribution — team-mates fly resources in from elsewhere.
Mixed — gather the bulk, buy the rare materials.

Milestone payments¶

The total project cost is split across a four-stage payment schedule, separate from daily rent and resource delivery. Milestones unlock in real time as construction phases advance.

Milestone	Trigger	% of total project cost
Deposit	On slip booking	10% (Light Freighter, Scout, Fast Courier) — 25% (Carrier, Warp Jumper)
Keel laid	Resource threshold met, Frame Assembly begins	25%
Hull complete	End of Systems Integration	25%
Final / commissioning	On ship delivery, claim issued	25–40%

The deposit-to-final ratio scales with ship type — small ships front-load less and back-load more (10% deposit, 40% final), heavy ships front-load more (25% deposit, 25% final). This guarantees the dock recoups capital expenditure on big builds early while keeping entry-tier construction accessible.

Payment failures¶

Missing a milestone payment pauses construction in the same way as missed rent.
Three consecutive days of missed milestone payment cancel the project (see Cancellation & refund).
Players can pre-pay any milestone in advance to immunise against cash-flow gaps.

Construction events¶

During a build, random events can occur with a base 5% chance per real-time day. Events surface as a UI prompt on the player's TradeDock dashboard the next time they dock or open the project view. Some events demand a decision (mitigate vs. accept); others are passive applications.

Event	Effect	Player decision
Quality Discovery (positive)	Engineer finds a structural improvement. Ship gains +5% to a random stat (hull, shields, cargo, speed).	Accept — no decision required.
Resource Shortage	Local supply chain disrupted. +10–25% cost overrun on the next milestone, OR ship 10% extra of one resource type to mitigate.	Pay overrun or deliver extra resource.
Labor Dispute	Slip workers strike. Build delayed 1–3 days unless the player pays a 5% bonus to dock workers.	Pay bonus or absorb delay.
Innovation (positive)	Engineer applies a novel technique. Ship gains +1 random equipment slot at completion.	Accept — no decision required.
Inspection Delay	Federation/Faction inspector slows progress. +1 day elapsed, no cost.	None — passively applied.

Event probability tuning¶

Base rate: 5% per day.
Space Engineer assignment (see Space Engineer integration): +10% per engineer assigned, capped at +30% with three engineers. Engineers also bias the roll toward positive events (Quality Discovery, Innovation) by approximately 2:1.
Events log to the project ledger and persist on the completed ship's "build history" record.

Multiple events¶

A single project can fire multiple events across its build window. Carrier and Warp Jumper builds (12–14 days) commonly accumulate 2–4 events; Scout and Light Freighter builds rarely fire more than one.

Space Engineer profession integration¶

The Space Engineer profession on a player-owned planet (see planets/professions.md) materially accelerates and improves TradeDock construction. A player with trained Space Engineers on any planet they control can assign engineers to an active TradeDock project.

Effects¶

Engineer training tier	Construction time reduction	Quality bonus	Labour fee reduction
Tier 1	−10%	+2% extra stat bonuses	−5%
Tier 2	−20%	+3%	−10%
Tier 3	−30%	+5%	−15%

Stacking rules¶

Up to three engineers can be assigned to a single project (one per slip).
Effects stack additively within the build, but the construction time reduction caps at −50% to prevent trivialised carrier and warp-jumper builds.
Each assigned engineer is paid daily from the project owner's credits at the engineer's home-planet wage rate (TBD, set by planets/professions.md).
Engineers also boost the construction-event RNG roll toward positive outcomes (see Construction events).

This is the primary reason the Space Engineer profession exists: it converts long-running planet investment into a recurring shipyard advantage for the player and their team.

Team coordination workflows¶

Multiple players can collaborate on a single slip booking. The legacy single-owner model is preserved as a default — one player books, pays, and claims — but team workflows extend it.

Shared slip booking¶

Initiator — the team-mate who reserves the slip. Credits with the deposit; their Player.id is the project owner of record.
Co-contributors — team-mates who deliver resources or pay milestone fees. Logged on the project ledger.
Claimant — the player listed at completion as recipient of the ship. Default = initiator; reassignable to any co-contributor before final payment.

Pooled resource delivery¶

Any team-mate docked at the TradeDock can deliver to a teammate's project's resource intake, provided the slip is flagged team-shared.
Contributions are credited on the ledger — useful for distributing a future ship's effective cost.
Team-treasury credits can pay milestone fees and slip rent without a specific player needing to be online.

Co-ownership¶

A completed ship may optionally be team-owned rather than individually owned. A team-owned ship is bound to the team's roster and any active member can pilot it (one pilot at a time).
Co-ownership is decided at claim time and irreversible without selling and re-buying the ship.
Per-team-ship limits and team-roster transfer rules track factions-and-teams.md (📐 Design-only there as well).

Specialisation roles¶

A natural team workflow emerges:

Gatherers mine, trade, and produce raw resources to deliver to the project.
Builders queue and manage active slips, schedule milestone payments, decide on construction events.
Engineers train and assign Space Engineers from their colonised planets.
Treasurers fund milestone gaps from the team treasury.

Three team-mates building three ships in parallel at one TradeDock is the design's reference workflow.

Cancellation & refund¶

Players can cancel a project at any point before claim. Refund schedule:

Cancellation timing	Deposit refund	Milestones already paid	Resources delivered
Pre-keel (Frame Assembly not started)	90% (10% restocking fee)	refunded fully	refunded fully
Post-keel, pre-hull (Frame Assembly started, Outfitting not begun)	forfeit	50% of milestones already paid	not refundable
Post-hull, pre-claim (Outfitting or Final Assembly)	forfeit	10% of milestones already paid	not refundable

Sell to dock at completion¶

If a player completes a build but no longer wants the ship, the dock will buy the completed hull at construction cost minus 30%. This is the best-available exit after Final Assembly and is the only way to recover any value once the ship is hull-complete.

Forfeiture cancellation¶

If the project is cancelled by the system (three days of missed rent or milestones), all credits and resources are forfeit — there is no refund path. The player may not re-book a slip at the same TradeDock for 7 real-time days after a forfeiture.

Defenses¶

TradeDocks are heavily defended Class-9-equivalent military installations:

NPC defence fleet — 8–16 turrets and 24–48 garrison drones permanently stationed.
No PvP combat — players cannot initiate combat in a TradeDock's sector against the dock or other docked players.
No PvE damage — no NPC faction event can destroy or capture a TradeDock outside an end-game faction-war scenario flagged by an operator (📐 Design-only).
Player ships at the dock are safe — the dock guarantees a no-combat zone within 1 sector.

A TradeDock cannot be cargo-raided or saboteur-targeted in current design. The shipyard infrastructure is too strategic to be lost to an opportunistic player attack.

Discovery & access¶

Galaxy-generation seeding¶

TradeDock placement is decided at galaxy generation (see galaxy/generation.md):

3 in the Central Nexus — typically in EXPANSE zones near population centres.
1 in Terran Space — in the Federation zone, sector range 1–99.
0 or 1 per player-owned region (eligible only at ≥ 500 sectors).

Player-region TradeDocks must be funded by the region owner; they are not auto-seeded.

Reputation gate¶

To dock at a TradeDock without paying the guest fee, a player needs:

+200 or higher reputation with the controlling NPC faction (the faction owning the sector) — see factions-and-teams.md.
A clean criminal record with that faction (no outstanding bounties from the faction's own NPCs).

Guest fee¶

Players below the reputation threshold can still dock by paying a flat guest fee of 100,000 cr per visit. The fee is non-refundable, persists for one in-game session (i.e. until the next undock), and is applied each time the player re-docks.

Region-funded construction¶

A region owner with ≥ 500 sectors may construct one new TradeDock in their region:

Cost: 50,000,000 cr.
Duration: 90 real-time days.
Resource bundle: 500,000 ore + 300,000 technology + 200,000 equipment.
Operating cut: the region owner receives 5% of all shipyard fees generated at the new dock as ongoing income (paid into the region treasury).

Region-funded TradeDocks operate identically to galaxy-seeded ones; players see no functional difference.

Player-facing affordances¶

TradeDock landing page — three tabs: Trading Hub, Shipyard, Storage.
Shipyard slip browser — visual grid of all 12 slips, occupancy progress bars, waiting-list position.
Project dashboard — for the player's own active projects: progress phase, resource intake checklist, milestone payment schedule, construction-event log, Space Engineer assignment panel, customisation preview.
Customisation panel — paint scheme picker, ship-name field, modification toggles (unlocked through Innovation events).
Stats projection — live preview of the ship's stats including any pending bonuses from quality events.
Cancel / sell-to-dock controls — gated behind a confirmation modal that displays the exact refund amount.
Team-shared slip flag — toggle visible only to the slip's initiator.

ARIA surfaces project status as conversational status updates ("Your Defender is 65% complete and currently in Outfitting; one resource shortage event is pending your decision").

Source map¶

All paths are targets — no current code implements TradeDock or shipyard behaviour at the level described.

Concern	Target path
TradeDock model	`services/gameserver/src/models/tradedock.py` (target)
Construction slip model	`services/gameserver/src/models/construction_slip.py` (target)
Ship construction project model	`services/gameserver/src/models/ship_construction_project.py` (target)
Slip rental & lifecycle service	`services/gameserver/src/services/shipyard_service.py` (target)
Construction event RNG service	`services/gameserver/src/services/construction_event_service.py` (target)
Bundle composition catalogue	`services/gameserver/src/core/ship_construction_bundles.py` (target)
Premium-pricing override (10–15% spread, bulk discount)	`services/gameserver/src/services/trading_service.py` (target update — branch on `Station.is_tradedock`)
Galaxy-gen TradeDock seeding	`services/gameserver/src/services/galaxy_service.py:_seed_tradedocks` (target)
Region-funded construction	`services/gameserver/src/services/regional_governance_service.py` (target update)
Space Engineer integration	`services/gameserver/src/services/profession_service.py` (target) and `shipyard_service.py` cross-call
API — list TradeDocks	`GET services/gameserver/src/api/routes/tradedock.py:/api/tradedock/list` (target)
API — slip availability	`GET .../tradedock/{tradedock_id}/slips` (target)
API — reserve slip	`POST .../tradedock/{tradedock_id}/slips/reserve` (target)
API — deliver resources	`POST .../tradedock/slips/{slip_id}/deliver` (target)
API — milestone payment	`POST .../tradedock/slips/{slip_id}/payment` (target)
API — customise + claim	`POST .../tradedock/slips/{slip_id}/customize`, `.../claim` (target)
API — cancel	`POST .../tradedock/slips/{slip_id}/cancel` (target)
Migration adding TradeDock + slip + project tables	`services/gameserver/alembic/versions/xxxx_add_tradedock_shipyard.py` (target)
Player UI — TradeDock landing	`services/player-client/src/components/TradeDock/TradeDockHome.tsx` (target)
Player UI — shipyard slip browser	`services/player-client/src/components/TradeDock/SlipBrowser.tsx` (target)
Player UI — project dashboard	`services/player-client/src/components/TradeDock/ProjectDashboard.tsx` (target)
Admin UI — TradeDock management	`services/admin-ui/src/components/pages/TradeDockAdmin.tsx` (target)

Status summary¶

Every aspect of this system is 📐 Design-only.

No tradedocks, construction_slips, or ship_construction_projects table.
No is_tradedock flag on Station or any equivalent classification.
No premium-pricing override in trading_service.py.
No slip rental, milestone payment, or construction-event RNG path.
No Space Engineer assignment integration to a shipyard project.
No player-client or admin-UI panel for TradeDock interactions.
The Warp Jumper craft-only requirement is referenced in gameplay/ships.md but no shipyard construction flow exists yet — Warp Jumper construction today reduces to a single 500,000 cr base-cost transaction with rare-material gating, not the slip-rental flow above.

Implementation order, when scheduled, follows the legacy phase plan:

Phase 1 — TradeDock seeding at galaxy generation, premium trading floor (spreads + bulk discount + 10× inventory + zero fee), Warp Jumper construction migrated onto the slip-rental flow.
Phase 2 — Full slip rental for all 8 ship types, resource bundles, milestone payments, cancellation & refund.
Phase 3 — Construction events RNG, Space Engineer integration, team coordination workflows, region-funded construction.

If this system is indefinitely deferred, file an ADR in ADR/ capturing the deferral rationale and the conditions under which it would be picked up.

trading.md — main trading flow, station classes, and pricing engine; the TradeDock summary block there is a brief pointer to this spec.
lifecycle.md — credit faucets and sinks; TradeDock construction is a major mid-to-late-game sink.
planets/professions.md — Space Engineer profession that accelerates and improves TradeDock construction.
gameplay/ships.md — ship types, pre-fab acquisition paths, the craft-only Warp Jumper.
gameplay/ship-systems.md — upgrade and equipment slots that built ships can extend with.
galaxy/generation.md — TradeDock placement at galaxy generation and per-region scarcity rules.
gameplay/factions-and-teams.md — reputation gates for TradeDock access and team-coordinated workflows.