BlupiController

Blupi's body: movement, collision, jumping, swimming, vehicles, powers and the animation state that picks his clip.

Location

Older pages called this class GEBlupiController and described an invisible collision point. Since then Blupi is drawn as a 3D model converted from the original Ray Dream scenes; the controller decides which clip that model plays. (The class comment at the top of the header still describes the early placeholder; the code is current.)

Purpose

BlupiController reproduces the original game's movement rules in 3D. Each call of Step() turns one tick of steering input into a new position and status: tank-style turning (135 °/s) and walking (2.5 cells/s once under way, after the original's four-tick ease-in), the original's jump speeds and gravity, ledges and walls, crouching and looking up, swimming at the surface and under water, hanging on bars, being squashed or ballooned, riding lifts and crates, six vehicle modes, secret powers, and the one-shot actions (switch, dynamite, pickups, death). It also keeps an AnimState from which the host chooses Blupi's model clip, and it reports one-shot cues (head bump, bar grab, turn, idle fidget) as events for the host to play as sounds.

Speeds are written in the original's units: 64 pixels per block and 20 ticks per second, so 8 px/tick becomes 8 × 20 / 64 = 2.5 blocks per second.

Collaborators

Uses

• World and BlockDefinitionRegistry (collision masks, water, springs, bars, hazards).
• SolidBox.hpp (solid BigDecor), BarRows.hpp, LavaHeight.hpp, FanGeometry.hpp, BlockModels.hpp, PlateRotationMetadata.hpp.
• WorldRuntime's centre constants (kWorldCenterX/Z) only.

Used by

• GalaxyEggbertGame: owns one blupi_, feeds it input, the terrain phase, crate cells and lift state every tick, and applies InteractionSystem events to it.
• VerifyBlupiMovement drives it with scripted input; WorldRuntime reads its body constants for fan contact.

InteractionSystem does not use it: the two meet only in the host.

Key members

The header is about 1 800 lines, most of it constants with the original's values and their sources. A selection of the public API of BlupiController.hpp (verified 2026-11-10):

AnimState

An enum class AnimState : std::uint8_t with one value per live action of the original's table_blupi: Stop, March, Jump, Air, Down, Up; the squashed and balloon states; each vehicle's stop/march pair; StopNage/MarchNage and StopSurf/MarchSurf for swimming; StopSuspend, MarchSuspend, JumpSuspend on bars; actions such as Push, Switch, TakeDynamite, PutDynamite, FireTank, HelicoGlu; the mockery and reaction poses (Mockery, JumpAie, Ouf1a ... Ouf5, Vertigo, Recede, Advance); Win, Turn, Bye, Teleporting, DeathLocked, PickupBusy, and the short transitions StopMarch and StopJump. The Blupi model in avatars3d/blupi/ has a clip for each state.

How it is used

The host prepares the tick's facts, then steps him once per tick with the scaled simulation time:

const float stepStartFeetY = blupi_.GetY();
...
blupi_.SetTerrainAnimationPhase(worldRuntime_.GetAnimPhase());
blupi_.Step(worldRuntime_.GetWorld(), steering, moveInput, jumpPressed,
            crouchHeld, lookUpHeld, simDt, tempPassable, inSurfWater, inDeepWater,
            wasPushingCrate_, holdingCrate_);

Afterwards it reads EventsThisFrame() for sounds, compares before/after state (landing, water entry, teleport end) and runs the actions. Mission starts go through PlaceBlupi, which sets the crate cells and calls SettleOnGround.

Movement facts worth knowing

• No step-up. As in the original's Decor::TestPath, a one-block step stops Blupi until he jumps. kStepLimit is a 4-pixel tolerance so seams between almost equal heights do not snag him (it was a whole block until 2026-10-25).
• Swimming. In water there is no gravity: Jump or Right Shift swims up, Left Shift down. At the surface he floats until he dives; Jump with open air above makes the weak jump out onto a bank. The air gauge drains only under water.
• Vehicles have their own maximum speeds, acceleration and gravity: the jeep and tank fall heavier than Blupi, and the jeep with ground under one end only rolls off the edge nose first, tipping up to 45°; the helicopter sinks slowly when idle; the overcraft climbs only with ground within 80 original pixels below it. Water, a spring or the helicopter hitting a ceiling wrecks the vehicle (applied by the host's WreckVehicle()).
• Bars. On a hanging bar he moves along it, can jump off, and does not re-grab for a moment after letting go.

Rules and invariants

• Engine independence. No CNA, cna-engine, camera or input type appears in the header or source. Terrain facts that need WorldRuntime (the Temp phase, water at the feet) are passed in as booleans. This is what lets VerifyBlupiMovement run without a window.
• Deterministic. The same inputs and dt give the same path; the golden trace, autoplay scripts, the resume log and demos rely on it.
• The original's numbers. Speeds, durations and gates come from the reference game and carry their sources in comments; changing one changes the timing of every playthrough script.

Tests

• VerifyBlupiMovement (ctest, runs from the repository root): drives Step() against worlds3d/world999.vwr with scripted input. It covers walking and the first-tick start after SettleOnGround, jumps, gravity and falls, walls, crates and footprints as support, temporary platforms, swimming, vehicles (including penetration recovery for foot, jeep, tank and helicopter) and the one-shot sound cues.
• VerifyInteractionSystem also creates controllers to check deaths and blasts end to end.
• The golden trace (tools/verify_golden_trace.sh) records position, vertical speed, ground contact and animation per tick for a fixed walk and jump; any change in movement shows up there.

Related pages

• Collision, Game Loop, Gameplay, Controls
• InteractionSystem, WorldRuntime, GalaxyEggbertGame, BlockDefinitionRegistry
• Testing