Jump

A scripted vertical jump arc on a keypress — rise, hang, fall, land exactly where you left.

What it does

Jump is data-only: it holds a key, a peak height, an air-time duration, and a hang factor. The System listens for keyboard.keydown and for a jump.request event; on the configured key it starts a jump, captures the entity's current ground Y, and emits jump.started carrying the duration and height. Each frame while airborne it advances elapsed, computes progress p = elapsed / duration, and writes the vertical offset groundY + height * arc(p) back onto the entity — a followed Mesh's Y if the entity has one, otherwise the MeshPrimitive proxy's Y. When p reaches 1 it snaps back to the captured ground height and emits jump.landed. The arc is 4p(1-p) (a plain parabola) blended toward sin(πp) by hang, so it always peaks at height when p = 0.5 and is symmetric — ascent and descent mirror, which lets a jump animation's midpoint line up with the apex. Only one jump runs at a time: a key-repeat or a second press mid-air is ignored (no double-jump).

Use it in a scene

A scene is just data — a list of entities, each with its components. At startup the SceneLoader turns this JSON into a live world; edit the file and reload to rebuild it.

Build it from scratch with the bjs CLI:

1Scaffold a project
```
npm create @babylonjsmarket/arcade@latest my-game
```
World, renderer, and dev server — ready to run.
2Install dependencies
```
cd my-game && npm install
```
3Add Jump
```
bjs download Jump
```
Copies its source into src/ so the scene resolves.
First time? Run bjs login once.
4Paste the scene into src/scenes/arcade-room.ts and run
```
npm run dev
```
SceneLoader builds the world from the JSON; reload to rebuild.

JSON

{
  "Player": {
    "components": {
      "MeshPrimitive": { "primitive": "capsule", "height": 1.8, "position": [0, 0.9, 0] },
      "KeyboardMover": { "speed": 4 },
      "Jump": {
        "key": "Space",
        "height": 1.6,
        "duration": 0.7,
        "hang": 0.35
      }
    }
  }
}

Props

key (string, default "Space") — the KeyboardEvent.code that triggers a jump. The System matches this against incoming keyboard.keydown events.
height (number, default 1.6) — peak height in world units at the apex (p = 0.5), independent of hang.
duration (number, default 0.7) — total air time in seconds (ascent + descent). Carried in jump.started so an animator can sync a clip to it.
hang (number, default 0.35, clamped to [0, 0.9]) — apex dwell. 0 is a plain parabola; toward 0.9 flattens the top so the character floats at the peak (a game-y, less physical feel).
airborne (boolean, default false) — runtime state owned by the System; true while a jump is in progress. Not config.
elapsed (number, default 0) — runtime state owned by the System; seconds into the current jump. Not config.

Events

emits jump.started (JumpEvents.STARTED) the frame the character leaves the ground, with { entityId, duration, height }.
emits jump.landed (JumpEvents.LANDED) the frame the character lands, with { entityId }.
listens for keyboard.keydown (KeyboardInputEvents.KEYDOWN, payload { code }) and starts a jump on any matching-entity whose key equals code.
listens for jump.request (JumpInputEvents.JUMP, payload { entityId? }) and jumps that entity; a request with no entityId jumps nobody.

Dependencies

None declared. Jump reads a sibling Mesh or MeshPrimitive for the vertical offset if present but doesn't require either — a keyed jumper with no mesh runs without throwing. Something in the scene must bridge DOM key events onto the bus for the keypress path to fire: KeyboardMover (and other input components) already emits keyboard.keydown, so pairing Jump with a mover gives you a walkable, jumpable character out of the box. Without any bridge, drive it purely through jump.request.

Notes

The System prefers a followed Mesh's params.position[1] over the MeshPrimitive proxy — the mesh follow reads that field for its Y (copying only X/Z from the proxy), so writing it lifts the visible figure while the capsule proxy and the camera anchor stay grounded (no jump-bob on the camera).
Ground Y is captured at takeoff and restored on landing, so a jumper standing at y = 0.9 returns to 0.9, not a hard 0.
Per-entity ground state is cleaned up on landing and on entity removal, so removing an airborne entity mid-jump doesn't leak or throw.
The jump is scripted, not physics-integrated: height, duration, and hang fully describe the arc, so it needs no physics engine and won't fight a mover for the transform handle.

Jump.core.ts

Jump — pure core.

A self-contained vertical arc: press the jump key (or emit jump.request) and the character rises then falls along a tunable parabola-with-hang over a fixed air time, back to where it left the ground. The System owns the actual vertical drive + the airborne state machine; this file is serializable config plus the arc math and the event contracts.

The arc is scripted, not physics-integrated — height, duration, and hang fully describe it, so it composes with any mover (KeyboardMover, AI) and needs no physics engine. jump.started carries the duration so an animator can play a jump clip that lands exactly on touchdown (first half ascending, second half descending).

