Salt & Steel: Instance Management

Document type: Technical Architecture — Canonical
Status: Canonical
Last updated: 2026-04
See also: Server Architecture | Networking Model | Performance and Optimization

Overview

Salt & Steel's instance management system is the most architecturally novel component in the infrastructure stack. Where Path of Exile manages one type of game instance (the area instance, private and ephemeral) with a town variant (shared and semi-persistent), Salt & Steel requires four distinct instance types — land instances, sea instances, port/town instances, and boss arenas — each with different lifecycle rules, capacity models, persistence semantics, and transition behaviors. The system must also handle seamless transitions between these types without loading screens where at all possible.

The principle governing all instance design: the player should never perceive the seam between instances. A pirate captain does not experience "loading screen → ship deck → loading screen → island jungle." They sail to the island, drop anchor, lower a landing boat, and wade ashore. The instance boundary is an implementation detail that the player never sees.

Instance Type Reference

Type	Scope	Persistence	Max Players	Tick Rate	Typical Size
Land Instance	Party-private	10 min idle timeout	6	30-40 Hz	200m × 200m – 2km × 2km
Sea Instance	Region-shared	5 min idle timeout	32 (multiple parties)	20 Hz ship / 30 Hz deck	4km × 4km
Port/Town Instance	Region-shared, persistent	Never (per-Voyage)	100+	10 Hz (social)	Fixed layout
Boss Arena Instance	Party-private	Destroyed on completion	6	40 Hz	Fixed layout per boss

Land Instances

What Land Instances Host

Procedurally generated islands (coastal, tropical, temperate, volcanic)
Procedurally generated dungeons: sea caves, pirate fortresses, ancient ruins, shipwreck interiors, underwater grottos
Hand-crafted landmark rooms embedded within procedurally generated layouts (treasure vaults, boss chambers, puzzle rooms)
Environmental content: buried treasure sites, salvageable wrecks, survivor camps

Procedural Island and Dungeon Generation

Land instance generation is seed-based. The instance seed is generated by the server at instance creation time and stored in the instance registry. The same seed always produces the same layout — this is essential for consistency (all party members entering the same instance must load the same geometry) and for reproducibility in crash recovery (the server can describe an instance by its seed rather than by its full state).

Generation pipeline:

Biome assignment: The chart region's biome parameters (tropical, temperate, volcanic, arctic, corrupted) are passed to the generator as constraints
Macro layout: High-level room graph is generated — entry point, paths, landmark rooms, exit points. Room graph uses a weighted randomized graph construction with connectivity guarantees (no dead-end-only paths to critical content)
Room geometry: Each room node in the graph is instantiated from a modular tileset bank. Tileset selection is biome-appropriate. Room dimensions and internal features (columns, water features, obstacles) are varied per-room using the seed
Landmark injection: Specific landmark rooms (boss chamber, treasure vault, puzzle room) are placed at designated graph positions. Landmark rooms are hand-authored — they use seed only for monster/loot population, not geometry
Navigation mesh generation: A navigation mesh is computed for all walkable surfaces. This is not pre-baked; it is computed at instance creation. Generation target: under 3 seconds for a large island instance.
Entity population: Monster types and densities are selected from the region's spawn table, modified by Nautical Chart region modifiers. Monster positions are distributed using Poisson disk sampling to prevent clustering. Mini-bosses placed at designated encounter nodes.
Loot table initialization: Treasure chest contents, breakable container contents, and enemy drop tables are initialized using the seed. Actual items are not generated until interaction — item generation is deferred to the moment of chest opening / enemy death.

Performance target for generation: 95th percentile instance creation under 4 seconds, measured from request receipt to "player can enter" state.

Instance Lifecycle — Land

[CREATION REQUEST]
        │
        ▼
[Select simulation server] ← scheduler: CPU/memory headroom
        │
        ▼
[Allocate pooled process or spawn new process]
        │ (~200ms from pool, ~2-3s cold start)
        ▼
[Generate area from seed]
        │ (~1-3s)
        ▼
[Register instance in Instance Directory]
        │
        ▼
[Redirect requesting client to instance endpoint]
        │
        ▼
