Health.defs.ts

Health — definitions.

Holds the HealthComponent class, its event dictionary and the shapes its data and events travel in. No System lives here, which is the point: another component can name Health in a query, or type an event it listens for, without pulling Health's behaviour into its own bundle. Import from here, not from Health.ts.

Health.defs.ts

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

export interface HealthInput {
  hp?: number
  maxHp?: number
  /** Post-damage grace period in seconds. 0 = no i-frames. */
  invulnSeconds?: number
  /** If set, entity teleports here + restores full HP when HP hits 0. */
  respawnPosition?: [number, number, number]
}

export class HealthComponent extends Component {
  hp: number
  maxHp: number
  invulnSeconds: number
  respawnPosition: [number, number, number] | null

  /** Wall-clock ms (performance.now) until which damage is ignored. */
  invulnUntil = 0

  constructor(data: HealthInput = {}) {
    super()
    this.hp = data.hp ?? 10
    this.maxHp = data.maxHp ?? this.hp
    this.invulnSeconds = data.invulnSeconds ?? 0
    this.respawnPosition = data.respawnPosition ?? null
  }

  serialize(): HealthInput {
    return {
      hp: this.hp,
      maxHp: this.maxHp,
      invulnSeconds: this.invulnSeconds,
      respawnPosition: this.respawnPosition ?? undefined,
    }
  }
}

export const HealthEvents = {
  /** Fired after HP changes (damage absorbed or healed). */
  DAMAGED: 'health.damaged',
  HEALED: 'health.healed',
  /** Fired the frame HP first hits 0, BEFORE any respawn happens. */
  DIED: 'health.died',
  /** Fired when a respawn-configured entity has been reset to full HP. */
  RESPAWNED: 'health.respawned',
} as const

export const HealthInputEvents = {
  /** Payload: { entityId: string, damage: number }. */
  DAMAGE: 'health.damage',
  /** Payload: { entityId: string, amount: number }. */
  HEAL: 'health.heal',
} as const

export interface HealthDamageRequest {
  entityId: string
  damage: number
}

export interface HealthHealRequest {
  entityId: string
  amount: number
}

Health.ts

Health.ts — renderer-agnostic System.

The core (Health.core.ts) owns the HealthComponent, event-name constants (HealthEvents, HealthInputEvents), and request-payload interfaces (HealthDamageRequest, HealthHealRequest). This System listens for the input events, mutates HP, emits the output events, and (for respawn-configured entities) snaps the host's MeshPrimitive back to the configured spawn point with full HP.

Health.ts

import { System } from '@babylonjsmarket/ecs'
import type { EventBus, Entity } from '@babylonjsmarket/ecs'
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import {
  HealthComponent,
  HealthEvents,
  HealthInputEvents,
  type HealthDamageRequest,
  type HealthHealRequest,
  type HealthInput,
} from './Health.defs'

export class HealthSystem extends System {
  protected query = { required: [HealthComponent] }

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

  protected onInitialize(): void {
    this.listen(HealthInputEvents.DAMAGE, (req: HealthDamageRequest) => {
      this.applyDamage(req)
    })
    this.listen(HealthInputEvents.HEAL, (req: HealthHealRequest) => {
      this.applyHeal(req)
    })
  }

  protected onUpdate(_dt: number): void {
    /* event-driven */
  }

  private applyDamage(req: HealthDamageRequest): void {
    const ent = this.world?.getEntity(req.entityId)
    if (!ent) return
    const h = ent.get(HealthComponent)
    if (!h || h.hp <= 0 || req.damage <= 0) return
    const now = typeof performance !== 'undefined' ? performance.now() : Date.now()
    if (now < h.invulnUntil) return

    h.hp = Math.max(0, h.hp - req.damage)
    if (h.invulnSeconds > 0) h.invulnUntil = now + h.invulnSeconds * 1000
    this.eventBus.emit(HealthEvents.DAMAGED, {
      entityId: req.entityId,
      hp: h.hp,
      maxHp: h.maxHp,
      damage: req.damage,
    })

    if (h.hp <= 0) {
      this.eventBus.emit(HealthEvents.DIED, { entityId: req.entityId })
      if (h.respawnPosition) this.respawn(ent, h)
    }
  }