Zero imports from @babylonjs, three, solid-js or the DOM.

Jump.core.ts

import { Component } from '@babylonjsmarket/ecs';

Events

Jump.core.ts

export const JumpEvents = {
  /** Fired the frame the character leaves the ground. Payload: {@link JumpStartedEvent}. */
  STARTED: 'jump.started',
  /** Fired the frame the character lands. Payload: `{ entityId }`. */
  LANDED: 'jump.landed',
} as const;

export const JumpInputEvents = {
  /** Request a jump for an entity (alongside the configured key). Payload: `{ entityId? }`. */
  JUMP: 'jump.request',
} as const;

export interface JumpStartedEvent {
  entityId: string;
  /** Air time in seconds — an animator syncs a clip to this so it lands on touchdown. */
  duration: number;
  /** Peak height in world units. */
  height: number;
}

export interface JumpInput {
  /** KeyboardEvent.code that triggers a jump. Default `"Space"`. */
  key?: string;
  /** Peak height in world units. Default `1.6`. */
  height?: number;
  /** Total air time in seconds (ascent + descent). Default `0.7`. */
  duration?: number;
  /**
   * Apex dwell. `0` = a plain parabola; toward `0.9` flattens the top so the
   * character floats at the peak (a game-y, less physical jump). Default `0.35`.
   */
  hang?: number;
}

Component

Jump.core.ts

export class JumpComponent extends Component {
  key: string;
  height: number;
  duration: number;
  hang: number;
  /** True while airborne. Owned by the System. */
  airborne = false;
  /** Seconds into the current jump. Owned by the System. */
  elapsed = 0;

  constructor(data: JumpInput = {}) {
    super();
    this.key = data.key ?? 'Space';
    this.height = data.height ?? 1.6;
    this.duration = data.duration ?? 0.7;
    this.hang = clamp(data.hang ?? 0.35, 0, 0.9);
  }

  /**
   * Normalized height in `[0, 1]` at jump progress `p` in `[0, 1]`. A parabola
   * `4p(1-p)` lerped toward the fuller `sin(πp)` by `hang`; both peak at `1.0`
   * when `p === 0.5`, so the apex is `height` regardless of hang, and the curve
   * is symmetric — ascent and descent mirror, which is what lets a jump clip's
   * midpoint line up with the apex.
   */
  arc(p: number): number {
    const parabola = 4 * p * (1 - p);
    const full = Math.sin(Math.PI * p);
    return parabola * (1 - this.hang) + full * this.hang;
  }

  serialize(): JumpInput {
    return { key: this.key, height: this.height, duration: this.duration, hang: this.hang };
  }
}

function clamp(v: number, lo: number, hi: number): number {
  return Math.max(lo, Math.min(hi, v));
}

Jump.ts

Jump — System.

Starts a jump on the configured key (or a jump.request event), then each frame drives the character's vertical offset along {@link JumpComponent.arc} for duration seconds and restores the ground height on landing. One jump at a time — a key-repeat or a second press mid-air is ignored (no double-jump).

Vertical drive goes through the entity's own transform data, never a raw renderer call, so it composes with a followed Mesh (the System writes the mesh's position[1], which the follow applies while it copies X/Z from the proxy) and never fights the mover for the handle. Falls back to the MeshPrimitive proxy's Y when there's no Mesh.

Jump.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus, Entity } from '@babylonjsmarket/ecs';
import { MeshComponent } from '../Mesh/Mesh';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.core';
import { KeyboardInputEvents } from '../../inputEvents';
import {
  JumpComponent,
  JumpEvents,
  JumpInputEvents,
  type JumpStartedEvent,
} from './Jump.core';

export class JumpSystem extends System {
  protected query = { required: [JumpComponent] };
  /** Ground Y captured when a jump began, restored on landing. Keyed by entity id. */
  private groundY = new Map<string, number>();

  constructor(eventBus: EventBus) {
    super(eventBus);
  }

  protected onInitialize(): void {
    this.listen(KeyboardInputEvents.KEYDOWN, (e: { code: string }) => {
      for (const entity of this.entities) {
        if (entity.get(JumpComponent)?.key === e.code) this.start(entity);
      }
    });
    this.listen(JumpInputEvents.JUMP, (e: { entityId?: string }) => {
      const entity = e.entityId ? this.world?.getEntity(e.entityId) : undefined;
      if (entity && this.entities.has(entity)) this.start(entity);
    });
  }

  protected onEntityRemoved(entity: Entity): void {
    this.groundY.delete(entity.id);
  }

