@vylos/core 0.1.0

package/tests/engine/EventManager.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { EventManager } from '../../src/engine/managers/EventManager';
+import type { VylosEvent, VylosAPI, BaseGameState } from '../../src/engine/types';
+import { EventStatus } from '../../src/engine/types';
+
+function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+  return {
+    locationId: 'cafe',
+    gameTime: 8,
+    flags: {},
+    counters: {},
+    player: { name: 'Alice' },
+    ...overrides,
+  };
+}
+
+function makeEvent(id: string, overrides: Partial<VylosEvent> = {}): VylosEvent {
+  return {
+    id,
+    async execute(_engine: VylosAPI) { /* noop */ },
+    ...overrides,
+  };
+}
+
+describe('EventManager', () => {
+  let em: EventManager;
+
+  beforeEach(() => {
+    em = new EventManager();
+  });
+
+  it('registers events', () => {
+    em.register(makeEvent('ev1'));
+    em.register(makeEvent('ev2'));
+    expect(em.get('ev1')).toBeDefined();
+    expect(em.get('ev2')).toBeDefined();
+    expect(em.get('ev3')).toBeUndefined();
+  });
+
+  it('events start as NotReady', () => {
+    em.register(makeEvent('ev1'));
+    expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
+  });
+
+  describe('evaluate()', () => {
+    it('unlocks events with no conditions', () => {
+      em.register(makeEvent('ev1'));
+      const unlocked = em.evaluate(makeState());
+      expect(unlocked).toHaveLength(1);
+      expect(unlocked[0].id).toBe('ev1');
+      expect(em.getStatus('ev1')).toBe(EventStatus.Unlocked);
+    });
+
+    it('unlocks events when conditions are met', () => {
+      em.register(makeEvent('ev1', {
+        conditions: (state) => state.flags['intro_done'] === true,
+      }));
+
+      expect(em.evaluate(makeState())).toHaveLength(0);
+      expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
+
+      const unlocked = em.evaluate(makeState({ flags: { intro_done: true } }));
+      expect(unlocked).toHaveLength(1);
+    });
+
+    it('calls unlocked() callback when transitioning', () => {
+      const unlockedFn = vi.fn();
+      em.register(makeEvent('ev1', { unlocked: unlockedFn }));
+      em.evaluate(makeState());
+      expect(unlockedFn).toHaveBeenCalledOnce();
+    });
+
+    it('does not re-evaluate already unlocked events', () => {
+      em.register(makeEvent('ev1'));
+      em.evaluate(makeState());
+      const second = em.evaluate(makeState());
+      expect(second).toHaveLength(0);
+    });
+  });
+
+  it('getNextUnlocked returns first unlocked event', () => {
+    em.register(makeEvent('ev1', {
+      conditions: () => false,
+    }));
+    em.register(makeEvent('ev2'));
+    em.evaluate(makeState());
+
+    const next = em.getNextUnlocked(makeState());
+    expect(next?.id).toBe('ev2');
+  });
+
+  it('lifecycle: NotReady → Unlocked → Running → Locked', () => {
+    const lockedFn = vi.fn();
+    em.register(makeEvent('ev1', { locked: lockedFn }));
+
+    expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
+
+    em.evaluate(makeState());
+    expect(em.getStatus('ev1')).toBe(EventStatus.Unlocked);
+
+    em.setRunning('ev1');
+    expect(em.getStatus('ev1')).toBe(EventStatus.Running);
+
+    em.setLocked('ev1', makeState());
+    expect(em.getStatus('ev1')).toBe(EventStatus.Locked);
+    expect(lockedFn).toHaveBeenCalledOnce();
+  });
+
+  it('getByLocation filters events', () => {
+    em.register(makeEvent('ev1', { locationId: 'cafe' }));
+    em.register(makeEvent('ev2', { locationId: 'bedroom' }));
+    em.register(makeEvent('ev3', { locationId: 'cafe' }));
+
+    const cafeEvents = em.getByLocation('cafe');
+    expect(cafeEvents).toHaveLength(2);
+    expect(cafeEvents.map(e => e.id)).toEqual(['ev1', 'ev3']);
+  });
+
+  it('getLockedIds / restoreLockedIds', () => {
+    em.register(makeEvent('ev1'));
+    em.register(makeEvent('ev2'));
+    em.register(makeEvent('ev3'));
+
+    em.evaluate(makeState());
+    em.setLocked('ev1', makeState());
+    em.setLocked('ev3', makeState());
+
+    const ids = em.getLockedIds();
+    expect(ids).toEqual(['ev1', 'ev3']);
+
+    em.resetAll();
+    em.restoreLockedIds(['ev1', 'ev3']);
+    expect(em.getStatus('ev1')).toBe(EventStatus.Locked);
+    expect(em.getStatus('ev2')).toBe(EventStatus.NotReady);
+    expect(em.getStatus('ev3')).toBe(EventStatus.Locked);
+  });
+
+  it('reset puts event back to NotReady', () => {
+    em.register(makeEvent('ev1'));
+    em.evaluate(makeState());
+    expect(em.getStatus('ev1')).toBe(EventStatus.Unlocked);
+    em.reset('ev1');
+    expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
+  });
+});