  private applyHeal(req: HealthHealRequest): void {
    const ent = this.world?.getEntity(req.entityId)
    if (!ent) return
    const h = ent.get(HealthComponent)
    if (!h || req.amount <= 0) return
    if (h.hp >= h.maxHp) return
    h.hp = Math.min(h.maxHp, h.hp + req.amount)
    this.eventBus.emit(HealthEvents.HEALED, {
      entityId: req.entityId,
      hp: h.hp,
      maxHp: h.maxHp,
      amount: req.amount,
    })
  }

  private respawn(entity: Entity, h: HealthComponent): void {
    if (!h.respawnPosition) return
    // Set the position DATA only — the entity's transform owner (for the player,
    // TwinStickShooter, which commits every frame) pushes it to the renderer.
    // Calling setMeshPosition here too would make HealthSystem a second writer
    // of the same mesh handle in one frame, racing that owner on the death
    // frame (the flicker the RaceDetector flags). Respawn is only used by the
    // player, which has such an owner.
    const mesh = entity.get(MeshPrimitiveComponent)
    if (mesh) {
      mesh.position[0] = h.respawnPosition[0]
      mesh.position[1] = h.respawnPosition[1]
      mesh.position[2] = h.respawnPosition[2]
    }
    h.hp = h.maxHp
    // Brief grace after respawn so a clump of enemies doesn't insta-kill again.
    const now = typeof performance !== 'undefined' ? performance.now() : Date.now()
    h.invulnUntil = now + Math.max(h.invulnSeconds, 1.0) * 1000
    this.eventBus.emit(HealthEvents.RESPAWNED, {
      entityId: entity.id,
      hp: h.hp,
      maxHp: h.maxHp,
    })
  }
}

export {
  HealthComponent,
  HealthEvents,
  HealthInputEvents,
  type HealthDamageRequest,
  type HealthHealRequest,
  type HealthInput,
} from './Health.defs'

Health.contract.test.ts

13 ✓

ArcadeECS contract: Health

Component() with no args constructs and applies defaults
Component merges sample input on top of defaults
Component.serialize() round-trips into a constructor input
System constructor signature is exactly (eventBus)
System declares a non-empty query.required
world.addSystem + initialize + update runs clean with no entity
adding the Component attaches the entity to the System
world.update(dt) does not throw with the entity attached
Adapter handles: create/dispose balance across entity lifecycle
EventBus has no lingering listeners after world.destroy()
Declared event names follow the "{domain}.{action}" convention
Emits at least one declared output event during an update
Registers a listener for each declared input event

Last run 2026-08-22

Health.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import type { MechanicContractContext } from '@babylonjsmarket/ecs/testing';
import {
  HealthComponent,
  HealthSystem,
  HealthEvents,
  HealthInputEvents,
} from './Health';

/**
 * HealthSystem routes its inputs by `entityId`. The contract battery mints
 * a fresh entity inside `buildWorld`; we latch onto `world.entity.created`
 * so `makeInputPayload` always references the most recent one.
 */
let latestEntityId = 'contract-test';

runMechanicContract({
  name: 'Health',
  componentClass: HealthComponent,
  systemClass: HealthSystem,
  sampleInput: { hp: 5, maxHp: 5 },
  events: {
    input: [HealthInputEvents.DAMAGE, HealthInputEvents.HEAL],
    output: [
      HealthEvents.DAMAGED,
      HealthEvents.HEALED,
      HealthEvents.DIED,
      HealthEvents.RESPAWNED,
    ],
  },
  setup(ctx: MechanicContractContext) {
    ctx.eventBus.on('world.entity.created', (e: { entity: { id: string } }) => {
      latestEntityId = e.entity.id;
    });
  },
  makeInputPayload(event) {
    if (event === HealthInputEvents.DAMAGE) {
      return { entityId: latestEntityId, damage: 1 };
    }
    if (event === HealthInputEvents.HEAL) {
      return { entityId: latestEntityId, amount: 1 };
    }
    return {};
  },
});

Health.defs.test.ts

