Object3DBehaviour

Object3DBehaviour is the base class for all components. Extend it, override the lifecycle methods you need, and attach it to any Object3D via addComponent. The component hooks itself into the loop and the lifecycle automatically — the shared ThreeContext is available as this.ctx, and any registered ContextModule via this.modules.

import { Object3DBehaviour, addComponent } from "three-start";

class Spin extends Object3DBehaviour {
  onAwake() {
    // initialize
  }
  onUpdate() {
    this.object.rotation.y += this.ctx.getDeltaTime();
  }
  onDestroy() {
    // clean up
  }
}

addComponent(mesh, Spin);

First activation order: onAwake → onEnable → onStart

Enable/disable cycle: onEnable ↔ onDisable

On removal: onDisable → onDestroy

Properties

Methods

Override methods

These are the lifecycle hooks you implement in your subclass.

Events

Object3DBehaviour extends TypedEmitter — declare your own event map via the generic parameter to expose typed events on instances of your subclass.

Declaring events in your subclass

Pass a typed event map as the generic parameter. Keys become the event argument in on / off / once, and tuple values type the listener payload. emit is protected — only the component itself can fire its own events.

type HealthEvents = {
  damaged: [amount: number, source: string];
  died: [];
};

class Health extends Object3DBehaviour<HealthEvents> {
  hp = 100;

  takeDamage(n: number, by: string) {
    this.hp -= n;
    this.emit("damaged", n, by);          // ✅ inside the class
    if (this.hp <= 0) this.emit("died");  // ✅
  }
}

// Subscribe from outside:
const health = getComponent(player, Health)!;
health.on("damaged", (amount, by) => console.log(`-${amount} from ${by}`));
health.emit("damaged", 10, "x");          // ❌ compile error: emit is protected

The default for the generic is {} — without declaring events, calling on / emit fails at compile time (keyof {} = never).