14 — API Guide (runtime)

Feature inventory: 13 — Feature List · Behavior quick-start: LLM_SCRIPTING_CONTEXT.md · Scripting prose: 05 — Scripting · Input: 12 — Input

Reference for behavior authors and anyone reading runtime code. Import from @bjs/engine in app behavior files. This guide covers the kit’s public surface — not every Babylon.js API.

Quick example

import { Behavior, exposed, inputMap, type Entity } from "@bjs/engine";
import type { InputActionMap } from "@bjs/engine";
import { Vector3 } from "@babylonjs/core";

export default class Patrol extends Behavior
{
  @exposed({ min: 0, max: 10 }) speed = 2;
  @exposed({ type: "entity" }) target!: Entity;
  @inputMap("Player") player!: InputActionMap;

  OnStart(): void
  {
    // target is resolved before this runs
  }

  OnUpdate(deltaSeconds: number): void
  {
    const move = this.player.FindAction("Move")?.ReadVector2();
    if (move !== undefined)
    {
      this.node.position.addInPlace(new Vector3(move.x, 0, move.y).scale(this.speed * deltaSeconds));
    }
  }

  OnMessage(message: string, source: Entity): void
  {
    if (message === "Alert")
    {
      // react to trigger or GUI click from source
    }
  }
}

Behavior

Base class for all scripts. One export default class per file; filename stem = Blender registry key (Patrol.ts → "Patrol").

Lifecycle (PascalCase required)

Physics hooks are opt-in: override one and the engine enables the matching Havok callbacks automatically — no manual observable subscription. Both bodies in a solid contact receive collision hooks (Unity semantics); trigger hooks fire on the trigger entity's behaviors. Details: 06 — Physics › Collision lifecycle hooks.

Injected members

Scale continuous motion by deltaSeconds. Babylon velocities are already per-second — do not multiply those by deltaSeconds.

Entity

One Blender object that exported successfully. File: packages/engine/src/core/Entity.ts.

Fields

Methods

Level

Runtime container returned by LevelLoader.Load. File: packages/engine/src/core/Level.ts.

Fields (common)

Methods

Begin() and RunFrame() are called by the loader — behaviors do not call them.

Attachments

Each successfully applied component becomes one row on entity.attachments. Types match manifest component types plus GUI3D variants.

Convenience arrays on Entity (sounds, behaviors, …) mirror attachments for common access patterns.

@exposed (Blender-editable fields)

Decorator: exposed(options?) from @bjs/engine. Must stay lowercase — Blender regex-parses the token literally.

Defaults in source must be single-line literals so Blender’s parser can read them. After changing fields, press Sync on the SCRIPT component.

Input (@inputMap + polling)

See 12 — Input for authoring (stick vs 1D/2D composites, control type, gamepad labels, LT/RT as axis 4/5, axisHalf, disambiguation). In behaviors:

@inputMap("Player") player!: InputActionMap;  // named map
@inputMap("Vehicle") vehicle!: InputActionMap; // e.g. CarController

// Vector 2 action — Type: Value, Control Type: Vector 2 in Blender
const control = this.vehicle.FindAction("Main Control")?.ReadVector2() ?? { x: 0, y: 0 };
const throttle = control.y;
const steer = control.x;

InputActionMap

InputAction (polling)

InputAction (callbacks)

action.started.add(fn), action.performed.add(fn), action.canceled.add(fn) — same semantics as Unity Input System.

Global access (optional)

InputManager.actions · InputManager.FindAction("Player/Move") · InputManager.GetDefaultMap() — prefer @inputMap fields on behaviors.

BehaviorRegistry

Maps script name → class. Apps register before load:

const registry = new BehaviorRegistry();
const modules = import.meta.glob("./behaviors/*.{ts,js}", { eager: true });
AutoRegisterBehaviors(registry, modules);
const level = await new LevelLoader(scene, registry).Load(manifestUrl);

registry.Create("Patrol") is called internally for each SCRIPT row.

App bootstrap (not in behaviors)

Typical main.ts responsibilities — see 02 — Runtime Basics:

1. FetchAndValidateManifest(url) — optional; required before CreateLevelEngine when using large-world rendering
2. CreateLevelEngine(canvas, antialias, manifest)
3. new Scene(engine)
4. await EnableHavokPhysics(scene, …) — before Load
5. LevelLoader.Load(manifestUrl, manifest?, options?)
6. engine.runRenderLoop(() => scene.render())

LevelLoaderOptions

Physics (from behaviors)

When an entity has a body: this.entity.body is a Babylon PhysicsBody. Use Havok APIs for impulses, velocities, etc. Collider overlay: app debug key → level.ShowColliders() (when level.debugEnabled).

Messages

Authored Event Messages and 3D GUI buttons call targetEntity.SendMessage(message, sourceEntity). Every behavior on the target gets OnMessage(message, source). Use the same string names you authored in Blender event rows.

Related exports

@bjs/engine also re-exports manifest types (core/types.ts), subsystem helpers (physics, lights, …), and UI loaders — mainly for app code and advanced scripts. Behavior authors usually need Behavior, exposed, inputMap, and Babylon types only.