8 ✓

HealthComponent

applies defaults
defaults maxHp to hp when hp alone is supplied
merges input on top of defaults
respawnPosition round-trips through serialize()
serialize round-trips with all fields set
serialize omits respawnPosition when none was set
exposes the documented HealthEvents / HealthInputEvents constants
HealthDamageRequest / HealthHealRequest interfaces match the documented shape

Last run 2026-08-22

Health.defs.test.ts

import { describe, it, expect } from 'vitest';
import {
  HealthComponent,
  HealthEvents,
  HealthInputEvents,
  type HealthDamageRequest,
  type HealthHealRequest,
} from './Health.defs';

describe('HealthComponent', () => {
  it('applies defaults', () => {
    const c = new HealthComponent();
    expect(c.hp).toBe(10);
    expect(c.maxHp).toBe(10);
    expect(c.invulnSeconds).toBe(0);
    expect(c.respawnPosition).toBeNull();
    expect(c.invulnUntil).toBe(0);
  });

  it('defaults maxHp to hp when hp alone is supplied', () => {
    const c = new HealthComponent({ hp: 3 });
    expect(c.hp).toBe(3);
    expect(c.maxHp).toBe(3);
  });

  it('merges input on top of defaults', () => {
    const c = new HealthComponent({
      hp: 5,
      maxHp: 8,
      invulnSeconds: 0.5,
    });
    expect(c.hp).toBe(5);
    expect(c.maxHp).toBe(8);
    expect(c.invulnSeconds).toBe(0.5);
    expect(c.respawnPosition).toBeNull();
  });

  it('respawnPosition round-trips through serialize()', () => {
    const a = new HealthComponent({ respawnPosition: [1, 2, 3] });
    expect(a.respawnPosition).toEqual([1, 2, 3]);
    const b = new HealthComponent(a.serialize());
    expect(b.respawnPosition).toEqual([1, 2, 3]);
    expect(b.serialize()).toEqual(a.serialize());
  });

  it('serialize round-trips with all fields set', () => {
    const a = new HealthComponent({
      hp: 4,
      maxHp: 9,
      invulnSeconds: 0.75,
      respawnPosition: [0, 1, -2],
    });
    const b = new HealthComponent(a.serialize());
    expect(b.serialize()).toEqual(a.serialize());
    expect(b.hp).toBe(a.hp);
    expect(b.maxHp).toBe(a.maxHp);
    expect(b.invulnSeconds).toBe(a.invulnSeconds);
    expect(b.respawnPosition).toEqual(a.respawnPosition);
  });

  it('serialize omits respawnPosition when none was set', () => {
    const a = new HealthComponent({ hp: 6 });
    const payload = a.serialize();
    expect(payload.respawnPosition).toBeUndefined();
  });

  it('exposes the documented HealthEvents / HealthInputEvents constants', () => {
    expect(HealthEvents.DAMAGED).toBe('health.damaged');
    expect(HealthEvents.HEALED).toBe('health.healed');
    expect(HealthEvents.DIED).toBe('health.died');
    expect(HealthEvents.RESPAWNED).toBe('health.respawned');
    expect(HealthInputEvents.DAMAGE).toBe('health.damage');
    expect(HealthInputEvents.HEAL).toBe('health.heal');
  });

  it('HealthDamageRequest / HealthHealRequest interfaces match the documented shape', () => {
    // Pure type-shape check — if these interfaces drift, the assignment
    // below stops compiling and `npm run build` catches it.
    const dmg: HealthDamageRequest = { entityId: 'e1', damage: 2 };
    const heal: HealthHealRequest = { entityId: 'e1', amount: 3 };
    expect(dmg.entityId).toBe('e1');
    expect(dmg.damage).toBe(2);
    expect(heal.entityId).toBe('e1');
    expect(heal.amount).toBe(3);
  });
});

Health.test.ts

16 ✓

HealthSystem

