Events

1. What it is

Events are world-space hold-to-charge zones the player encounters during a run. Each event is a dotted ring at a fixed world position; standing inside it fills a charge meter and, on completion, dispatches a type-specific reward (XP, weapons, artifacts, healing, combat bursts, gravity pulls, etc.). Events are placed at hubs and scattered across the level on generation; they do not respawn after being completed or failed.

2. Stats and variables

2.1 Event types and rewards

Type	Pool count	Pool share	Reward on completion
levelup	27	38.0%	Player gains one level; fractional XP progress within the band is preserved
magnet	10	14.1%	Global XP-orb vacuum — every orb on the map flips to exponential lock-on
weapon	6	8.5%	Spawns a weapon chest at event center (radius 15) for normal pickup
regen	5	7.0%	Spawns a 30-second healing zone at event center; ship heals 1% HP/sec while inside
artifact	4	5.6%	Queues an artifact upgrade reward; falls back to a weapon chest if the player owns fewer than 2 artifacts or has no non-legendary artifacts
forager	4	5.6%	Drops a ring of 8 XP orbs (12 XP each) at event center
horde	3	4.2%	Spawns 4 rare-tier chargers in a 110 px ring around event center
comet_shower	3	4.2%	Force-spawns up to 5 Comet Fragment props in a 110 px ring around event center
pulse	3	4.2%	Damages every enemy within 600 px for 250 flat damage, routed as player-source damage
vortex	3	4.2%	Triggers a Magnetar pull at event center; enemies within 220 px are yanked inward
starpower	2	2.8%	Applies the Star Power exclusive state for 15 seconds (stacks with existing star-power timers)
cascade	2	2.8%	Fires the Supply Pod cascade primitive (5-prop ring: 2 Scrap, 1 Mineral, 1 Comet, 1 Magnetar by default)
wheel	0 in default pool	n/a	Opens the Wheel of Fortune overlay; sim freezes via timeDilation = 0 and music low-pass drops to 1000 Hz

Default pool size is 71 entries; selection is uniform random over duplicates.

2.2 Radius by type

Radius bucket	Value (px)	Types
Tight	110	starpower, regen
Small	130	levelup
Large	220	magnet, weapon, artifact, wheel, cascade, forager, horde, comet_shower, pulse, vortex

2.3 Charge mechanics

Variable	Value
Base charge time	6 seconds (EVENT_CHARGE_TIME of 4 × 1.5 multiplier)
Inside-zone charge acceleration	+10% rate per second of continuous occupancy
Outside-zone drain rate	0.15 charge units per second
Exit grace period before fail	8 seconds outside the zone
Exit warning fires at	5 seconds before failure (3 seconds after leaving)
Completion flash duration	2.0 seconds
Failure flash duration	1.0 second
Completion particle burst	25 spark particles at RGB 80,255,120 with speed 100

2.4 Phase machine

Phase	Trigger	Behavior
idle	Initial state	No charge progress; waits for player entry
active	Player enters zone	Charge fills; exit drains; exit grace timer runs when outside
done	Charge reaches chargeTime	Reward dispatched; eventsCompleted counter incremented; flash plays then event is spliced (non-hub) or persists (hub)
failed	Exit timer exceeds exitTimeMax	Failure flash plays; non-hub events spliced; hub events revert to idle and reset
completing	Reserved	Listed in the phase enum but never assigned in the runtime

2.5 Hub-tagged events

Behavior	Non-hub event	Hub-tagged event
Charge mechanics	Standard	Standard
Exit failure	Splices out on failed	Never fails; exitTimer is reset to 0 each frame while active
Behavior on done	Splices after flash	Persists as a permanent beacon after flash
Behavior on failed	Splices after flash	Reverts to idle, resets charged/initiated/exitTimer/insideDuration/exitWarning

2.6 Spawn placement constants

