# World Runtime (Loading, Entities, Cleanup, Effects, Audio)

## Purpose
This document describes world-level runtime systems: map loading, reset/cleanup, world entities, effects, and audio.

## Authority map
- Scene/map load entry:
  - `Code/World/Loading/TerrorTownSceneLoader.cs`
  - `Code/World/Loading/TerrorTownLegacyMapLoader.cs`
- Reset/capture core:
  - `Code/World/MapEntities/ResettableMapInstance.cs`
  - `Code/World/MapEntities/RegisteredResetModule.cs`
- Round cleanup barrier integration:
  - `Code/Game/Systems/RoundCleanupSystem.cs`
- Cleanup tags/interfaces:
  - `Code/World/MapEntities/DestroyBetweenRounds.cs` (`DestroyBetweenRounds`, `DestroyOnMapCleanup`, `IResettableSpawner`).
- Map entity behaviors:
  - `Code/World/MapEntities/*` (doors, buttons, glass, replacements, temporary effects, map network root).
- Physics/props systems:
  - `Code/World/Physics/Props/*`
- Effects systems:
  - `Code/World/Effects/Particles/*`
- Audio systems:
  - `Code/World/Audio/*` and `Code/World/Audio/Voice/*`.

## Reset/cleanup model
- `RoundCleanupSystem` runs a host cleanup barrier before each round start listener `OnRoundStart`.
- Barrier performs:
  - force-drop temporary grabber ownership interactions,
  - destroy tagged cleanup objects/corpses,
  - static marker reset,
  - optional legacy-map cleanup/reset pass.
- `ResettableMapInstance` supports fast reset via `IResettable` + slower serialized recreation fallback.
- Option 3 registered-reset path:
  - `RegisteredResetModule` captures map-authored `IResettable` components after legacy map load completes.
  - `ResetMap()` resets the captured registry first (host-only), with scene-scan fallback if registry is unavailable/empty.
  - Legacy serialized recreation fallback remains in place for safety (non-resettable serialized objects).
- `SpawnSystem` physical respawn batch executes in `OnRoundStart`, after cleanup barrier completion.

## Legacy map bridge
- `TerrorTownLegacyMapLoader` converts legacy entities to modern components/prefabs.
- Conversion/network spawning is host-owned; clients do not destroy mapped runtime entities during `OnCreateObject`.
- Runtime entities are parented under `MapNetworkRoot` (`MapNetworkRoot.Ensure(Scene)`) with fallback to `Scene` if unavailable.
- Loader now keeps aggregated diagnostics for conversion routes, type counts, netspawn/destroy counts, and map-root fallback occurrences.
- Loader clears/reset-captures the registered-reset registry across load boundaries:
  - clear on `OnLoad`
  - capture on `OnFinishedLoad` (host only).

## Diagnostics
- Map loader:
  - `t.db.maploader` enables conversion/reset diagnostics and summaries.
  - `t.maploader.dump` emits a manual diagnostics summary from current loader instance.
- Registered reset module:
  - `t.reset.registry.enable` toggles Option 3 registry reset path.
  - `t.db.resetregistry` enables registry capture/reset/compaction diagnostics.
- Parenting/network spawn diagnostics:
  - `t.db.netparent` logs `SetParent` and `NetworkSpawn` parent-state details.

## Hardening playtest checklist (map/runtime)
1. Enable diagnostics:
   - `t.db.maploader 1`
   - `t.db.netparent 1`
   - `t.db.use 1`
2. Load a legacy-backed map:
   - Confirm map loader summary logs on load (`[maploader.db] summary marker=finished_load`).
3. Start a round and run cleanup barrier:
   - Confirm cleanup begin/end logs and stable route/type summaries.
   - Confirm fast reset log includes registry status (`[FASTRESET] ... registry=True/False ...`).
4. Validate interaction regressions:
   - Doors are pressable/openable.
   - Legacy-spawned dropped weapons/ammo are pickable.
   - Health station interaction/range checks work when parented under map root.
5. A/B validation for non-regression:
   - Run one full round with `t.reset.registry.enable 1`.
   - Run one full round with `t.reset.registry.enable 0`.
   - Confirm parity for:
     - player spawn/lifecycle behavior,
     - door/glass/prop reset behavior,
     - pickup/use behavior.
6. Request manual snapshot during runtime:
   - Run `t.maploader.dump` and inspect route/type distribution and fallback counters.

## Voice and world audio
- Voice routing is filtered via `IVoiceFilter` contracts and `PlayerVoiceComponent`.
- World audio effects (footsteps, explosions, round sounds) live under `Code/World/Audio/`.

## Related docs
- Host loop and cleanup barrier position: `Code/Core/Documentation/game-loop.md`
- Items and spawner behavior: `Code/Core/Documentation/items-weapons-equipment.md`