WorldRuntime

The world as it is being played: the voxel grid, the live object list, BigDecor, spawn point and the animation clock.

Location

Older pages called this class GEWorldRuntime; the GE prefixes were dropped when the game code moved to src/GalaxyEggbert/Game/.

Purpose

WorldRuntime turns a world file into the state the game plays on. It owns a World (the 100 × 100 × 100 voxel grid) and derives from it everything that changes during play or that other systems look up every tick: the list of moving objects (MobileObjSpec), the BigDecor scenery and its solid boxes, the training-hint zones, the spawn point, the sky region and the mission number. It also keeps the world's animation clock, which advances at the original game's 20 Hz reference rate, and offers a few pure helpers that encode the original's timing and mission arithmetic.

Collaborators

Uses

• World and its records: MoveObjectRecord, BigDecorRecord, HintZoneRecord, PlayerStart.
• ObjectDefinitionRegistry to skip unsupported or null-placement object types.
• LegacySawFloors.hpp (upgrades old saw cells on load), FanGeometry.hpp, SolidBox.hpp; the body constants of BlupiController for fan contact.

Used by

• GalaxyEggbertGame: LoadMission, the title scene, editor play-tests, demo and resume validation.
• InteractionSystem: moves, collects and spawns objects in the mutable object list.
• TerrainRenderer and the scene builder: animation phase, objects, BigDecor.
• WorldEditor through the host: edits the mutable World, then ResyncFromWorld().
• Verifiers: VerifyShippedWorlds, VerifyInteractionSystem, VerifyMoveObjectTypesCna.

Key members

A selection of the public API of WorldRuntime.hpp (verified 2026-11-10):

MobileObjSpec

One moving or interactive object, in plain floats. The fields that matter most:

Coordinates and the world centre

Files, editor and tools use raw grid cells 0-99. The simulation and the renderer use centred coordinates: X and Z minus kWorldCenterX/kWorldCenterZ (50), Y unchanged, so the world sits around the origin. ResyncFromWorld() applies the shift when it builds MobileObjSpecs and BigDecor cells, and the spawn is offered both ways (GetSpawnTileX raw, GetSpawnRenderX centred). Blupi's position in BlupiController is centred too; crate cells and solid boxes handed to it are raw.

Animation phase

Update(dt) accumulates time and advances animPhase_ once per 1/20 s, the original's reference tick; each object's phase advances by dt × 20. Animated tiles divide this tick by their own divisor (from BlockDefinitionRegistry) before choosing a frame. The hazard helpers read the same tick:

bool WorldRuntime::IsBlitzActiveAtPhase(int animPhase) noexcept
{
    const int cycle = ((animPhase % 100) + 100) % 100; // defensive: handle a negative phase
    return cycle % 2 == 0 && cycle < 50;
}

Lightning is lethal on even ticks of the first half of a 100-tick cycle; a crusher when (phase/3)%10 <= 2; a vanishing (Temp) tile is passable when (phase/4)%20 >= 18. The host passes the Temp result to BlupiController::Step as a plain bool.

How it is used

The host loads each mission from bytes it has already read, then re-applies the galaxy mission number when needed:

std::istringstream world(bytes ? *bytes : std::string{}, std::ios::in | std::ios::binary);
if (!bytes || !worldRuntime_.LoadFromVwrStream(world))
{
    ...
    return;
}
loadedMissionPath_ = path;
loadedMissionHash_ = ResumeLog::HashBytes(*bytes);
if (galaxyGamer_ >= 0) worldRuntime_.OverrideMissionNumber(missionNumber); // its place in the galaxy

Every Play tick starts with worldRuntime_.Update(simDt); InteractionSystem::Update then works on GetMobileObjectsMutable().

Mission arithmetic: from the main hub (mission 1) sign N leads to world N×10 (sign 13 to the showcase, world 999, except in a player's galaxy); inside a world hub sign N leads to mission hub+N and sign 199 back to the main hub. ComputeMissionBack returns to the mission's hub, or from a hub to the main hub. ComputeWinExitTarget(1) is 199 (the bonus world) and ComputeWinExitTarget(199) is 1.

Rules and invariants

• Engine-independent: no CNA or cna-engine include, so the verifiers can load worlds without a window.
• Object timing is the original's: the loader forces the big creature (type 54) to rest 152 ticks at each end, whatever the file says.
• ResyncFromWorld() deliberately leaves the animation clock alone; LoadFromVwrStream() resets it, so a newly loaded world starts at phase 0.
• Old worlds with implicit saw floors are upgraded in memory on load (UpgradeLegacySawFloors).

Tests

• VerifyShippedWorlds: every worlds3d/*.vwr loads through LoadFromVwrFile, carries the mission number of its file name, yields its objects, and survives load, save, load unchanged.
• VerifyInteractionSystem: loads world999 and checks, among much else, the Blitz, crusher and Temp cycles and patrol timing.
• VerifyMoveObjectTypesCna: LoadFromMobileEggbertFile on original world files (needs the sibling reference checkout).

Related pages

• World Loading, VWR Format, Object Lifecycle
• World, Chunk, MoveObjectRecord, HubDoors
• InteractionSystem, BlupiController, GalaxyEggbertGame
• Game Loop, Campaign & Worlds