applies damage and emits DAMAGED
clamps hp at 0 and emits DIED (no respawn when unconfigured)
ignores damage on an unknown entity
ignores damage when the entity has no HealthComponent
ignores damage once already dead (hp <= 0)
ignores non-positive damage
sets invulnUntil after a hit and blocks damage during the window
heals and emits HEALED
clamps heal at maxHp
ignores heal on unknown entity
ignores heal when entity has no HealthComponent
ignores non-positive heal amount
ignores heal when already at full hp
respawns on death: snaps mesh position, restores hp, grace invuln, RESPAWNED
respawns even without a MeshPrimitive (no mesh write, still restores hp)
respawn grace honours a larger invulnSeconds

Last run 2026-08-22

Health.test.ts

import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import {
  HealthComponent,
  HealthSystem,
  HealthEvents,
  HealthInputEvents,
} from './Health';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';

describe('HealthSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let damaged: Array<{ entityId: string; hp: number; maxHp: number; damage: number }>;
  let healed: Array<{ entityId: string; hp: number; maxHp: number; amount: number }>;
  let died: Array<{ entityId: string }>;
  let respawned: Array<{ entityId: string; hp: number; maxHp: number }>;

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer });
    world.addSystem(new HealthSystem(eventBus));
    world.initialize();
    damaged = [];
    healed = [];
    died = [];
    respawned = [];
    eventBus.on(HealthEvents.DAMAGED, (d) => damaged.push(d as never));
    eventBus.on(HealthEvents.HEALED, (d) => healed.push(d as never));
    eventBus.on(HealthEvents.DIED, (d) => died.push(d as never));
    eventBus.on(HealthEvents.RESPAWNED, (d) => respawned.push(d as never));
  });

  function makeEntity(opts: Record<string, unknown> = {}, withMesh = false) {
    const e = world.createEntity();
    if (withMesh) {
      e.add(new MeshPrimitiveComponent({ primitive: 'capsule', position: [0, 0, 0] }));
    }
    e.add(new HealthComponent({ hp: 5, maxHp: 5, ...opts }));
    return e;
  }

  // ── damage ────────────────────────────────────────────────────────────
  it('applies damage and emits DAMAGED', () => {
    const e = makeEntity();
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 2 });
    expect(e.get(HealthComponent)!.hp).toBe(3);
    expect(damaged).toHaveLength(1);
    expect(damaged[0]).toEqual({ entityId: e.id, hp: 3, maxHp: 5, damage: 2 });
    expect(died).toHaveLength(0);
  });

  it('clamps hp at 0 and emits DIED (no respawn when unconfigured)', () => {
    const e = makeEntity();
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 99 });
    expect(e.get(HealthComponent)!.hp).toBe(0);
    expect(damaged[0].hp).toBe(0);
    expect(died).toEqual([{ entityId: e.id }]);
    expect(respawned).toHaveLength(0);
  });

  it('ignores damage on an unknown entity', () => {
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: 'nope', damage: 1 });
    expect(damaged).toHaveLength(0);
  });

  it('ignores damage when the entity has no HealthComponent', () => {
    const e = world.createEntity();
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 1 });
    expect(damaged).toHaveLength(0);
  });

  it('ignores damage once already dead (hp <= 0)', () => {
    const e = makeEntity();
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 99 });
    expect(died).toHaveLength(1);
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 1 });
    // No second DAMAGED / DIED.
    expect(damaged).toHaveLength(1);
    expect(died).toHaveLength(1);
  });

  it('ignores non-positive damage', () => {
    const e = makeEntity();
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 0 });
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: -3 });
    expect(damaged).toHaveLength(0);
    expect(e.get(HealthComponent)!.hp).toBe(5);
  });

  // ── invulnerability ───────────────────────────────────────────────────
  it('sets invulnUntil after a hit and blocks damage during the window', () => {
    vi.spyOn(performance, 'now').mockReturnValue(1000);
    const e = makeEntity({ invulnSeconds: 0.5 });
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 1 });
    const h = e.get(HealthComponent)!;
    expect(h.hp).toBe(4);
    expect(h.invulnUntil).toBe(1000 + 500);

    // Still inside the window → blocked.
    vi.spyOn(performance, 'now').mockReturnValue(1200);
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 1 });
    expect(h.hp).toBe(4);
    expect(damaged).toHaveLength(1);

    // After the window → lands again.
    vi.spyOn(performance, 'now').mockReturnValue(2000);
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 1 });
    expect(h.hp).toBe(3);
    expect(damaged).toHaveLength(2);
  });

  // ── heal ──────────────────────────────────────────────────────────────
  it('heals and emits HEALED', () => {
    const e = makeEntity({ hp: 2, maxHp: 5 });
    eventBus.emit(HealthInputEvents.HEAL, { entityId: e.id, amount: 2 });
    expect(e.get(HealthComponent)!.hp).toBe(4);
    expect(healed).toEqual([{ entityId: e.id, hp: 4, maxHp: 5, amount: 2 }]);
  });

  it('clamps heal at maxHp', () => {
    const e = makeEntity({ hp: 4, maxHp: 5 });
    eventBus.emit(HealthInputEvents.HEAL, { entityId: e.id, amount: 10 });
    expect(e.get(HealthComponent)!.hp).toBe(5);
    expect(healed[0].hp).toBe(5);
  });

  it('ignores heal on unknown entity', () => {
    eventBus.emit(HealthInputEvents.HEAL, { entityId: 'nope', amount: 1 });
    expect(healed).toHaveLength(0);
  });

  it('ignores heal when entity has no HealthComponent', () => {
    const e = world.createEntity();
    eventBus.emit(HealthInputEvents.HEAL, { entityId: e.id, amount: 1 });
    expect(healed).toHaveLength(0);
  });

  it('ignores non-positive heal amount', () => {
    const e = makeEntity({ hp: 2, maxHp: 5 });
    eventBus.emit(HealthInputEvents.HEAL, { entityId: e.id, amount: 0 });
    eventBus.emit(HealthInputEvents.HEAL, { entityId: e.id, amount: -1 });
    expect(healed).toHaveLength(0);
  });

  it('ignores heal when already at full hp', () => {
    const e = makeEntity({ hp: 5, maxHp: 5 });
    eventBus.emit(HealthInputEvents.HEAL, { entityId: e.id, amount: 1 });
    expect(healed).toHaveLength(0);
    expect(e.get(HealthComponent)!.hp).toBe(5);
  });

  // ── respawn ───────────────────────────────────────────────────────────
  it('respawns on death: snaps mesh position, restores hp, grace invuln, RESPAWNED', () => {
    vi.spyOn(performance, 'now').mockReturnValue(5000);
    const e = makeEntity(
      { hp: 5, maxHp: 5, respawnPosition: [7, 8, 9], invulnSeconds: 0.25 },
      true,
    );
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 99 });

    const h = e.get(HealthComponent)!;
    expect(died).toEqual([{ entityId: e.id }]);
    expect(h.hp).toBe(5); // restored to maxHp
    const mesh = e.get(MeshPrimitiveComponent)!;
    expect(mesh.position).toEqual([7, 8, 9]);
    // Grace window is max(invulnSeconds, 1.0) → 1s here.
    expect(h.invulnUntil).toBe(5000 + 1000);
    expect(respawned).toEqual([{ entityId: e.id, hp: 5, maxHp: 5 }]);
  });

  it('respawns even without a MeshPrimitive (no mesh write, still restores hp)', () => {
    vi.spyOn(performance, 'now').mockReturnValue(0);
    const e = makeEntity({ hp: 5, maxHp: 5, respawnPosition: [1, 2, 3] });
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 99 });
    const h = e.get(HealthComponent)!;
    expect(h.hp).toBe(5);
    expect(respawned).toHaveLength(1);
    // Grace uses max(invulnSeconds=0, 1.0) = 1s.
    expect(h.invulnUntil).toBe(1000);
  });

  it('respawn grace honours a larger invulnSeconds', () => {
    vi.spyOn(performance, 'now').mockReturnValue(100);
    const e = makeEntity({ hp: 5, maxHp: 5, respawnPosition: [0, 0, 0], invulnSeconds: 3 });
    eventBus.emit(HealthInputEvents.DAMAGE, { entityId: e.id, damage: 99 });
    const h = e.get(HealthComponent)!;
    expect(h.invulnUntil).toBe(100 + 3000);
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });
});