[ACTIVE: Players connected, simulation running]
        │
        ├─── [All players disconnect]
        │         │
        │         ▼
        │    [IDLE: 10-minute countdown]
        │         │
        │         ├─── [Player reconnects] → [ACTIVE again]
        │         │
        │         └─── [Timer expires] → [GARBAGE COLLECT]
        │
        └─── [Boss killed + all content complete] → [MARK COMPLETABLE]
                  │
                  ▼
             [Players exit normally] → [GARBAGE COLLECT immediately]

Idle timeout semantics: The 10-minute idle window serves player experience: a player who disconnects mid-dungeon can reconnect within the window and resume from exactly their position. Items already picked up are preserved (checkpointed to Account Authority at pickup). Progress (monster kills, boss damage) is preserved in instance memory. If the window expires, the instance is collected and reconnecting players are placed at the entry point of a fresh instance (their position is lost, loot already picked up is retained).

Land Instance Crash Recovery

On land instance crash:

Players are disconnected and returned to their ship (if they have a ship in the adjacent sea instance) or to the nearest port (if no ship present)
Character state (HP, FP, equipment, inventory) rolls back to the entry checkpoint (taken at instance entry + every 60-second periodic checkpoint)
Items picked up since last checkpoint are retained (item pickups are written to Account Authority immediately at pickup, before the checkpoint interval)
Boss progress is lost. Boss encounters are designed to be completable from start without loss of character power (no resources are consumed on entry that are not restored on death/reset)

Sea Instances

Sea instances are Salt & Steel's most architecturally novel instance type. They are the game's closest analog to an open-world shared space — multiple independent player groups occupy the same instance, can interact, and operate at a scale dramatically larger than land instances.

Sea Instance Spatial Model

A sea instance covers a 4km × 4km ocean area corresponding to a single Nautical Chart region. The instance is divided into a 40×40 grid of 100m × 100m cells for entity locality tracking and area-of-interest filtering.

Entities within a sea instance:

Player ships and their simulated crew
NPC ships (merchant convoys, naval patrols, pirate raiders, quest vessels)
Sea creatures (whales, giant squid, sea serpents, hostile creatures, passive ecology)
Environmental hazards (reefs, whirlpools, volcanic vents — fixed positions, generated at instance creation)
Weather state (inherited from Weather Service, applies globally to the instance)
Boarding contexts (sub-simulations within the instance, see below)
Floating debris and salvage zones from destroyed ships
Underwater entrances (points where player can dive to a linked sub-instance)

Unlike land instances (party-private, ephemeral), sea instances are region-shared: any player or party entering a given Nautical Chart region joins the same sea instance for that region (up to capacity). This is an intentional design decision:

Encounter possibility: Players can encounter each other on the open sea — for PvP zones, cooperative world events, or simply the atmospheric effect of seeing another ship on the horizon
World event hosting: Sea monster migrations, fleet engagements, and faction battles play out in shared space, visible to all players in the instance
Economy interaction: A sunken NPC ship's debris field is visible and accessible to multiple players — creating emergent first-come/competition dynamics for salvage

Capacity management: When a sea instance reaches 32 players (or 16 ships, whichever is hit first), new players are routed to an overflow sea instance for the same region. Both instances run independently; players in different instances cannot see or interact with each other. The instance directory tracks all active instances per chart region and assigns new arrivals to the least-full instance below capacity.

Weather consistency across overflow instances: All overflow instances for the same chart region receive identical weather state from the Weather Service. Players phased into different overflow instances of the same region experience the same storm.

Sea Instance Lifecycle

Sea instances are more persistent than land instances: they remain active as long as at least one player (or one active NPC ship encounter with recent player proximity) is present. The 5-minute idle timeout is conservative — seas are never truly empty while a Nautical Chart region is active.

At Voyage end, the Weather Service resets regional weather parameters, Nautical Chart modifications are preserved per-player on the Account Authority, and active sea instances are gracefully terminated. Players in sea instances at Voyage-end cutoff are given a 15-minute warning and then safely logged out to port.

Boarding Contexts — Sea Instance Sub-Simulations

A boarding context is a personal-combat simulation spawned within a sea instance process, running at 30 Hz GURPS tick rate, using the attacking ship's deck geometry as its spatial domain.

Boarding context properties:

Spatially bounded by the defender ship's deck geometry (loaded at boarding initiation from the ship model's combat collision mesh)
Populated by: the attacking player(s), their active crew companions, the defending ship's crew (as AI-controlled NPC combatants)
Time-coupled to the parent sea instance: time passes at the same rate, the parent simulation continues advancing (ships drift, remaining gunners fire broadsides, weather continues)
Maximum duration: 10 minutes. If boarding is unresolved after 10 minutes, it is declared a failed assault. Attackers are forcibly transported back to their ship.

