@vylos/core 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vylos/core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/DevOpsBenjamin/Vylos"

package/src/components/menu/SaveLoadMenu.vue

@@ -139,6 +139,7 @@ async function handleSlot(slot: number): Promise<void> {
       engineState.historyBrowsing = false;
       engineState.setDialogue(null);
       engineState.setChoices(null);
+      engineState.setForeground(null);
       engineState.closeMenu();
     }
   }

package/src/engine/core/Engine.ts

@@ -138,18 +138,23 @@ export class Engine {
    * Restores game state, history, event lock state, and sets up mid-event resume if needed.
    */
   loadSave(saveData: SaveSlot, setState: (state: VylosGameState) => void): void {
+    logger.info('Loading save...');
+
     // Restore game state
     setState(JSON.parse(JSON.stringify(saveData.gameState)));
+    logger.debug(`Restored game state (location: ${saveData.gameState.locationId})`);
 
     // Restore event lock state
     this.eventManager.resetAll();
     if (saveData.lockedEventIds) {
       this.eventManager.restoreLockedIds(saveData.lockedEventIds);
+      logger.debug(`Restored ${saveData.lockedEventIds.length} locked events`);
     }
 
     // Restore history
     if (saveData.history) {
       this.historyManager.restore(saveData.history, saveData.historyIndex ?? -1);
+      logger.debug(`Restored history (${saveData.history.length} entries, index ${saveData.historyIndex ?? -1})`);
     } else {
       this.historyManager.clear();
     }
@@ -161,12 +166,14 @@ export class Engine {
         checkpoints: saveData.checkpoints,
         initialState: saveData.initialState,
       };
+      logger.debug(`Pending resume: ${saveData.eventId} (${saveData.checkpoints.length} checkpoints)`);
     }
 
     // Interrupt current execution so the loop picks up the new state
     this.loadInterrupted = true;
     this.eventRunner.interrupt('load');
     this.navigationManager.cancel();
+    logger.info('Save loaded');
   }
 
   /** Execute a single event, handling jumps */