Constant	Value (px)	Purpose
Super-chunk size	800	Grid used by chunk-based bookkeeping
Spawn torus outer radius	1500	Maximum distance from player for legacy chunk eligibility
Spawn torus inner radius	600	Minimum distance from player for legacy chunk eligibility
Revisit cooldown	3 seconds	Time a chunk must go unseen before re-evaluation
Minimum distance from origin	500	Keeps the starting area clear of events
Minimum event separation	500	World-space gap enforced between any two event centers
Scatter cell size	600	Jittered-grid cell width for level-wide scatter pass
Scatter attempt chance	0.75 per cell	Fraction of cells that receive a placement attempt
Scatter terrain padding	40	Inside-terrain buffer used by scatter placement rejection
Terrain clearance around event	event radius + 80	Radius within which terrain is removed when an event is placed
Per-extra placement attempts	6 angles	Number of angle retries before the extra slot is skipped
Extra radial band inside hub	40%–90% of hub radius	Range within which extras are placed around hub center
Hub fallback radius	300	Default hub clear radius when none is supplied
Default level radius	2500	Used when level data does not specify a level radius

2.7 Runtime spawn filters

Type	Removed from pool when
artifact	Player owns fewer than 2 upgradeable artifacts
regen	Ship has not taken hull damage in the current run (lowestHpPercent equals 1)

If filtering empties the pool, the fallback pool is weapon only.

2.8 Density

Parameter	Default	Effect
densityMult	1.0	Average extra events per hub on top of the guaranteed center event; floor + Bernoulli(frac) per hub

2.9 Datacore artifact (event_reward) tiers

Tier	Upgrades on complete	Heal on complete	Invuln on complete (s)	Event spawn multiplier
1	2	0%	0	1.00×
2	2	75%	5	1.20×
3	3	100%	8	1.40×
4	4	100%	15	1.75×

2.10 Bacta Tank artifact (event_healer) tiers

Tier	Heal	Invuln (s)	Damage buff	Buff duration (s)	Shield restored	Crate spawn
1	100%	5.0	+25%	15	no	0
2	100%	8.0	+40%	18	no	0
3	100%	12.0	+65%	22	yes	0
4	100%	18.0	+100%	30	yes	8

2.11 Trigger-based events

Trigger type	Fires on
event	Player enters trigger radius once (default) or every entry when oneShot is false

Trigger-based events are level-script primitives separate from the world-generated event pool. They fire a callback when the player crosses into a level-author-defined radius and can be one-shot or repeatable.

3. How it works

• Events are placed during world generation: one event at the center of each hub, plus a floor-plus-Bernoulli count of extras inside the hub’s clear area, plus a level-wide jittered-grid scatter pass between hubs.
• Each hub seeds exactly once per run; completed or failed events do not respawn on revisit.
• Pool selection is uniform random over the duplicate-weighted default pool of 71 entries.
• The runtime pool is filtered each seed call by current run state, removing artifact events while artifact count is below 2 and removing regen events while the ship has full hull.
• Hub-center placement is fixed; if existing terrain overlaps, that terrain is removed within event radius plus 80 px and the terrain chunk index is rebuilt.
• Extras try up to six angles before the slot is skipped; rejection causes are proximity to another event under the separation rule or sitting inside terrain.
• Scatter placement rejects candidates that are inside the origin guard ring, beyond 95% of level radius, too close to another event, or inside terrain.
• The proximity check each frame uses the player ship position; the inZone flag is true when the distance from the ship to the event center is less than the event radius.
• The charge accumulator increases by dt while inside, scaled by 1 + insideDuration × 0.10, and decreases by 0.15 × dt while outside.
• Spark VFX begin once charge exceeds 10% of charge time; spark spawn chance scales with progress, particles ride the event ring at 90% of event radius, and particle size grows from 2 to 5.
• On entering the zone the event is marked initiated, exitTimer is zeroed, and exitWarning is cleared.
• On leaving the zone after initiation, exitTimer counts up; insideDuration resets to zero so the charge acceleration restarts from scratch on re-entry.
• The exit warning flag latches at exitTimer ≥ (exitTimeMax − 5).
• On completion the phase flips to done, the event is added to the per-frame completed list, completeFlash is set to 2.0 seconds, and a 25-particle green spark burst plays.
• On completion the reward dispatcher in bridge.ts also fires an event_complete signal at the event position with the event type, plays the type-keyed audio cue and screen shake, and tints the screen with the type-keyed VFX color.
• Eventsompleted is incremented in game.tracking.eventsCompleted for run-tracking purposes.
• Non-hub events that reach done or failed wait out the completeFlash timer then splice themselves out of the world events array.
• Hub-tagged events that reach failed revert to idle with a full state reset; hub-tagged events that reach done play the flash then persist as permanent beacons (never spliced).
• On the first gameplay tick of a run a one-shot diagnostic message is emitted with the current count of alive, done, failed, and hub-tagged events.
• Spawn-time logs cover the seed call (pool requested vs. active, density, hub counts, placements by category) and the per-run init call (pool requested vs. active, density).
• Trigger-based events run through the trigger system, which checks each tick whether the player has crossed into a trigger’s radius and fires the matching callback.