Multiple boarding contexts can exist simultaneously within one sea instance (different ships boarding each other). Each context runs as a coroutine within the sea instance process — the sea instance scheduler manages time allocation between the 20 Hz ship simulation and all active boarding sub-contexts.

Compute allocation: A sea instance with two simultaneous boarding contexts runs:

Ship simulation (20 Hz): 40% of server frame time allocation
Boarding context A (30 Hz): 25% allocation
Boarding context B (30 Hz): 25% allocation
NPC AI / creature behavior: 10% allocation

If compute budget is exceeded (rarely, but possible during extreme encounters), the ship simulation tick rate drops to 15 Hz before the boarding tick rate is reduced — personal combat timing is more sensitive to tick rate changes than ship positioning.

Port and Town Instances

Design Role

Ports are Salt & Steel's persistent social hubs — the equivalent of PoE's town instances. They are always-available, shared, architecturally fixed spaces where players:

Recruit crew at the harbormaster's office, tavern, and guild halls
Trade with other players at the port marketplace
Access faction representatives for reputation rewards and exclusive missions
Repair ships and restock supplies
Access the Skill Atlas through faction trainers
Socialize, form parties, display ships in the harbor

Technical Characteristics

Port instances are architecturally distinct from all other instance types:

Semi-persistent: Ports remain active for the duration of a Voyage season. Individual server processes may restart (maintenance, crash recovery), but the port instance is immediately recreated on server restart. There is no idle timeout.
Shared, high-capacity: Up to 100-150 players per port instance. Player characters are visible to each other in the port environment.
Non-combat simulation: Port instances do not run a combat simulation. GURPS resolution does not occur in ports (outside the port arena sub-instance). Port instances run at 10 Hz, sufficient for social presence (seeing other players, NPC animation) without the overhead of combat-grade tick rates.
Fixed layout: Ports are hand-authored, not procedurally generated. Each major port is a unique, recognizable location consistent across all playthroughs.
Ship display in harbor: Player ships are rendered in the port harbor as cosmetic display objects. The ship displayed is the player's currently active ship. Hull damage state is not shown in port (ships are assumed repaired when docked). Ship positions in the harbor are randomly assigned from a pool of available berth slots; Crew guilds with a shared "guild flagship" may have a reserved berth.

Port Instance Overflow

When a port instance reaches capacity:

New arrivals are placed in an overflow port instance (identical layout, same NPCs, but separate player population)
Players can whisper each other across port instances (handled by Social Service, not by instance-to-instance communication)
Party formation can bridge port instances: inviting a player in a different port instance triggers an instance transfer for the invited player to the inviter's port instance
Trading occurs within the same port instance (direct trade) or through the Trade Service marketplace (available from all port instances)

Port Arena Sub-Instance

Each major port contains an arena — a designated PvP zone accessible from within the port. Arena matches are boss-arena-style instances (party-private, time-limited) created on demand when a duel is accepted. The arena sub-instance:

Uses the port's arena geometry (fixed, hand-authored)
Runs full 40 Hz GURPS combat simulation
Terminates on match resolution or after 10 minutes (draw)
Spectators from the port can enter a spectator sub-instance that renders the match without participation

Boss Arena Instances

Boss arena instances are the highest-fidelity, most carefully resourced instance type. They host pinnacle boss encounters: legendary pirate captains, sea monsters, mythic beings.

Characteristics

Party-private: Only the party that initiated the boss encounter occupies this instance. No other players can enter while the encounter is active.
Fixed layout: Boss arenas are hand-authored at each distinct location. The encounter geography is part of the boss fight design (a sea serpent fight uses a different arena layout than a duel with a legendary pirate captain on a burning ship).
40 Hz tick rate: The highest tick rate of any instance type. Boss encounters are the most mechanically demanding content; timing precision matters for both boss AI pattern execution and player active defense windows.
Multi-phase scripting: Boss AI is scripted with phase transitions, summon events, environmental changes (fire spreading, water rising, platform destruction). Phase transition scripts run on the simulation server as part of the instance's scripted event queue.
No idle timeout: A boss arena instance does not expire while players are present. If all players die, the instance holds for 30 seconds (allowing reconnection) before terminating and returning players to the instance entry point.
Destroyed on completion: When a pinnacle boss is killed, the instance is marked for immediate collection after all loot has been distributed and the kill flag has been written to the Account Authority.