@@ -183,18 +190,18 @@ export class Engine {
         // Skip lock/push if interrupted by a load
         if (this.loadInterrupted) return;
 
-        // Event completed successfully
+        // Event completed — check locked() to decide fate
         const state = getState();
-        this.eventManager.setLocked(currentEvent.id, state);
+        this.finishEvent(currentEvent, state);
         this.historyManager.push(currentEvent.id, this.eventRunner.checkpoints.getAll());
         currentEvent = undefined;
       } catch (error) {
         if (this.loadInterrupted) return;
 
         if (error instanceof JumpSignal) {
-          // Lock current event, find jump target
+          // Finish current event, find jump target
           const state = getState();
-          this.eventManager.setLocked(currentEvent.id, state);
+          this.finishEvent(currentEvent, state);
           this.historyManager.push(currentEvent.id, this.eventRunner.checkpoints.getAll());
 
           const target = this.eventManager.get(error.targetEventId);
@@ -234,14 +241,14 @@ export class Engine {
       if (this.loadInterrupted) return;
 
       const state = getState();
-      this.eventManager.setLocked(resume.eventId, state);
+      this.finishEvent(event, state);
       this.historyManager.push(resume.eventId, this.eventRunner.checkpoints.getAll());
     } catch (error) {
       if (this.loadInterrupted) return;
 
       if (error instanceof JumpSignal) {
         const state = getState();
-        this.eventManager.setLocked(resume.eventId, state);
+        this.finishEvent(event, state);
         this.historyManager.push(resume.eventId, this.eventRunner.checkpoints.getAll());
 
         const target = this.eventManager.get(error.targetEventId);
@@ -255,6 +262,15 @@ export class Engine {
     }
   }
 
+  /** After event execution: lock permanently or return to Ready */
+  private finishEvent(event: VylosEvent, state: VylosGameState): void {
+    if (event.locked?.(state) === true) {
+      this.eventManager.setLocked(event.id);
+    } else {
+      this.eventManager.setReady(event.id);
+    }
+  }
+
   private handleBack(): void {
     const entry = this.historyManager.goBack();
     if (entry) {

package/src/engine/managers/EventManager.ts

@@ -10,11 +10,11 @@ interface EventEntry {
 /**
  * Manages event lifecycle: registration, condition evaluation, status transitions.
  *
- * Event lifecycle: NotReady → Unlocked → Running → Locked
- * - NotReady: conditions not yet met
- * - Unlocked: conditions met, ready to execute
+ * Event lifecycle: NotReady → Ready → Running → Ready (or Locked)
+ * - NotReady: unlocked() gate not yet passed
+ * - Ready: available — conditions() checked each tick
  * - Running: currently executing
- * - Locked: completed (won't trigger again)
+ * - Locked: permanently done (locked() returned true)
  */
 export class EventManager {
   private events = new Map<string, EventEntry>();
@@ -45,46 +45,44 @@ export class EventManager {
     return this.events.get(id)?.status;
   }
 
-  /** Evaluate conditions and update statuses. Returns newly unlocked events. */
+  /** Evaluate unlocked() gate for NotReady events. Returns newly ready events. */
   evaluate(state: VylosGameState): VylosEvent[] {
-    const unlocked: VylosEvent[] = [];
+    const newlyReady: VylosEvent[] = [];
 
     for (const [id, entry] of this.events) {
       if (entry.status !== EventStatus.NotReady) continue;
 
-      // Skip events bound to a different location
-      if (entry.event.locationId && entry.event.locationId !== state.locationId) continue;
+      // unlocked() gate: if not defined or returns !== false → Ready
+      if (entry.event.unlocked && entry.event.unlocked(state) === false) continue;
 
-      const conditionsMet = !entry.event.conditions || entry.event.conditions(state);
-      if (conditionsMet) {
-        entry.status = EventStatus.Unlocked;
-        entry.event.unlocked?.(state);
-        unlocked.push(entry.event);
-        logger.debug(`Event unlocked: ${id}`);
-      }
+      entry.status = EventStatus.Ready;
+      newlyReady.push(entry.event);
+      logger.debug(`Event ready: ${id}`);
     }
 
-    return unlocked;
+    return newlyReady;
   }
 
-  /** Get the next unlocked event matching the current location (first registered wins). Skips drawable events. */
+  /** Get the next ready event matching the current location whose conditions are met. Skips drawable events. */
   getNextUnlocked(state: VylosGameState): VylosEvent | undefined {
     for (const entry of this.events.values()) {
-      if (entry.status !== EventStatus.Unlocked) continue;
+      if (entry.status !== EventStatus.Ready) continue;
       if (entry.event.draw) continue; // Drawable events don't auto-trigger
       if (entry.event.locationId && entry.event.locationId !== state.locationId) continue;
+      if (entry.event.conditions && !entry.event.conditions(state)) continue;
       return entry.event;
     }
     return undefined;
   }
 
-  /** Get all unlocked drawable events at the current location */
+  /** Get all ready drawable events at the current location whose conditions are met */
   getDrawableEvents(state: VylosGameState, resolveText?: (text: string | Record<string, string>) => string): DrawableEventEntry[] {
     const result: DrawableEventEntry[] = [];
     for (const entry of this.events.values()) {
-      if (entry.status !== EventStatus.Unlocked) continue;
+      if (entry.status !== EventStatus.Ready) continue;
       if (!entry.event.draw) continue;
       if (entry.event.locationId && entry.event.locationId !== state.locationId) continue;
+      if (entry.event.conditions && !entry.event.conditions(state)) continue;
       const draw = entry.event.draw;
       const label = typeof draw.label === 'string'
         ? draw.label
@@ -107,16 +105,23 @@ export class EventManager {
     }
   }
 
-  /** Mark event as locked (completed) */
-  setLocked(id: string, state: VylosGameState): void {
+  /** Mark event as locked (permanently done) */
+  setLocked(id: string): void {
     const entry = this.events.get(id);
     if (entry) {
       entry.status = EventStatus.Locked;
-      entry.event.locked?.(state);
       logger.debug(`Event locked: ${id}`);
     }
   }
 
+  /** Mark event as ready (skip unlocked() gate) */
+  setReady(id: string): void {
+    const entry = this.events.get(id);
+    if (entry) {
+      entry.status = EventStatus.Ready;
+    }
+  }
+
   /** Reset an event back to NotReady */
   reset(id: string): void {
     const entry = this.events.get(id);

package/src/engine/types/events.ts

@@ -109,11 +109,11 @@ export interface VylosEvent<TState extends VylosGameState = VylosGameState> {
   /** Whether this event should trigger — checked each game loop tick */
   conditions?(state: TState): boolean;
 
-  /** Called when event transitions from NotReady → Unlocked */
-  unlocked?(state: TState): void;
+  /** Gate from NotReady → Ready. Return false to stay NotReady, anything else = Ready. */
+  unlocked?(state: TState): boolean;
 
-  /** Called when event completes (Unlocked → Locked) */
-  locked?(state: TState): void;
+  /** Called after execution. Return true to permanently lock, anything else = stays Ready. */
+  locked?(state: TState): boolean;
 
   /** The event's narrative logic */
   execute(engine: VylosAPI, state: TState): Promise<void>;
@@ -121,12 +121,12 @@ export interface VylosEvent<TState extends VylosGameState = VylosGameState> {
 
 /** Event lifecycle status */
 export enum EventStatus {
-  /** Conditions not yet met */
+  /** unlocked() gate not yet passed */
   NotReady = 'not_ready',
-  /** Conditions met, ready to execute */
-  Unlocked = 'unlocked',
+  /** Ready to execute when conditions met */
+  Ready = 'ready',
   /** Currently executing */
   Running = 'running',
-  /** Completed */
+  /** Permanently locked (locked() returned true) */
   Locked = 'locked',
 }

package/tests/engine/EventManager.test.ts

@@ -43,68 +43,121 @@ describe('EventManager', () => {
     expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
   });
 
-  describe('evaluate()', () => {
-    it('unlocks events with no conditions', () => {
+  describe('evaluate() — unlocked() gate', () => {
+    it('moves events with no unlocked() to Ready', () => {
       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);
+      const ready = em.evaluate(makeState());
+      expect(ready).toHaveLength(1);
+      expect(ready[0].id).toBe('ev1');
+      expect(em.getStatus('ev1')).toBe(EventStatus.Ready);
     });
 
-    it('unlocks events when conditions are met', () => {
+    it('moves events when unlocked() returns true', () => {
       em.register(makeEvent('ev1', {
-        conditions: (state) => state.flags['intro_done'] === true,
+        unlocked: () => true,
+      }));
+      const ready = em.evaluate(makeState());
+      expect(ready).toHaveLength(1);
+      expect(em.getStatus('ev1')).toBe(EventStatus.Ready);
+    });
+
+    it('keeps events NotReady when unlocked() returns false', () => {
+      em.register(makeEvent('ev1', {
+        unlocked: (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();
+      const ready = em.evaluate(makeState({ flags: { intro_done: true } }));
+      expect(ready).toHaveLength(1);
+      expect(em.getStatus('ev1')).toBe(EventStatus.Ready);
     });
 
-    it('does not re-evaluate already unlocked events', () => {
+    it('does not re-evaluate already Ready events', () => {
       em.register(makeEvent('ev1'));
       em.evaluate(makeState());
       const second = em.evaluate(makeState());
       expect(second).toHaveLength(0);
     });
+
+    it('does not check conditions — only unlocked() gate', () => {
+      em.register(makeEvent('ev1', {
+        conditions: () => false,
+      }));
+      // evaluate() ignores conditions — event goes Ready anyway
+      const ready = em.evaluate(makeState());
+      expect(ready).toHaveLength(1);
+      expect(em.getStatus('ev1')).toBe(EventStatus.Ready);
+    });
   });
 
-  it('getNextUnlocked returns first unlocked event', () => {
-    em.register(makeEvent('ev1', {
-      conditions: () => false,
-    }));
-    em.register(makeEvent('ev2'));
-    em.evaluate(makeState());
+  describe('getNextUnlocked() — conditions checked at query time', () => {
+    it('returns first Ready event with no conditions', () => {
+      em.register(makeEvent('ev1'));
+      em.evaluate(makeState());
+      const next = em.getNextUnlocked(makeState());
+      expect(next?.id).toBe('ev1');
+    });
+
+    it('skips Ready event when conditions return false', () => {
+      em.register(makeEvent('ev1', {
+        conditions: () => false,
+      }));
+      em.register(makeEvent('ev2'));
+      em.evaluate(makeState());
+
+      const next = em.getNextUnlocked(makeState());
+      expect(next?.id).toBe('ev2');
+    });
+
+    it('returns Ready event when conditions return true', () => {
+      em.register(makeEvent('ev1', {
+        conditions: (state) => state.flags['go'] === true,
+      }));
+      em.evaluate(makeState());
 
-    const next = em.getNextUnlocked(makeState());
-    expect(next?.id).toBe('ev2');
+      expect(em.getNextUnlocked(makeState())).toBeUndefined();
+      expect(em.getNextUnlocked(makeState({ flags: { go: true } }))?.id).toBe('ev1');
+    });
   });
 
-  it('lifecycle: NotReady → Unlocked → Running → Locked', () => {
-    const lockedFn = vi.fn();
-    em.register(makeEvent('ev1', { locked: lockedFn }));
+  describe('lifecycle: NotReady → Ready → Running → Ready/Locked', () => {
+    it('repeatable event: Ready → Running → Ready', () => {
+      em.register(makeEvent('ev1'));
 
-    expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
+      expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
 
-    em.evaluate(makeState());
-    expect(em.getStatus('ev1')).toBe(EventStatus.Unlocked);
+      em.evaluate(makeState());
+      expect(em.getStatus('ev1')).toBe(EventStatus.Ready);
 
-    em.setRunning('ev1');
-    expect(em.getStatus('ev1')).toBe(EventStatus.Running);
+      em.setRunning('ev1');
+      expect(em.getStatus('ev1')).toBe(EventStatus.Running);
 
-    em.setLocked('ev1', makeState());
-    expect(em.getStatus('ev1')).toBe(EventStatus.Locked);
-    expect(lockedFn).toHaveBeenCalledOnce();
+      em.setReady('ev1');
+      expect(em.getStatus('ev1')).toBe(EventStatus.Ready);
+    });
+
+    it('one-shot event: Ready → Running → Locked', () => {
+      em.register(makeEvent('ev1'));
+
+      em.evaluate(makeState());
+      em.setRunning('ev1');
+      em.setLocked('ev1');
+      expect(em.getStatus('ev1')).toBe(EventStatus.Locked);
+    });
+
+    it('setLocked is a pure status setter (no callback)', () => {
+      const lockedFn = vi.fn();
+      em.register(makeEvent('ev1', { locked: lockedFn }));
+
+      em.evaluate(makeState());
+      em.setRunning('ev1');
+      em.setLocked('ev1');
+      expect(em.getStatus('ev1')).toBe(EventStatus.Locked);
+      // locked() is NOT called by setLocked — Engine calls it explicitly
+      expect(lockedFn).not.toHaveBeenCalled();
+    });
   });
 
   it('getByLocation filters events', () => {
@@ -123,8 +176,8 @@ describe('EventManager', () => {
     em.register(makeEvent('ev3'));
 
     em.evaluate(makeState());
-    em.setLocked('ev1', makeState());
-    em.setLocked('ev3', makeState());
+    em.setLocked('ev1');
+    em.setLocked('ev3');
 
     const ids = em.getLockedIds();
     expect(ids).toEqual(['ev1', 'ev3']);
@@ -139,8 +192,21 @@ describe('EventManager', () => {
   it('reset puts event back to NotReady', () => {
     em.register(makeEvent('ev1'));
     em.evaluate(makeState());
-    expect(em.getStatus('ev1')).toBe(EventStatus.Unlocked);
+    expect(em.getStatus('ev1')).toBe(EventStatus.Ready);
     em.reset('ev1');
     expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
   });
+
+  it('setReady puts event directly to Ready (skips gate)', () => {
+    em.register(makeEvent('ev1', {
+      unlocked: () => false,
+    }));
+    // Gate blocks it
+    em.evaluate(makeState());
+    expect(em.getStatus('ev1')).toBe(EventStatus.NotReady);
+
+    // setReady bypasses gate
+    em.setReady('ev1');
+    expect(em.getStatus('ev1')).toBe(EventStatus.Ready);
+  });
 });

package/tests/integration/game-loop.test.ts

@@ -69,6 +69,7 @@ describe('Game loop integration', () => {
 
     const event: VylosEvent = {
       id: 'intro',
+      locked: () => true,
       async execute(api: VylosAPI) {
         await api.say('Hello');
         await api.say('World');
@@ -130,6 +131,7 @@ describe('Game loop integration', () => {
     const events: VylosEvent[] = [
       {
         id: 'first',
+        locked: () => true,
         async execute(api: VylosAPI) {
           await api.say('In first event');
           api.jump('second');
@@ -137,6 +139,7 @@ describe('Game loop integration', () => {
       },
       {
         id: 'second',
+        locked: () => true,
         async execute(api: VylosAPI) {
           await api.say('In second event');
         },