  private start(entity: Entity): void {
    const j = entity.get(JumpComponent);
    if (!j || j.airborne) return; // already in the air — ignore key-repeat / second press
    j.airborne = true;
    j.elapsed = 0;
    this.groundY.set(entity.id, this.readY(entity));
    this.eventBus.emit(JumpEvents.STARTED, {
      entityId: entity.id,
      duration: j.duration,
      height: j.height,
    } satisfies JumpStartedEvent);
  }

  protected onUpdate(dt: number): void {
    if (dt <= 0) return;
    for (const entity of this.entities) {
      const j = entity.get(JumpComponent);
      if (!j?.airborne) continue;
      j.elapsed += dt;
      const p = Math.min(1, j.elapsed / j.duration);
      const base = this.groundY.get(entity.id) ?? 0;
      this.writeY(entity, base + j.height * j.arc(p));
      if (p >= 1) {
        j.airborne = false;
        j.elapsed = 0;
        this.writeY(entity, base);
        this.groundY.delete(entity.id);
        this.eventBus.emit(JumpEvents.LANDED, { entityId: entity.id });
      }
    }
  }

  /**
   * Current vertical offset — a followed Mesh's Y if present, else the proxy's.
   * The Mesh follow reads `params.position[1]` for the mesh's Y each frame (it
   * copies only X/Z from the proxy), so writing that field is what lifts the
   * figure; the capsule proxy and the camera stay grounded (no jump-bob).
   */
  private readY(entity: Entity): number {
    const mesh = entity.get(MeshComponent);
    if (mesh) return mesh.params.position[1];
    const mp = entity.get(MeshPrimitiveComponent);
    return mp ? mp.position[1] : 0;
  }

  private writeY(entity: Entity, y: number): void {
    const mesh = entity.get(MeshComponent);
    if (mesh) {
      mesh.params.position[1] = y;
      return;
    }
    const mp = entity.get(MeshPrimitiveComponent);
    if (mp) mp.position[1] = y;
  }
}

export * from './Jump.core';

Jump.test.ts

13 ✓

Jump › component

applies defaults
clamps hang to [0, 0.9] and round-trips config
arc is 0 at the ends, 1 at the apex, and symmetric

Jump › system

leaves the ground on the jump key
does not jump on a different key
drives Y to the apex then back to ground and lands
restores the ground offset it started from (not hard 0)
ignores a second press while airborne (no double-jump)
jump.request triggers a jump too
drives a followed Mesh via params.position[1], preferring it over the proxy
cleans up per-entity state when the entity leaves
a keyed jumper with no mesh or proxy runs without throwing
jump.request without an entityId jumps nobody

Last run 2026-07-17

Jump.test.ts

import { describe, it, expect, beforeEach } from 'vitest';
import { JumpComponent, JumpSystem, JumpEvents, JumpInputEvents } from './Jump';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.core';
import { MeshComponent } from '../Mesh/Mesh';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';