Naval-Personal Boss Transitions

Many pinnacle bosses span both naval and personal combat phases. The Kraken fight, for example:

Phase 1: Naval combat against the Kraken's tentacles and body from the player's ship (sea-scale simulation)
Phase 2: The Kraken grapples the ship; boarding-context-style personal combat on the ship deck against Kraken's attack appendages
Phase 3: The player must dive into the water (underwater sub-instance) to attack the Kraken's core

This multi-domain boss fight occurs within a single boss arena instance. The instance runs all three scales simultaneously as needed:

The sea-scale simulation continues (the Kraken and the ship interact at ship scale)
A boarding context is spawned for Phase 2 on-deck combat
An underwater sub-context is spawned as a volume beneath the main instance when the player dives

All three contexts share the same entity registry — the Kraken is a single entity referenced in all three contexts, taking damage from any source and updating its HP in a single authoritative state.

Transition System

The seamless transition system is the most player-facing innovation in Salt & Steel's instance management. The design requirement is absolute: no visible loading screens for transitions between sea and land instances. Port entry is allowed one brief atmospheric hold (fog dissolve, 3-4 seconds) but no black screen.

Sea → Land (Anchoring / Landing)

Triggered when: player anchors their ship within range of an island or shore, then deploys the landing boat.

Technical sequence:

Player selects anchor action from ship command menu
Server validates anchor position (within 500m of island coastline, safe depth for ship class)
Ship enters "anchored" state — helm control disabled, sails furled. Ship physics become passive (no steering, position held by anchor constraint)
Server begins land instance creation for the adjacent island (if no instance exists for this island in this session) — the creation runs in background, taking 2-4 seconds
Client plays landing boat deployment animation (rowing toward shore) — this animation lasts ~5 seconds, covering the instance creation time
Instance Directory confirms land instance is ready
Server sends TRANSITION_SEA_TO_LAND packet containing: land instance server endpoint, player spawn coordinates on the beach, pre-generated terrain seed for visual matching
Client receives packet and begins pre-loading land instance assets in background (texture streaming, terrain geometry cache)
As the rowing animation completes (player character approaches shore), a light atmospheric effect (sea mist, bright beach glare) provides a 1-2 second atmospheric dissolve
Connection transitions: client connects to land instance server, receives initial state snapshot, spawns player at beach coordinates
Sea instance server receives PLAYER_LEFT_TO_LAND notification — player character is marked as "on island" (not aboard ship). Ship remains in sea instance, accessible by other party members or by the player returning.

Pre-loading window: The 5-second rowing animation is the most critical engineering element of this transition. During those 5 seconds, the client must:

Load terrain geometry for the island (from the pre-communicated seed, the generator is deterministic so the client knows what to load before the server sends the state)
Stream required texture mips into VRAM
Begin audio bank loading for the island's biome
Decompile shaders if new tileset variants are encountered (unlikely after first region entry)

If pre-loading is incomplete when the animation ends, the atmospheric hold is extended to a maximum of 8 seconds. If pre-loading is still incomplete after 8 seconds (slow HDD, cold cache scenario), a brief loading indicator appears — the only acceptable fall-back to a visible loading state.

Land → Sea (Returning to Ship)

Triggered when: player reaches the water's edge at the anchor point and selects "Return to ship."

Technical sequence:

Player activates return action at the shore anchor marker
Client plays rowing-back animation (symmetric with landing)
During animation: client pre-loads sea instance state (ship positions, weather parameters)
Server sends TRANSITION_LAND_TO_SEA packet
Atmospheric dissolve (mist), connection transitions to sea instance server
Player spawns on ship deck at the helm

Land instance: player is marked as departed. Land instance continues running for 10 minutes (allowing party members to remain or reconnect).

Ship → Ship (Boarding)

Boarding is not an instance transition — it is a boarding context creation within the same sea instance. No client-server endpoint change occurs. See Networking Model for boarding context lifecycle.

The camera transition (naval view → deck view) is purely client-side, driven by the boarding animation. The server simply begins sending the boarding context state updates alongside the ongoing sea instance updates.