package/tests/engine/EventRunner.test.ts

@@ -0,0 +1,318 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { EventRunner, type EventRunnerCallbacks } from '../../src/engine/core/EventRunner';
+import type { VylosEvent, VylosAPI, BaseGameState } from '../../src/engine/types';
+import { JumpSignal } from '../../src/engine/errors/JumpSignal';
+import { EventEndError } from '../../src/engine/errors/EventEndError';
+
+function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+  return {
+    locationId: 'cafe',
+    gameTime: 8,
+    flags: {},
+    counters: {},
+    player: { name: 'Alice' },
+    ...overrides,
+  };
+}
+
+function makeCallbacks(state?: BaseGameState): EventRunnerCallbacks & { state: BaseGameState } {
+  const s = state ?? makeState();
+  return {
+    state: s,
+    onSay: vi.fn(),
+    onChoice: vi.fn(),
+    onSetBackground: vi.fn(),
+    onSetForeground: vi.fn(),
+    onShowOverlay: vi.fn(),
+    onHideOverlay: vi.fn(),
+    onSetLocation: vi.fn(),
+    onClear: vi.fn(),
+    resolveText: vi.fn((text: unknown) => typeof text === 'string' ? text : 'resolved'),
+    getState: vi.fn(() => s),
+    setState: vi.fn((newState: BaseGameState) => { Object.assign(s, newState); }),
+  };
+}
+
+describe('EventRunner', () => {
+  let callbacks: ReturnType<typeof makeCallbacks>;
+  let runner: EventRunner;
+
+  beforeEach(() => {
+    callbacks = makeCallbacks();
+    runner = new EventRunner(callbacks);
+  });
+
+  describe('say()', () => {
+    it('displays dialogue and waits for continue', async () => {
+      const event: VylosEvent = {
+        id: 'test-say',
+        async execute(engine: VylosAPI) {
+          await engine.say('Hello world');
+        },
+      };
+
+      // Start execution (will pause at say)
+      const promise = runner.executeEvent(event);
+
+      // Wait a tick for the say to be called
+      await vi.waitFor(() => {
+        expect(callbacks.onSay).toHaveBeenCalledWith('Hello world', null);
+      });
+
+      // Simulate player clicking continue
+      runner.resolveWait();
+
+      await promise;
+      expect(callbacks.onClear).toHaveBeenCalled();
+    });
+
+    it('resolves speaker text', async () => {
+      const event: VylosEvent = {
+        id: 'test-speaker',
+        async execute(engine: VylosAPI) {
+          await engine.say('Hi!', { from: 'Barista' });
+        },
+      };
+
+      const promise = runner.executeEvent(event);
+
+      await vi.waitFor(() => {
+        expect(callbacks.onSay).toHaveBeenCalledWith('Hi!', 'Barista');
+      });
+
+      runner.resolveWait();
+      await promise;
+    });
+
+    it('interpolates variables', async () => {
+      callbacks.resolveText = vi.fn((t: unknown) => typeof t === 'string' ? t : 'resolved');
+
+      const event: VylosEvent = {
+        id: 'test-vars',
+        async execute(engine: VylosAPI) {
+          await engine.say('Hello {name}!', { variables: { name: 'Bob' } });
+        },
+      };
+
+      const promise = runner.executeEvent(event);
+
+      await vi.waitFor(() => {
+        expect(callbacks.onSay).toHaveBeenCalledWith('Hello Bob!', null);
+      });
+
+      runner.resolveWait();
+      await promise;
+    });
+  });
+
+  describe('choice()', () => {
+    it('shows choices and returns selected value', async () => {
+      let result = '';
+      const event: VylosEvent = {
+        id: 'test-choice',
+        async execute(engine: VylosAPI) {
+          result = await engine.choice([
+            { text: 'Coffee', value: 'coffee' },
+            { text: 'Tea', value: 'tea' },
+          ]);
+        },
+      };
+
+      const promise = runner.executeEvent(event);
+
+      await vi.waitFor(() => {
+        expect(callbacks.onChoice).toHaveBeenCalled();
+      });
+
+      // Simulate player choosing "tea"
+      runner.resolveWait('tea');
+      await promise;
+
+      expect(result).toBe('tea');
+    });
+
+    it('filters choices by condition', async () => {
+      const event: VylosEvent = {
+        id: 'test-choice-filter',
+        async execute(engine: VylosAPI) {
+          await engine.choice([
+            { text: 'Coffee', value: 'coffee' },
+            { text: 'Secret', value: 'secret', condition: () => false },
+          ]);
+        },
+      };
+
+      const promise = runner.executeEvent(event);
+
+      await vi.waitFor(() => {
+        expect(callbacks.onChoice).toHaveBeenCalled();
+        const options = callbacks.onChoice.mock.calls[0][0];
+        expect(options).toHaveLength(1);
+        expect(options[0].value).toBe('coffee');
+      });
+
+      runner.resolveWait('coffee');
+      await promise;
+    });
+  });
+
+  describe('inline choice branching', () => {
+    it('supports if/else based on choice result', async () => {
+      const spoken: string[] = [];
+      callbacks.onSay = vi.fn((_text: string) => { spoken.push(_text); });
+
+      const event: VylosEvent = {
+        id: 'test-branch',
+        async execute(engine: VylosAPI) {
+          await engine.say('Welcome!');
+          const pick = await engine.choice([
+            { text: 'Coffee', value: 'coffee' },
+            { text: 'Tea', value: 'tea' },
+          ]);
+          if (pick === 'coffee') {
+            await engine.say('Good choice!');
+          } else {
+            await engine.say('Coming right up!');
+          }
+          await engine.say('Enjoy.');
+        },
+      };
+
+      const promise = runner.executeEvent(event);
+
+      // Step 1: "Welcome!"
+      await vi.waitFor(() => expect(spoken).toContain('Welcome!'));
+      runner.resolveWait();
+
+      // Step 2: Choice
+      await vi.waitFor(() => expect(callbacks.onChoice).toHaveBeenCalled());
+      runner.resolveWait('coffee');
+
+      // Step 3: "Good choice!" (not "Coming right up!")
+      await vi.waitFor(() => expect(spoken).toContain('Good choice!'));
+      runner.resolveWait();
+
+      // Step 4: "Enjoy."
+      await vi.waitFor(() => expect(spoken).toContain('Enjoy.'));
+      runner.resolveWait();
+
+      await promise;
+
+      expect(spoken).toEqual(['Welcome!', 'Good choice!', 'Enjoy.']);
+      expect(spoken).not.toContain('Coming right up!');
+    });
+  });
+
+  describe('jump()', () => {
+    it('throws JumpSignal', async () => {
+      const event: VylosEvent = {
+        id: 'test-jump',
+        async execute(engine: VylosAPI) {
+          engine.jump('other-event');
+        },
+      };
+
+      await expect(runner.executeEvent(event)).rejects.toThrow(JumpSignal);
+    });
+
+    it('carries target event ID', async () => {
+      const event: VylosEvent = {
+        id: 'test-jump-id',
+        async execute(engine: VylosAPI) {
+          engine.jump('intro');
+        },
+      };
+
+      try {
+        await runner.executeEvent(event);
+      } catch (e) {
+        expect(e).toBeInstanceOf(JumpSignal);
+        expect((e as JumpSignal).targetEventId).toBe('intro');
+      }
+    });
+  });
+
+  describe('end()', () => {
+    it('ends event cleanly', async () => {
+      const spoken: string[] = [];
+      callbacks.onSay = vi.fn((t: string) => spoken.push(t));
+
+      const event: VylosEvent = {
+        id: 'test-end',
+        async execute(engine: VylosAPI) {
+          await engine.say('Before end');
+          engine.end();
+          // This should never execute
+          await engine.say('After end');
+        },
+      };
+
+      const promise = runner.executeEvent(event);
+
+      await vi.waitFor(() => expect(spoken).toContain('Before end'));
+      runner.resolveWait();
+
+      await promise;
+      expect(spoken).not.toContain('After end');
+    });
+  });
+
+  describe('setBackground / setForeground', () => {
+    it('calls callbacks synchronously', async () => {
+      const event: VylosEvent = {
+        id: 'test-bg',
+        async execute(engine: VylosAPI) {
+          engine.setBackground('/bg.jpg');
+          engine.setForeground('/fg.png');
+        },
+      };
+
+      await runner.executeEvent(event);
+      expect(callbacks.onSetBackground).toHaveBeenCalledWith('/bg.jpg');
+      expect(callbacks.onSetForeground).toHaveBeenCalledWith('/fg.png');
+    });
+  });
+
+  describe('checkpoints', () => {
+    it('captures checkpoint for each say', async () => {
+      const event: VylosEvent = {
+        id: 'test-cp',
+        async execute(engine: VylosAPI) {
+          await engine.say('Line 1');
+          await engine.say('Line 2');
+        },
+      };
+
+      const promise = runner.executeEvent(event);
+
+      await vi.waitFor(() => expect(callbacks.onSay).toHaveBeenCalled());
+      runner.resolveWait();
+
+      await vi.waitFor(() => expect(callbacks.onSay).toHaveBeenCalledTimes(2));
+      runner.resolveWait();
+
+      await promise;
+      expect(runner.checkpoints.count).toBe(2);
+    });
+
+    it('captures choice result in checkpoint', async () => {
+      const event: VylosEvent = {
+        id: 'test-cp-choice',
+        async execute(engine: VylosAPI) {
+          await engine.choice([
+            { text: 'A', value: 'a' },
+            { text: 'B', value: 'b' },
+          ]);
+        },
+      };
+
+      const promise = runner.executeEvent(event);
+      await vi.waitFor(() => expect(callbacks.onChoice).toHaveBeenCalled());
+      runner.resolveWait('b');
+      await promise;
+
+      const all = runner.checkpoints.getAll();
+      expect(all[0].choiceResult).toBe('b');
+    });
+  });
+});

