Explorable Areas (Star Systems) — Design

Explorable Areas (Star Systems) — Design

Status: APPROVED (2026-06-28, Chris) — ready to plan · Date: 2026-06-28 Prerequisite — ALREADY SATISFIED (verified via git 2026-06-28): the biomass spawner is already MERGED and live (feat/biomass-spawning fast-forwarded into main; shipped as BUILD 68 to TestFlight; present in main + the drone branch — SpawnTable, total_biomass, the wave phase machine). So an area swaps the biomass spawn-table as the “Area model” intends, and the area system builds DIRECTLY on the current branch (no merge needed). The earlier “merge biomass first” framing was based on a stale note; biomass is in the build on the TV now. (Minor housekeeping still open: remove the dead leftover SpawnDirector code — not a blocker for areas.) Sequence: depends on the biomass wave spawning system (an “area” is a swappable spawn config) and benefits from more enemy content — so it lands after the spawner, sequence otherwise flexible. Vision horizon: eventually a map of star systems you fly between (EVE-style), each with its own enemies, backdrop, rewards, and collectibles. This spec commits only to the first concrete step: one extra area reached by a wormhole.

Vision

The single arena becomes one of many areas (star systems / constellations). You travel between them via wormholes, each area has a distinct look + enemy roster + rewards, and over time a system map lets you choose where to go. Long-term this is how content breadth + replay variety scale.

First concrete step (what we build now)

Add one second area — “Aurora” — as a harder stage 2:

1. Wormhole spawn: after you defeat a boss (decided), a wormhole icon spawns at a random play-field location — a pulsing, sparkling cosmic portal (animated swirl + glow). It lingers; ignoring it just continues the current area.
2. Travel: fly the ship over the wormhole → a brief warp transition (~1–1.5s: ship pulled in, a streaking tunnel/fade, arrive) — long enough to sell “travelling between systems,” short enough not to drag.
3. Arrive in Aurora: new background (aurora-themed), the same enemy roster at a higher difficulty multiplier (no bespoke Aurora enemies yet — those wait until the roster is bigger), and better rewards (gold/XP multiplier, possibly area-specific upgrades). You carry your run — build, level, HP — into it (decided); it’s continuous travel into deeper space, not a fresh run.

Two-way (decided): Aurora also spawns a return wormhole (after its boss, same rule) so you can fly back to Home. So travel is bidirectional from the start; a full multi-system map is the long-term layer. (Both areas reuse the same “boss-kill spawns a wormhole” rule; the wormhole’s destination is the other area for now.)

Area model (data-driven)

An Area definition (new areas in bible.json or a dedicated file):

• id, name
• spawn config — its own probability table + biomass tuning (reuses the biomass spawner; an area just swaps the table + difficulty multiplier)
• background — which ArenaBackground variant (new “aurora” backdrop added)
• boss/elite pool — which bosses/elites can appear here
• difficulty multiplier — Aurora ramps higher
• rewards — gold/XP multiplier, and optionally area-only upgrades

The current arena is the default “Home” area. Adding more areas = adding data entries.

Architecture

• Sim: a current_area id; switching area swaps the active spawn config + boss pool and resets the field (clears enemies, re-seeds the wave loop for the new area). The biomass phase machine continues in the new area. Deterministic — the switch is triggered by the player contacting a deterministically spawned wormhole, like any pickup.
• Wormhole: a pickup-like entity (Sim.wormholes) spawned by the trigger; on player overlap it fires an area_transition event. Render-side: a WormholeRenderer (pulsing swirl) + the warp transition VFX in main (which briefly pauses the sim tick, plays the effect, then calls Sim.enter_area(id)).
• Backgrounds: extend ArenaBackground with an “aurora” variant; the area picks its background (the existing grid/starfield/nebula stay as Home’s random pool).
• Transition: render-only warp effect (camera/streak/fade) over a short timer; the sim is frozen during it (like the level-up grace), then resumes in the new area.

Determinism

Area switching is deterministic (player-contact with a deterministically-spawned wormhole → enter_area). The wormhole spawn is gated well past the survival baseline window (it triggers on a boss defeat, which never happens in the <10s baseline), so the determinism baseline is unaffected. Verify on build.

Long-term (noted, not built yet)

• A system map screen: choose your next system (branching paths, risk/reward).
• Bidirectional travel + persistent per-area state.
• Per-area collectibles / unlocks (area-specific currencies, blueprints, drone parts…).
• Areas as the backbone of run structure (a run = a route through several systems → a final system boss).

Decisions (resolved 2026-06-28)

1. Wormhole trigger: after a boss kill (gateway-to-next-system; ties into the biomass spawn loop).
2. Carry your build/level/HP into the new area (continuous travel, not a fresh stage).
3. Two-way travel: Aurora spawns a return wormhole (same boss-kill rule) so you can hop back to Home.
4. Aurora = “harder Home + new look” to start: same enemy roster at a higher difficulty + a distinct aurora backdrop + better rewards. Bespoke Aurora-only enemies wait until the roster is bigger.