Surface → Underwater (Diving)

Triggered when: player reaches a designated underwater entrance (a cave mouth beneath the surface, a shipwreck hatch, a submerged temple entrance) and activates the dive action.

Two variants:

Shallow dive (no instance change): For underwater areas directly adjacent to the current instance's simulation volume (reefs, shallow submerged ruins within the sea instance's footprint). No transition occurs — the player character moves from surface to below the waterline within the same sea instance. The rendering system switches to underwater rendering mode. This is the most common diving scenario during sea exploration.

Deep dive (sub-instance): For deeper underwater content (sunken ship interiors, deep ocean trenches, underwater dungeons) that are structurally separate from the sea instance. These are land-instance-equivalent sub-instances with an underwater tileset.

Deep dive transition sequence:

Player reaches underwater entrance within the sea instance (an air-pocket cave mouth, for example)
Server begins creating the underwater sub-instance
Client plays dive animation (character descends below the camera threshold)
Underwater visual filter applied (color shift, muffle audio)
Brief black-out as the character enters the narrow entrance (natural geometry-based visual hold)
Connection transitions to sub-instance
Character appears in the underwater area's spawn point

Return from deep dive reverses the sequence. The adjacent sea instance remains available — the character surfaces back into the sea instance's simulation volume.

Instance Directory Service

All active instances are registered in a distributed Instance Directory — a Redis Cluster providing sub-millisecond lookup for:

Instance ID → server endpoint (IP:port)
Chart region ID → list of active sea instances for that region
Character ID → current instance ID (for cross-instance messaging and party coordination)
Ship entity ID → current sea instance ID (for fleet coordination)

The Instance Directory is the coordination layer that makes transitions seamless. Before sending a client to a new instance, the server looks up the instance endpoint in the directory and validates it is still alive. If the instance has crashed (missed heartbeat in the last 5 seconds), a new instance is created before the transition proceeds.

High availability: The Instance Directory uses Redis Cluster with 3 primary + 3 replica nodes across two availability zones. Failover to a replica takes under 500ms — fast enough that an in-progress transition may stall briefly but not fail. The gateway service caches frequently accessed directory entries locally with a 100ms TTL, further reducing directory lookup latency for active transitions.

Instance Pooling and Process Reuse

Cold-starting a new instance process (fork + exec + initialization) takes 2-5 seconds. To achieve the 200ms warm-start target for land instances and 1-second target for sea instances, the simulation server maintains a pool of pre-warmed processes:

Land instance pool per server: 20-50 idle processes, each initialized up to the point of map seed assignment. These processes have the game simulation code loaded, the tick loop idle, and are waiting for a seed and player list. Assignment time: ~200ms (seed application + monster spawning).

Sea instance pool per server: 5-10 idle processes, initialized with the sea instance framework (ocean simulation initialized, entity registry empty). Assignment time: ~800ms (region parameterization + initial NPC ship spawning).

At Voyage launch, pool sizes are expanded: 200 land instance processes and 50 sea instance processes are pre-warmed per simulation server cluster in anticipation of the first-hour spike.

Memory and Resource Accounting

Per-instance memory estimates:

Instance Type	Memory (typical)	Memory (peak)
Small land instance (island, 50 monsters)	150 MB	300 MB
Large land instance (fortress dungeon, 200 monsters)	350 MB	600 MB
Boss arena (pinnacle boss, scripted)	400 MB	800 MB
Sea instance (8 ships, 100 NPC entities, weather)	600 MB	1.2 GB
Port/town instance (100 players, NPCs)	250 MB	400 MB

Server fleet sizing (per region, Voyage launch target):

Server Role	Instances Hosted	RAM per Server	Count
Land simulation servers	40-60 land instances	64 GB	24
Sea simulation servers	8-12 sea instances	128 GB	12
Port instance servers	5-8 port instances	32 GB	4
Account Authority DB	—	256 GB	6 (3P+3R)
Trade + Social services	—	32 GB	4
Gateway + routing	—	16 GB	4

Total per-region server count at Voyage launch peak: ~54 active servers plus cloud burst headroom. At sustained non-launch load, approximately 20-25 servers handle the steady state.

Cross-references: design/10-technical-architecture/server-architecture.md, design/10-technical-architecture/networking-model.md, design/10-technical-architecture/performance-optimization.md, design/topology/system-topology.md