Log inGet started
Package

Motor.component

Newest version

README.md

umbral.Motor

Ilva's motor: a 2D platformer body driven on the engine's own physics.

Attaches to: the player body entity (the body of the scene's PlayerPrototype). It needs a BoxCollider and a Physics component — it adds both itself if they are absent — and it reads an input map carrying move, jump and sprint, which the scene supplies as inputMaps.umbralMove (keyboard, gamepad and touch together).

Why it is not a script-driven kinematics solver

The body is a dynamic rigid body with a box collider, held to the XY plane by axis locks (lockTranslationZ, lockRotationX/Y/Z). This component writes the horizontal velocity from the move control and the vertical velocity for jumps; the engine's simulation does the rest — collisions, one-way ledges, contact with anything in the world. Nothing here re-implements collision, so a ledge added anywhere in the scene works the moment it exists.

twoDKit.Player2D was installed first and rejected: its motor holds the body still unless a twoDKit.Level2D exists (update returns early on #Levels.all() == 0), and it activates controlsKit's platformer scheme, which suppresses every other input map in the player group. UMBRAL builds its own architecture, so both were dead weight here.

Feel, and the fields that set it

FieldDefaultWhat
speed7.5Top horizontal speed, units/s.
accel / airAccel60 / 34How fast she reaches it on the ground and in the air.
friction48How fast she stops with no input on the ground.
jumpSpeed15.5Upward speed a full jump gives.
jumpCut0.45Share of the rise that survives letting go early — variable height.
airJumps0Mid-air jumps. Set to 1 by the Vuelo de la Sal.
canDashfalseThe Paso de Marea.
coyote / buffer0.10 / 0.12Grace after leaving a ledge, and grace before landing for an early press.

grounded and facing are public and synced, so every peer sees her footing and her heading.

Methods

  • ref:readState() — { x, y, vx, vy, grounded, facing, clock, dashing, airJumpsLeft }. clock advancing is the proof the motor is stepping; if it stays at 0 the body is not being simulated, whatever else looks right.
  • ref:placeAt(x, y) — put her feet at a point, at rest.

The two failures worth remembering

Ground is detected through Physics.groundContact, with a short downward raycast under her feet as the fallback, so a body resting on a merged collider reads as standing.

Movement silently doing nothing has two causes seen here: a control read as v.x when the axis reports a bare number (the handler now accepts both), and a suppressed input map — the motor's own map is in the umbral group precisely because controlsKit's platformer scheme suppresses everything in player.