@babylonjsmarket/arcade 0.3.11 → 0.3.12

package/src/Components/Bullet/Bullet.test.ts

@@ -0,0 +1,223 @@
+/**
+ * BulletSystem flight + collision tests. Bullets are normally pooled, but the
+ * System only needs live entities carrying a BulletComponent + MeshPrimitive,
+ * so these wire them directly and drive `world.update` to exercise the per-frame
+ * integration, lifetime/arena expiry, wall blocking, and enemy-hit path.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
+import { BulletComponent, BulletSystem, BulletEvents } from './Bullet';
+import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.core';
+import { HealthInputEvents } from '../Health/Health';
+import { ObstacleComponent } from '../Obstacle/Obstacle.core';
+
+describe('BulletSystem', () => {
+  let eventBus: EventBus;
+  let world: World;
+  let renderer: MockRendererAdapter;
+
+  beforeEach(() => {
+    eventBus = new EventBus();
+    renderer = new MockRendererAdapter();
+    world = new World({ eventBus, renderer, detectRaces: false });
+    world.addSystem(new BulletSystem(eventBus));
+    world.initialize();
+  });
+
+  function makeBullet(pos: [number, number, number], extra: Record<string, unknown> = {}) {
+    const entity = world.createEntity();
+    const mesh = new MeshPrimitiveComponent({ primitive: 'sphere', diameter: 0.3, position: pos });
+    mesh.handle = renderer.createMesh(entity.id, mesh.toPrimitiveSpec());
+    entity.add(mesh);
+    entity.add(new BulletComponent({ direction: [1, 0, 0], speed: 10, lifetime: 1.2, ...extra }));
+    return entity;
+  }
+
+  function makeEnemy(pos: [number, number, number], diameter = 1.2) {
+    const entity = world.createEntity();
+    const mesh = new MeshPrimitiveComponent({ primitive: 'sphere', diameter, position: pos });
+    mesh.handle = renderer.createMesh(entity.id, mesh.toPrimitiveSpec());
+    entity.add(mesh);
+    entity.addTag('enemy');
+    return entity;
+  }
+
+  function makeWall(pos: [number, number, number], halfWidth: number, halfDepth: number, blocksBullets: boolean) {
+    const entity = world.createEntity();
+    entity.add(new MeshPrimitiveComponent({ primitive: 'box', position: pos }));
+    entity.add(new ObstacleComponent({ halfWidth, halfDepth, blocksBullets, blocksSight: blocksBullets }));
+    entity.addTag('obstacle');
+    return entity;
+  }
+
+  // A freshly-added bullet is a "newborn" skipped exactly once, so burn a frame.
+  function warmup() {
+    world.update(0.016);
+  }
+
+  it('advances a live bullet along its direction and commits the position', () => {
+    const bullet = makeBullet([0, 0.5, 0]);
+    warmup();
+    world.update(0.1); // 10 u/s * 0.1 = +1 in X
+
+    const m = bullet.get(MeshPrimitiveComponent)!;
+    expect(m.position[0]).toBeCloseTo(1, 5);
+    const committed = renderer.calls.some(
+      (c) => c.method === 'setMeshPosition' && c.args[0] === m.handle,
+    );
+    expect(committed).toBe(true);
+  });
+
+  it('expires a bullet once its lifetime runs out (released)', () => {
+    const bullet = makeBullet([0, 0.5, 0], { lifetime: 0.05, speed: 0 });
+    const id = bullet.id;
+    warmup();
+    world.update(0.1); // lifetime 0.05 - 0.1 <= 0 → expired → removed
+
+    expect(world.getEntity(id)).toBeUndefined();
+  });
+
+  it('expires a bullet that leaves the arena bounds', () => {
+    const bullet = makeBullet([0.9, 0.5, 0], {
+      arenaHalfWidth: 1,
+      arenaHalfDepth: 1,
+      speed: 10,
+      direction: [1, 0, 0],
+    });
+    const id = bullet.id;
+    warmup();
+    world.update(0.1); // x → 1.9 > arenaHalfWidth 1 → out of bounds → expired
+
+    expect(world.getEntity(id)).toBeUndefined();
+  });
+
+  it('expires a bullet that leaves the arena along the depth (Z) axis', () => {
+    const bullet = makeBullet([0, 0.5, 0.9], {
+      arenaHalfWidth: 1,
+      arenaHalfDepth: 1,
+      speed: 10,
+      direction: [0, 0, 1],
+    });
+    const id = bullet.id;
+    warmup();
+    world.update(0.1); // z → 1.9 > arenaHalfDepth 1 → out of bounds → expired
+
+    expect(world.getEntity(id)).toBeUndefined();
+  });
+
+  it('skips an enemy that has no MeshPrimitive when testing hits', () => {
+    // An enemy-tagged entity with no mesh must be skipped (the `!em` guard),
+    // and a normal enemy behind it still gets hit.
+    const ghost = world.createEntity();
+    ghost.addTag('enemy'); // no MeshPrimitive
+    const enemy = makeEnemy([1, 0.5, 0]);
+    const bullet = makeBullet([0.5, 0.5, 0], { speed: 5, direction: [1, 0, 0] });
+    let hits = 0;
+    eventBus.on(BulletEvents.HIT, () => hits++);
+    warmup();
+    world.update(0.1); // x: 0.5 → 1.0, lands on the real enemy
+
+    expect(hits).toBe(1);
+    void ghost;
+    void enemy;
+  });
+
+  it('stops at a full-height wall, shielding enemies behind it', () => {
+    // Wall straddling x=2; an enemy behind it at x=5. The bullet should be
+    // expired on the wall crossing before it can hit the enemy.
+    makeWall([2, 0.5, 0], 0.5, 2, true);
+    const enemy = makeEnemy([5, 0.5, 0]);
+    const bullet = makeBullet([0, 0.5, 0], { speed: 40, direction: [1, 0, 0] });
+    const id = bullet.id;
+    let damaged = false;
+    eventBus.on(HealthInputEvents.DAMAGE, () => (damaged = true));
+    warmup();
+    world.update(0.1); // x travels 0 → 4, crossing the wall segment at x≈1.5..2.5
+
+    expect(world.getEntity(id)).toBeUndefined(); // stopped by the wall
+    expect(damaged).toBe(false); // enemy behind it was shielded
+    void enemy;
+  });
+
+  it('passes through low cover that does not block bullets', () => {
+    // blocksBullets:false → the wall is filtered out of bulletWalls, so the
+    // bullet flies through and hits the enemy beyond it.
+    makeWall([2, 0.5, 0], 0.5, 2, false);
+    const enemy = makeEnemy([3, 0.5, 0]);
+    // Land the bullet exactly on the enemy this frame (speed*dt = 3) — the hit
+    // test is a point overlap at the bullet's committed position.
+    const bullet = makeBullet([0, 0.5, 0], { speed: 30, direction: [1, 0, 0] });
+    const hits: unknown[] = [];
+    eventBus.on(BulletEvents.HIT, (d) => hits.push(d));
+    warmup();
+    world.update(0.1); // x: 0 → 3, lands on the enemy past the low cover
+
+    expect(hits.length).toBe(1);
+    void enemy;
+  });
+
+  it('emits HIT (with shot direction) then DAMAGE on enemy overlap, and expires', () => {
+    const enemy = makeEnemy([1, 0.5, 0]);
+    const bullet = makeBullet([0.5, 0.5, 0], { speed: 10, direction: [1, 0, 0], damage: 3 });
+    const id = bullet.id;
+    const order: string[] = [];
+    let hit: Record<string, unknown> | undefined;
+    eventBus.on(BulletEvents.HIT, (d: Record<string, unknown>) => {
+      order.push('hit');
+      hit = d;
+    });
+    let damage: Record<string, unknown> | undefined;
+    eventBus.on(HealthInputEvents.DAMAGE, (d: Record<string, unknown>) => {
+      order.push('damage');
+      damage = d;
+    });
+    warmup();
+    world.update(0.1); // x: 0.5 → 1.5, sweeps onto the enemy at x=1
+
+    expect(order).toEqual(['hit', 'damage']); // HIT before DAMAGE
+    expect(hit).toMatchObject({ entityId: enemy.id, damage: 3, dirX: 1, dirZ: 0 });
+    expect(damage).toMatchObject({ entityId: enemy.id, damage: 3 });
+    expect(world.getEntity(id)).toBeUndefined(); // bullet consumed on hit
+  });
+
+  it('ignores parked and dying enemies (no hit on a corpse)', () => {
+    const parked = makeEnemy([1, 0.5, 0]);
+    parked.active = false; // pooled / inactive
+    const dying = makeEnemy([1, 0.5, 1]);
+    dying.addTag('dying');
+    const bullet = makeBullet([0.8, 0.5, 0.5], { speed: 4, direction: [0, 0, 0] });
+    let hits = 0;
+    eventBus.on(BulletEvents.HIT, () => hits++);
+    warmup();
+    world.update(0.1);
+
+    // Neither the parked nor the dying enemy can be hit.
+    expect(hits).toBe(0);
+    void parked;
+    void dying;
+  });
+
+  it('uses a fallback hit radius when the enemy mesh has no diameter', () => {
+    // diameter 0 → the system falls back to 0.6, widening the hit test.
+    const enemy = makeEnemy([1.4, 0.5, 0], 0);
+    const bullet = makeBullet([1, 0.5, 0], { speed: 0, direction: [1, 0, 0] });
+    let hits = 0;
+    eventBus.on(BulletEvents.HIT, () => hits++);
+    warmup();
+    world.update(0.1);
+    // dist 0.4 <= radius(0.3)+fallback(0.6)=0.9 → hit.
+    expect(hits).toBe(1);
+    void enemy;
+  });
+
+  it('skips bullets with no mesh handle', () => {
+    const entity = world.createEntity();
+    const mesh = new MeshPrimitiveComponent({ primitive: 'sphere', diameter: 0.3 });
+    // No handle assigned → the per-bullet guard skips it.
+    entity.add(mesh);
+    entity.add(new BulletComponent({ direction: [1, 0, 0], speed: 10 }));
+    warmup();
+    // Should not throw; the handle-less bullet is simply skipped.
+    expect(() => world.update(0.1)).not.toThrow();
+  });
+});

package/src/Components/BulletPool/BulletPool.test.ts

@@ -7,7 +7,7 @@ import {
   BulletPoolInputEvents,
 } from './BulletPool';
 import { BulletComponent } from '../Bullet/Bullet';
-import { MeshPrimitiveSystem } from '../MeshPrimitive/MeshPrimitive';
+import { MeshPrimitiveComponent, MeshPrimitiveSystem } from '../MeshPrimitive/MeshPrimitive';
 
 describe('BulletPoolComponent', () => {
   it('applies defaults', () => {
@@ -105,6 +105,55 @@ describe('BulletPoolSystem (World pool)', () => {
     expect(placed).toBe(true);
   });
 
+  it('applies a per-shot color override to the reused bullet mesh', () => {
+    makePool(4);
+    eventBus.emit(BulletPoolInputEvents.FIRE, { x: 0, y: 1, z: 0, dz: 1, color: [0.2, 0.4, 0.6] });
+
+    const bullet = live()[0]!;
+    const handle = bullet.get(MeshPrimitiveComponent)!.handle;
+    const colored = renderer.calls.some(
+      (c) =>
+        c.method === 'setMeshColor' &&
+        c.args[0] === handle &&
+        c.args[1] === 0.2 &&
+        c.args[2] === 0.4 &&
+        c.args[3] === 0.6,
+    );
+    expect(colored).toBe(true);
+  });
+
+  it('ignores FIRE before the pool has registered (guarded)', () => {
+    // No pool entity created yet → registered stays false.
+    eventBus.emit(BulletPoolInputEvents.FIRE, { x: 0, y: 1, z: 0, dz: 1 });
+    expect(allBullets().length).toBe(0);
+  });
+
+  it('FIRE is a no-op when the pool is exhausted (all slots live)', () => {
+    makePool(1);
+    eventBus.emit(BulletPoolInputEvents.FIRE, { x: 0, y: 1, z: 0, dz: 1 });
+    expect(live().length).toBe(1);
+    // A second shot recycles the oldest slot rather than allocating — still 1 live.
+    eventBus.emit(BulletPoolInputEvents.FIRE, { x: 5, y: 1, z: 0, dz: 1 });
+    expect(live().length).toBe(1);
+    expect(allBullets().length).toBe(1);
+  });
+
+  it('FIRE is a no-op for a zero-size pool (acquire returns nothing)', () => {
+    const entity = world.createEntity('Pool');
+    entity.add(new BulletPoolComponent({ poolSize: 0 }));
+    world.update(1 / 60); // registers an empty pool
+    eventBus.emit(BulletPoolInputEvents.FIRE, { x: 0, y: 1, z: 0, dz: 1 });
+    expect(live().length).toBe(0); // nothing to hand out → guarded
+  });
+
+  it('does not re-register the pool on a second tick', () => {
+    const ready = vi.fn();
+    eventBus.on(BulletPoolEvents.READY, ready);
+    makePool(2); // first tick registers + emits READY
+    world.update(1 / 60); // second tick: early-return on `registered`
+    expect(ready).toHaveBeenCalledTimes(1);
+  });
+
   it('removeEntity releases a fired bullet back to the pool (parked, reused)', () => {
     makePool(2);
     eventBus.emit(BulletPoolInputEvents.FIRE, { x: 0, y: 1, z: 0, dz: 1 });

package/src/Components/Bumper/Bumper.test.ts

@@ -109,4 +109,22 @@ describe('BumperSystem', () => {
     world.update(0.016);
     expect(hits).toHaveLength(1);
   });
+
+  it('skips a ball-tagged entity with no MeshPrimitiveComponent, still firing for a real ball', () => {
+    // branch 67: getEntitiesByTag('ball') returns the bare entity, but
+    // testBall bails (`if (!pm) return`). The real ball still scores.
+    makeBumper([0, 0, 0], { points: 100, ownerEntity: 'Player' });
+    const bare = world.createEntity();
+    bare.addTag('ball'); // tagged but no mesh
+    makeBall([0.5, 0, 0]); // real ball, inside the hit radius
+    world.update(0.016);
+    expect(hits).toHaveLength(1);
+    expect(hits[0].ballId).not.toBe(bare.id);
+    expect(scores).toEqual([{ ownerEntity: 'Player', points: 100 }]);
+  });
+
+  // Deliberately uncovered (defensive, unreachable here):
+  //   - line 48 `if (!w) return`          — world is always set on the system.
+  //   - line 55 `if (!b || !bm) continue` — the query guarantees both
+  //                                          BumperComponent + MeshPrimitive.
 });

package/src/Components/CameraFollow/CameraFollow.core.test.ts

@@ -73,4 +73,23 @@ describe('CameraFollow core', () => {
     const f = createCameraFollow();
     expect(f.getParams()).toEqual(DEFAULT_CAMERA_FOLLOW_PARAMS);
   });
+
+  it('reset() with no argument snaps back to the origin', () => {
+    const f = createCameraFollow({ smoothing: 100, offsetY: 0 }, { camX: 9, camY: 9, camZ: 9 });
+    f.reset();
+    const out = f.update({ targetX: 50, targetY: 50, targetZ: 50 }, 0);
+    expect(out.camX).toBe(0);
+    expect(out.camY).toBe(0);
+    expect(out.camZ).toBe(0);
+  });
+
+  it('reset() falls back to 0 for any axis omitted from the supplied position', () => {
+    const f = createCameraFollow({ smoothing: 100, offsetY: 0 }, { camX: 9, camY: 9, camZ: 9 });
+    // Only camX given; camY/camZ should default to 0.
+    f.reset({ camX: 7 } as { camX: number; camY: number; camZ: number });
+    const out = f.update({ targetX: 0, targetY: 0, targetZ: 0 }, 0);
+    expect(out.camX).toBe(7);
+    expect(out.camY).toBe(0);
+    expect(out.camZ).toBe(0);
+  });
 });

package/src/Components/CameraFollow/CameraFollow.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'vitest';
 import { CameraFollowComponent, CameraFollowSystem } from './CameraFollow';
 import { ArcCameraComponent } from '../ArcCamera/ArcCamera';
 import { getArcCameraRuntime } from '../ArcCamera/ArcCamera.core';
+import { MeshPrimitiveSystem, MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive';
 import { EventBus, World } from '@babylonjsmarket/ecs';
 import { MockRendererAdapter } from '@babylonjsmarket/ecs';
 import type { MeshHandle } from '@babylonjsmarket/ecs/renderer-types';
@@ -124,4 +125,95 @@ describe('CameraFollowSystem', () => {
     const target = renderer.cameraTargets.get(arcComp.handle!)!;
     expect(target[1]).toBeCloseTo(5, 2);
   });
+
+  it('does nothing while no ArcCamera handle exists in the world', () => {
+    // No ArcCamera at all → findArcCameraHandle returns undefined.
+    const fakeHandle = renderer.createMesh('Player', { kind: 'capsule' });
+    renderer.meshWorldPositions.set(fakeHandle as MeshHandle, [1, 1, 1]);
+    const followEntity = world.createEntity('Follow');
+    followEntity.add(new CameraFollowComponent({ target: 'Player' }));
+    eventBus.emit('meshprimitive.created', { entityId: 'Player', handle: fakeHandle });
+
+    renderer.calls.length = 0;
+    world.update(1 / 60);
+    expect(renderer.calls.some((c) => c.method === 'setCameraTarget')).toBe(false);
+  });
+
+  it('skips entities whose component carries no follow target', () => {
+    const arcEntity = world.createEntity('Camera');
+    const arcComp = new ArcCameraComponent();
+    arcComp.handle = renderer.createArcCamera(arcEntity.id, arcComp.toSpec());
+    getArcCameraRuntime(arcComp).initialized = true;
+    arcEntity.add(arcComp);
+
+    const followEntity = world.createEntity('Follow');
+    followEntity.add(new CameraFollowComponent()); // empty target ''
+
+    renderer.calls.length = 0;
+    world.update(1 / 60);
+    expect(renderer.calls.some((c) => c.method === 'setCameraTarget')).toBe(false);
+  });
+
+  it('picks up a mesh handle already created before the system initializes', () => {
+    // Build a fresh world where the target mesh exists BEFORE CameraFollowSystem
+    // is added — exercising the existing-entity scan in onInitialize.
+    const bus = new EventBus();
+    const r = new MockRendererAdapter();
+    const w = new World({ eventBus: bus, renderer: r });
+    w.addSystem(new MeshPrimitiveSystem(bus));
+
+    const arcEntity = w.createEntity('Camera');
+    const arcComp = new ArcCameraComponent();
+    arcComp.handle = r.createArcCamera(arcEntity.id, arcComp.toSpec());
+    getArcCameraRuntime(arcComp).initialized = true;
+    arcEntity.add(arcComp);
+
+    const player = w.createEntity('Player');
+    player.add(new MeshPrimitiveComponent());
+    const mp = player.get(MeshPrimitiveComponent)!;
+    r.meshWorldPositions.set(mp.handle as MeshHandle, [4, 0, 2]);
+
+    const follow = w.createEntity('Follow');
+    follow.add(new CameraFollowComponent({ target: 'Player', smoothing: 1000, offsetX: 0, offsetY: 0, offsetZ: 0 }));
+
+    // System added AFTER the mesh handle already exists.
+    w.addSystem(new CameraFollowSystem(bus));
+    w.initialize();
+
+    r.calls.length = 0;
+    w.update(1 / 60);
+    const setCalls = r.calls.filter((c) => c.method === 'setCameraTarget');
+    expect(setCalls.length).toBe(1);
+    const tgt = r.cameraTargets.get(arcComp.handle!)!;
+    expect(tgt[0]).toBeCloseTo(4, 3);
+    expect(tgt[2]).toBeCloseTo(2, 3);
+  });
+
+  it('no-ops on a renderer-less world', () => {
+    const bus = new EventBus();
+    const w = new World({ eventBus: bus });
+    w.addSystem(new CameraFollowSystem(bus));
+    w.initialize();
+    const e = w.createEntity('Follow');
+    e.add(new CameraFollowComponent({ target: 'Player' }));
+    expect(() => w.update(1 / 60)).not.toThrow();
+  });
+
+  it('clears its primed flag when an entity is removed', () => {
+    const arcEntity = world.createEntity('Camera');
+    const arcComp = new ArcCameraComponent();
+    arcComp.handle = renderer.createArcCamera(arcEntity.id, arcComp.toSpec());
+    getArcCameraRuntime(arcComp).initialized = true;
+    arcEntity.add(arcComp);
+
+    const fakeHandle = renderer.createMesh('Player', { kind: 'capsule' });
+    renderer.meshWorldPositions.set(fakeHandle as MeshHandle, [0, 0, 0]);
+    const followEntity = world.createEntity('Follow');
+    followEntity.add(new CameraFollowComponent({ target: 'Player' }));
+    eventBus.emit('meshprimitive.created', { entityId: 'Player', handle: fakeHandle });
+
+    world.update(1 / 60);
+    // Removing the follow entity must not throw and should clear primed state.
+    expect(() => world.removeEntity(followEntity)).not.toThrow();
+  });
 });

package/src/Components/DirectionalLight/DirectionalLight.test.ts

@@ -28,6 +28,11 @@ describe('DirectionalLightComponent (core)', () => {
     expect(c.direction[2]).toBeCloseTo(0);
   });
 
+  it('falls back to straight-down for a zero-length direction', () => {
+    const c = new DirectionalLightComponent({ direction: [0, 0, 0] });
+    expect(c.direction).toEqual([0, -1, 0]);
+  });
+
   it('accepts full configuration', () => {
     const c = new DirectionalLightComponent({
       direction: [-1, -3, -1],
@@ -182,4 +187,47 @@ describe('DirectionalLightSystem — adapter integration', () => {
     world.removeEntity(entity);
     expect(renderer.calls.some((c) => c.method === 'disposeLight')).toBe(true);
   });
+
+  it('creates lights for entities that exist before the system initializes', () => {
+    const bus = new EventBus();
+    const r = new MockRendererAdapter();
+    const w = new World({ eventBus: bus, renderer: r });
+    const entity = w.createEntity();
+    entity.add(new DirectionalLightComponent({ intensity: 0.7 }));
+    // System added AFTER the entity exists → onInitialize scans and creates it.
+    w.addSystem(new DirectionalLightSystem(bus));
+    w.initialize();
+    const call = r.calls.find((c) => c.method === 'createDirectionalLight');
+    expect(call).toBeDefined();
+    expect((call!.args[1] as { intensity: number }).intensity).toBe(0.7);
+  });
+
+  it('does not emit when an unchanged light ticks (no snapshot drift)', () => {
+    const entity = world.createEntity();
+    entity.add(new DirectionalLightComponent());
+    renderer.calls.length = 0;
+    // Nothing mutated → onUpdate must not push any change to the adapter.
+    world.update(0.016);
+    expect(renderer.calls.some((c) => c.method === 'updateLightIntensity')).toBe(false);
+  });
+
+  it('no-ops on a renderer-less world (never creates a light)', () => {
+    const bus = new EventBus();
+    const w = new World({ eventBus: bus });
+    w.addSystem(new DirectionalLightSystem(bus));
+    w.initialize();
+    const entity = w.createEntity();
+    expect(() => entity.add(new DirectionalLightComponent())).not.toThrow();
+    expect(() => w.update(0.016)).not.toThrow();
+  });
+
+  it('skips the update loop entirely for an un-created (autoCreate:false) light', () => {
+    const entity = world.createEntity();
+    const comp = new DirectionalLightComponent({ autoCreate: false });
+    entity.add(comp);
+    comp.intensity = 5; // would emit if it had a handle/snapshot
+    renderer.calls.length = 0;
+    world.update(0.016);
+    expect(renderer.calls.some((c) => c.method === 'updateLightIntensity')).toBe(false);
+  });
 });

package/src/Components/Enemy/Enemy.core.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { EnemyComponent, wanderHeading, allDeathClips, chooseDeathClip } from './Enemy.core';
+import { EnemyComponent, wanderHeading, allDeathClips, chooseDeathClip, decideLocomotion } from './Enemy.core';
 
 describe('EnemyComponent', () => {
   it('applies defaults', () => {
@@ -78,6 +78,25 @@ describe('allDeathClips', () => {
   });
 });
 
+describe('decideLocomotion', () => {
+  it('attacks within contact range', () => {
+    expect(decideLocomotion(0.5, 1, 'walk', 1.15)).toBe('attack');
+    // boundary: distance === contactRange is still attack (<=)
+    expect(decideLocomotion(1, 1, 'walk', 1.15)).toBe('attack');
+  });
+
+  it('walks once past the hysteresis-scaled exit threshold', () => {
+    // contactRange*hysteresis = 1.15; just beyond → walk
+    expect(decideLocomotion(1.2, 1, 'attack', 1.15)).toBe('walk');
+  });
+
+  it('holds the current state inside the dead-band (anti-flicker)', () => {
+    // Between contactRange (1) and contactRange*hysteresis (1.15): keep current.
+    expect(decideLocomotion(1.1, 1, 'attack', 1.15)).toBe('attack');
+    expect(decideLocomotion(1.1, 1, 'walk', 1.15)).toBe('walk');
+  });
+});
+
 describe('chooseDeathClip', () => {
   const back = ['Shot_and_Blown_Back', 'Walking_Blow_Back'];
   const fwd = ['Fall_Forward'];