describe('Jump', () => {
  describe('component', () => {
    it('applies defaults', () => {
      const j = new JumpComponent();
      expect(j.key).toBe('Space');
      expect(j.height).toBe(1.6);
      expect(j.duration).toBe(0.7);
      expect(j.hang).toBe(0.35);
      expect(j.airborne).toBe(false);
    });

    it('clamps hang to [0, 0.9] and round-trips config', () => {
      expect(new JumpComponent({ hang: 5 }).hang).toBe(0.9);
      expect(new JumpComponent({ hang: -1 }).hang).toBe(0);
      const j = new JumpComponent({ key: 'KeyJ', height: 2, duration: 1, hang: 0.5 });
      expect(j.serialize()).toEqual({ key: 'KeyJ', height: 2, duration: 1, hang: 0.5 });
    });

    it('arc is 0 at the ends, 1 at the apex, and symmetric', () => {
      const j = new JumpComponent({ hang: 0.4 });
      expect(j.arc(0)).toBeCloseTo(0, 6);
      expect(j.arc(1)).toBeCloseTo(0, 6);
      expect(j.arc(0.5)).toBeCloseTo(1, 6);
      expect(j.arc(0.25)).toBeCloseTo(j.arc(0.75), 6); // mirror
    });
  });

  describe('system', () => {
    let eventBus: EventBus;
    let world: World;

    beforeEach(() => {
      eventBus = new EventBus();
      world = new World({ eventBus, renderer: new MockRendererAdapter() });
      world.addSystem(new JumpSystem(eventBus));
      world.initialize();
    });

    const makeJumper = (data: Record<string, unknown> = {}) => {
      const e = world.createEntity('Player');
      e.add(new MeshPrimitiveComponent({ primitive: 'capsule', position: [0, 0, 0] }));
      e.add(new JumpComponent({ duration: 1, height: 2, hang: 0, ...data }));
      return e;
    };

    it('leaves the ground on the jump key', () => {
      const e = makeJumper();
      eventBus.emitImmediate('keyboard.keydown', { code: 'Space' });
      expect(e.get(JumpComponent)!.airborne).toBe(true);
    });

    it('does not jump on a different key', () => {
      const e = makeJumper();
      eventBus.emitImmediate('keyboard.keydown', { code: 'KeyX' });
      expect(e.get(JumpComponent)!.airborne).toBe(false);
    });

    it('drives Y to the apex then back to ground and lands', () => {
      const e = makeJumper(); // duration 1, height 2, hang 0 → arc(0.5)=1
      const mp = e.get(MeshPrimitiveComponent)!;
      let landed = 0;
      eventBus.on(JumpEvents.LANDED, () => landed++);

      eventBus.emitImmediate('keyboard.keydown', { code: 'Space' });
      world.update(0.5); // p = 0.5 → y = height * 1 = 2
      expect(mp.position[1]).toBeCloseTo(2, 3);

      world.update(0.5); // p = 1 → land, restore ground
      expect(e.get(JumpComponent)!.airborne).toBe(false);
      expect(mp.position[1]).toBeCloseTo(0, 6);

      world.update(0); // flush the queued LANDED
      expect(landed).toBe(1);
    });

    it('restores the ground offset it started from (not hard 0)', () => {
      const e = world.createEntity('P2');
      const mp = new MeshPrimitiveComponent({ primitive: 'capsule', position: [0, 0.9, 0] });
      e.add(mp);
      e.add(new JumpComponent({ duration: 1, height: 2, hang: 0 }));
      eventBus.emitImmediate('keyboard.keydown', { code: 'Space' });
      world.update(0.5);
      expect(mp.position[1]).toBeCloseTo(0.9 + 2, 3); // apex above the starting height
      world.update(0.5);
      expect(mp.position[1]).toBeCloseTo(0.9, 6); // back to where it started
    });

    it('ignores a second press while airborne (no double-jump)', () => {
      const e = makeJumper();
      let starts = 0;
      eventBus.on(JumpEvents.STARTED, () => starts++);
      eventBus.emitImmediate('keyboard.keydown', { code: 'Space' });
      world.update(0.3);
      eventBus.emitImmediate('keyboard.keydown', { code: 'Space' }); // mid-air — ignored
      world.update(0); // flush queued STARTED(s)
      expect(starts).toBe(1);
      expect(e.get(JumpComponent)!.airborne).toBe(true);
    });

    it('jump.request triggers a jump too', () => {
      const e = makeJumper();
      eventBus.emitImmediate(JumpInputEvents.JUMP, { entityId: 'Player' });
      expect(e.get(JumpComponent)!.airborne).toBe(true);
    });

    it('drives a followed Mesh via params.position[1], preferring it over the proxy', () => {
      const e = world.createEntity('Figure');
      const mesh = new MeshComponent({ src: 'x.glb', position: [0, 0, 0], follow: true, autoLoad: false });
      e.add(mesh);
      const mp = new MeshPrimitiveComponent({ primitive: 'capsule', position: [0, 0.5, 0] });
      e.add(mp);
      e.add(new JumpComponent({ duration: 1, height: 2, hang: 0 }));

      eventBus.emitImmediate('keyboard.keydown', { code: 'Space' });
      world.update(0.5); // apex

      expect(mesh.params.position[1]).toBeCloseTo(2, 3); // the Mesh Y (what follow reads) rose
      expect(mp.position[1]).toBe(0.5); // the proxy (camera anchor) stayed grounded
      world.update(0.5);
      expect(mesh.params.position[1]).toBeCloseTo(0, 6); // restored
    });

    it('cleans up per-entity state when the entity leaves', () => {
      const e = makeJumper();
      eventBus.emitImmediate('keyboard.keydown', { code: 'Space' });
      world.removeEntity(e);
      expect(() => world.update(0.1)).not.toThrow();
    });

    it('a keyed jumper with no mesh or proxy runs without throwing', () => {
      const e = world.createEntity('Bare');
      e.add(new JumpComponent({ duration: 1 }));
      eventBus.emitImmediate('keyboard.keydown', { code: 'Space' });
      expect(() => world.update(0.5)).not.toThrow();
      expect(e.get(JumpComponent)!.airborne).toBe(true);
    });

    it('jump.request without an entityId jumps nobody', () => {
      const e = makeJumper();
      eventBus.emitImmediate(JumpInputEvents.JUMP, {});
      expect(e.get(JumpComponent)!.airborne).toBe(false);
    });
  });
});

Babylon.js Market

Jump

Jump

What it does

Use it in a scene

Props

Events

Dependencies

Notes

Jump.core.ts

Events

Component

Jump.ts

Jump.test.ts

Jump.test.ts

More like this

Was this page helpful?