package/tests/engine/HistoryManager.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { HistoryManager } from '../../src/engine/managers/HistoryManager';
+import type { Checkpoint } from '../../src/engine/types';
+import { CheckpointType } from '../../src/engine/types';
+
+function makeCheckpoints(count: number): Checkpoint[] {
+  return Array.from({ length: count }, (_, i) => ({
+    step: i,
+    gameState: {
+      locationId: 'cafe',
+      gameTime: 8 + i,
+      flags: {},
+      counters: {},
+      player: { name: 'Alice' },
+    },
+    type: CheckpointType.Say,
+  }));
+}
+
+describe('HistoryManager', () => {
+  let hm: HistoryManager;
+
+  beforeEach(() => {
+    hm = new HistoryManager();
+  });
+
+  it('starts empty', () => {
+    expect(hm.count).toBe(0);
+    expect(hm.canGoBack).toBe(false);
+    expect(hm.canGoForward).toBe(false);
+    expect(hm.current).toBeUndefined();
+  });
+
+  it('pushes entries and tracks current', () => {
+    hm.push('event-1', makeCheckpoints(2));
+    expect(hm.count).toBe(1);
+    expect(hm.current?.eventId).toBe('event-1');
+
+    hm.push('event-2', makeCheckpoints(3));
+    expect(hm.count).toBe(2);
+    expect(hm.current?.eventId).toBe('event-2');
+  });
+
+  it('goes back and forward', () => {
+    hm.push('event-1', makeCheckpoints(2));
+    hm.push('event-2', makeCheckpoints(3));
+    hm.push('event-3', makeCheckpoints(1));
+
+    expect(hm.canGoBack).toBe(true);
+    expect(hm.canGoForward).toBe(false);
+
+    const back1 = hm.goBack();
+    expect(back1?.eventId).toBe('event-2');
+    expect(hm.canGoBack).toBe(true);
+    expect(hm.canGoForward).toBe(true);
+
+    const back2 = hm.goBack();
+    expect(back2?.eventId).toBe('event-1');
+    expect(hm.canGoBack).toBe(false);
+
+    const fwd1 = hm.goForward();
+    expect(fwd1?.eventId).toBe('event-2');
+  });
+
+  it('trims forward history on push after goBack', () => {
+    hm.push('event-1', makeCheckpoints(1));
+    hm.push('event-2', makeCheckpoints(1));
+    hm.push('event-3', makeCheckpoints(1));
+
+    hm.goBack(); // at event-2
+    hm.push('event-4', makeCheckpoints(1));
+
+    expect(hm.count).toBe(3); // event-1, event-2, event-4
+    expect(hm.current?.eventId).toBe('event-4');
+    expect(hm.canGoForward).toBe(false);
+  });
+
+  it('goBack returns undefined when at start', () => {
+    hm.push('event-1', makeCheckpoints(1));
+    expect(hm.goBack()).toBeUndefined();
+  });
+
+  it('goForward returns undefined when at end', () => {
+    hm.push('event-1', makeCheckpoints(1));
+    expect(hm.goForward()).toBeUndefined();
+  });
+
+  it('clear removes all history', () => {
+    hm.push('event-1', makeCheckpoints(2));
+    hm.push('event-2', makeCheckpoints(3));
+    hm.clear();
+    expect(hm.count).toBe(0);
+    expect(hm.canGoBack).toBe(false);
+  });
+
+  it('getAll returns deep clones', () => {
+    hm.push('event-1', makeCheckpoints(2));
+    const all = hm.getAll();
+    all[0].eventId = 'hacked';
+    expect(hm.current?.eventId).toBe('event-1');
+  });
+
+  it('restore loads from save data', () => {
+    const entries = [
+      { eventId: 'ev1', checkpoints: makeCheckpoints(2) },
+      { eventId: 'ev2', checkpoints: makeCheckpoints(1) },
+    ];
+    hm.restore(entries, 1);
+    expect(hm.count).toBe(2);
+    expect(hm.current?.eventId).toBe('ev2');
+    expect(hm.canGoBack).toBe(true);
+  });
+});