4. Interactions

• Charge acceleration compounds with continuous occupancy; staying inside doubles the fill rate at 10 seconds and triples it at 20 seconds before reaching the 6-second base completion target.
• Leaving the event mid-charge does not zero progress immediately; the drain rate of 0.15 per second means the player can re-enter within seconds without losing the whole charge, but the acceleration multiplier resets to 1.0×.
• Weapon events that resolve while all weapon slots are full route through the weapon-box collect pipeline, which grants +1 level to every equipped weapon instead of spawning a new weapon.
• Artifact events fall back to spawning a weapon chest when the player owns fewer than 2 artifacts or when every owned artifact is already at legendary tier.
• Wheel events freeze the simulation by setting timeDilation to 0 and pull music low-pass down to 1000 Hz until the wheel overlay exits.
• Star Power events apply the starpower exclusive state for 15 seconds and stack additively with any active star-power timer from other sources.
• Pulse events route damage through the standard damageEnemy path with source player, so the burst earns streak progress, XP, debris drops, and artifact procs as if the player killed each enemy.
• Vortex events use the existing Magnetar pull primitive; they do not deal damage themselves and rely on the player’s weapons to convert the clumped enemy ball into kills.
• Comet shower events fan-spawn comet fragment props, each carrying the comet’s 35% speed-boost-on-ram synergy; ramming the full ring stacks roughly 1.75 expected boosts.
• Horde events spawn rare-tier chargers, so their loot stream goes through the standard affix death-drop path (volatile crystals from volatile elites, mineral veins from regenerating, etc.).
• Cascade events reuse the boss-kill reward-chamber cascade primitive — 5-prop ring with the same default mix the boss flow uses.
• Forager events drop standard XP orbs, so the magnet aura, magnet artifacts, and global magnet events from other sources all act on them normally.
• The Datacore artifact fires on the event_complete signal and grants random ship upgrades, optional percent-max heal, and a brief invuln window; higher tiers also raise the event spawn multiplier so future levels seed more events.
• The Bacta Tank artifact fires on the same event_complete signal and restores hull, optionally restores shield, applies a flat damage buff for a fixed duration, and at tier 4 spawns 8 crates.
• The event_complete signal is fired with the event’s world position and type string so signal listeners can branch by event type.

5. What it does NOT do

• Does not garbage-collect events by distance or time after seeding; the legacy decay timer field exists on each event but is no longer ticked.
• Does not respawn events at a hub once that hub has been seeded; the _seededHubs set is checked before every seed call.
• Does not spawn crates from the legacy event-spawner chunk loop; the chunk torus is still walked for bookkeeping but the crate spawn hook is a no-op.
• Does not include wheel in the default event pool; it is a defined event type but is not in the default pool builder.
• Does not assign the completing phase from any code path; it exists in the phase enum as a reserved value.
• Does not let lantern-tagged events fail; they reset exitTimer to 0 every frame instead of crossing the failure threshold.
• Does not gate event completion by event type at the charge layer; all types share the same hold-to-charge state machine, and only the post-completion reward dispatch differs.
• Does not extend the charge time for higher-value reward types; every event type uses the same 6-second base charge time.
• Does not require the player to stay inside continuously to complete; brief exits drain only at 0.15 per second, well below the inside fill rate.
• Does not apply event spawn multipliers from artifacts to the density used by the event spawner inside this file; the spawner consumes the multiplier through the init density parameter set elsewhere.
• Does not log completion telemetry for levelup, magnet, weapon, artifact, regen, starpower, or wheel events; only cascade, forager, horde, pulse, vortex, and comet_shower record director-phase telemetry on completion.