package/tests/engine/LocationManager.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { LocationManager } from '../../src/engine/managers/LocationManager';
+import type { VylosLocation, LocationLink, BaseGameState } from '../../src/engine/types';
+
+function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+  return {
+    locationId: 'bedroom',
+    gameTime: 12,
+    flags: {},
+    counters: {},
+    player: { name: 'Alice' },
+    ...overrides,
+  };
+}
+
+const bedroom: VylosLocation = {
+  id: 'bedroom',
+  name: 'Bedroom',
+  backgrounds: [
+    { path: '/bedroom_day.jpg', timeRange: [6, 18] },
+    { path: '/bedroom_night.jpg', timeRange: [18, 6] },
+  ],
+};
+
+const hallway: VylosLocation = {
+  id: 'hallway',
+  name: 'Hallway',
+  backgrounds: [{ path: '/hallway.jpg' }],
+};
+
+const cafe: VylosLocation = {
+  id: 'cafe',
+  name: { en: 'Cafe', fr: 'Café' },
+  backgrounds: [{ path: '/cafe.jpg' }],
+  accessible: (state) => state.flags['has_key'] === true,
+};
+
+describe('LocationManager', () => {
+  let lm: LocationManager;
+
+  beforeEach(() => {
+    lm = new LocationManager();
+    lm.registerAll([bedroom, hallway, cafe]);
+  });
+
+  it('registers and retrieves locations', () => {
+    expect(lm.get('bedroom')).toBeDefined();
+    expect(lm.get('hallway')).toBeDefined();
+    expect(lm.get('cafe')).toBeDefined();
+    expect(lm.get('nonexistent')).toBeUndefined();
+  });
+
+  it('has() checks existence', () => {
+    expect(lm.has('bedroom')).toBe(true);
+    expect(lm.has('nope')).toBe(false);
+  });
+
+  it('getAll returns all locations', () => {
+    expect(lm.getAll()).toHaveLength(3);
+  });
+
+  describe('getAccessibleFrom', () => {
+    beforeEach(() => {
+      lm.setLinks([
+        { from: 'bedroom', to: 'hallway' },
+        { from: 'hallway', to: 'bedroom' },
+        { from: 'hallway', to: 'cafe' },
+      ]);
+    });
+
+    it('returns linked accessible locations', () => {
+      const state = makeState({ flags: { has_key: true } });
+      const accessible = lm.getAccessibleFrom('hallway', state);
+      expect(accessible.map(l => l.id)).toContain('bedroom');
+      expect(accessible.map(l => l.id)).toContain('cafe');
+    });
+
+    it('excludes inaccessible locations', () => {
+      const state = makeState(); // no has_key flag
+      const accessible = lm.getAccessibleFrom('hallway', state);
+      expect(accessible.map(l => l.id)).toContain('bedroom');
+      expect(accessible.map(l => l.id)).not.toContain('cafe');
+    });
+
+    it('only returns locations linked from source', () => {
+      const state = makeState({ flags: { has_key: true } });
+      const accessible = lm.getAccessibleFrom('bedroom', state);
+      expect(accessible.map(l => l.id)).toEqual(['hallway']);
+    });
+
+    it('supports conditional links', () => {
+      lm.setLinks([
+        { from: 'bedroom', to: 'hallway' },
+        {
+          from: 'bedroom',
+          to: 'cafe',
+          condition: (state) => state.flags['secret_path'] === true,
+        },
+      ]);
+
+      const stateWithout = makeState({ flags: { has_key: true } });
+      expect(lm.getAccessibleFrom('bedroom', stateWithout).map(l => l.id)).toEqual(['hallway']);
+
+      const stateWith = makeState({ flags: { has_key: true, secret_path: true } });
+      expect(lm.getAccessibleFrom('bedroom', stateWith).map(l => l.id)).toEqual(['hallway', 'cafe']);
+    });
+  });
+
+  describe('resolveBackground', () => {
+    it('resolves time-based background', () => {
+      expect(lm.resolveBackground('bedroom', 12)).toBe('/bedroom_day.jpg');
+      expect(lm.resolveBackground('bedroom', 22)).toBe('/bedroom_night.jpg');
+    });
+
+    it('resolves default background', () => {
+      expect(lm.resolveBackground('hallway', 12)).toBe('/hallway.jpg');
+    });
+
+    it('returns null for unknown location', () => {
+      expect(lm.resolveBackground('nope', 12)).toBeNull();
+    });
+  });
+
+  it('clear removes everything', () => {
+    lm.clear();
+    expect(lm.getAll()).toHaveLength(0);
+  });
+});