@vylos/core 0.5.4 → 0.6.0

package/package.json

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

package/src/components/app/GameShell.vue

@@ -92,6 +92,7 @@ const isRunning = computed(() =>
 // --- History step helpers ---
 
 function applyHistoryStep(step: HistoryStep): void {
+  engineState.setForeground(step.foreground ?? null);
   if (step.type === 'say' && step.dialogue) {
     engineState.setDialogue(step.dialogue);
     engineState.setChoices(null);

package/src/components/core/ForegroundLayer.vue

@@ -1,11 +1,20 @@
 <template>
   <Transition name="fg-fade">
-    <img
+    <div
       v-if="engineState.foreground"
-      :src="fgUrl"
-      alt=""
-      class="absolute inset-0 w-full h-full object-contain z-10 pointer-events-none"
-    />
+      class="absolute inset-0 z-10 pointer-events-none overflow-hidden"
+    >
+      <img
+        :src="fgUrl"
+        alt=""
+        class="fg-blur absolute inset-0 w-full h-full object-cover"
+      />
+      <img
+        :src="fgUrl"
+        alt=""
+        class="absolute inset-0 w-full h-full object-contain"
+      />
+    </div>
   </Transition>
 </template>
 
@@ -20,6 +29,11 @@ const fgUrl = computed(() => engineState.foreground ? assetUrl(engineState.foreg
 </script>
 
 <style scoped>
+.fg-blur {
+  filter: blur(80px);
+  transform: scale(1.2);
+}
+
 .fg-fade-enter-active,
 .fg-fade-leave-active {
   transition: opacity 0.3s ease;

package/src/engine/core/CheckpointManager.ts

@@ -5,6 +5,7 @@ import type { DialogueState } from '../types/engine';
 export interface CaptureDisplayData {
   dialogue?: DialogueState | null;
   background?: string | null;
+  foreground?: string | null;
   choiceOptions?: ChoiceOption[];
 }
 
@@ -46,6 +47,7 @@ export class CheckpointManager {
       choiceResult,
       dialogue: display?.dialogue ? structuredClone(toRaw(display.dialogue)) : undefined,
       background: display?.background,
+      foreground: display?.foreground,
       choiceOptions: display?.choiceOptions ? structuredClone(toRaw(display.choiceOptions)) : undefined,
     };
 

package/src/engine/core/EventRunner.ts

@@ -50,6 +50,7 @@ export interface EventRunnerCallbacks {
 export interface HistoryStep {
   type: 'say' | 'choice';
   dialogue?: DialogueState | null;
+  foreground?: string | null;
   choiceOptions?: ChoiceOption[];
   choiceResult?: string;
   stepIndex: number;
@@ -77,6 +78,8 @@ export class EventRunner implements VylosAPI {
   private liveDialogue: { text: string; speaker: VylosCharacter | null } | null = null;
   /** Current background path (tracked for checkpoint storage) */
   private currentBackground: string | null = null;
+  /** Current foreground path (tracked for checkpoint storage) */
+  private currentForeground: string | null = null;
 
   /** Snapshot of game state before event started (for redo) */
   private initialState: VylosGameState | null = null;
@@ -196,6 +199,8 @@ export class EventRunner implements VylosAPI {
       await this.runEventExecution(event);
     } finally {
       this.callbacks.onClear();
+      logger.debug(`Event ended — clearing foreground`);
+      this.callbacks.onSetForeground(null);
       this.initialState = null;
       this.currentEvent = null;
     }
@@ -223,6 +228,8 @@ export class EventRunner implements VylosAPI {
       throw error;
     } finally {
       this.callbacks.onClear();
+      logger.debug(`Rollback ended — clearing foreground`);
+      this.callbacks.onSetForeground(null);
     }
   }
 
@@ -244,6 +251,8 @@ export class EventRunner implements VylosAPI {
       await this.runEventExecution(event);
     } finally {
       this.callbacks.onClear();
+      logger.debug(`Resume ended — clearing foreground`);
+      this.callbacks.onSetForeground(null);
       this.initialState = null;
       this.currentEvent = null;
     }
@@ -297,6 +306,7 @@ export class EventRunner implements VylosAPI {
       {
         dialogue: { text: resolvedText, speaker, isNarration: !speaker },
         background: this.currentBackground,
+        foreground: this.currentForeground,
       },
     );
 
@@ -342,7 +352,7 @@ export class EventRunner implements VylosAPI {
       this.callbacks.getState(),
       'choice' as CheckpointType,
       result,
-      { choiceOptions: resolvedOptions },
+      { choiceOptions: resolvedOptions, foreground: this.currentForeground },
     );
 
     this.callbacks.onClear();
@@ -356,6 +366,7 @@ export class EventRunner implements VylosAPI {
   }
 
   setForeground(path: string | null): void {
+    this.currentForeground = path;
     this.callbacks.onSetForeground(path);
   }
 
@@ -438,6 +449,7 @@ export class EventRunner implements VylosAPI {
     if (cp.choiceOptions) {
       return {
         type: 'choice',
+        foreground: cp.foreground,
         choiceOptions: cp.choiceOptions,
         choiceResult: cp.choiceResult,
         stepIndex: idx,
@@ -446,6 +458,7 @@ export class EventRunner implements VylosAPI {
     return {
       type: 'say',
       dialogue: cp.dialogue,
+      foreground: cp.foreground,
       stepIndex: idx,
     };
   }

package/src/engine/managers/LocationManager.ts

@@ -1,4 +1,4 @@
-import type { VylosLocation, LocationLink, VylosGameState, BackgroundEntry } from '../types';
+import type { VylosLocation, LocationLink, VylosGameState } from '../types';
 import { resolveBackground } from '../utils/TimeHelper';
 import { logger } from '../utils/logger';
 
@@ -22,11 +22,23 @@ export class LocationManager {
     }
   }
 
-  /** Set the location link graph */
+  /** Set the location link graph (replaces all existing links) */
   setLinks(links: LocationLink[]): void {
     this.links = links;
   }
 
+  /** Add directed links from one location to one or more others (additive) */
+  link(
+    fromId: string,
+    toIds: string | string[],
+    options?: { condition?: (state: VylosGameState) => boolean },
+  ): void {
+    const targets = Array.isArray(toIds) ? toIds : [toIds];
+    for (const toId of targets) {
+      this.links.push({ from: fromId, to: toId, ...options });
+    }
+  }
+
   /** Get a location by ID */
   get(id: string): VylosLocation | undefined {
     return this.locations.get(id);

package/src/engine/types/checkpoint.ts

@@ -15,6 +15,8 @@ export interface Checkpoint {
   dialogue?: DialogueState | null;
   /** Background path at this point */
   background?: string | null;
+  /** Foreground path at this point */
+  foreground?: string | null;
   /** Available choice options at this step (for history redo) */
   choiceOptions?: ChoiceOption[];
 }

package/src/engine/types/config.ts

@@ -6,4 +6,6 @@ export interface VylosConfig {
   defaultLanguage: string;
   defaultLocation: string;
   resolution: { width: number; height: number };
+  /** The game time at which new games begin. Defaults to 12 if not specified. */
+  startGameTime?: number;
 }

package/src/engine/types/plugin.ts

@@ -1,5 +1,26 @@
 import type { DependencyContainer } from 'tsyringe';
-import type { Component } from 'vue';
+import type { Component, Ref } from 'vue';
+import type { VylosGameState } from './game-state';
+
+/**
+ * Minimal contract for a game state store.
+ * Compatible with the default `useGameStateStore` return type.
+ * Projects with custom game state can implement this with additional properties.
+ */
+export interface VylosGameStore {
+  /** Reactive game state ref */
+  state: Ref<VylosGameState>;
+  /** Get current (unwrapped) game state */
+  getState(): VylosGameState;
+  /** Replace the entire game state */
+  setState(newState: VylosGameState): void;
+  /** Deep-clone the current state for saving */
+  getSnapshot(): VylosGameState;
+  /** Restore a previously saved snapshot */
+  restoreSnapshot(snapshot: VylosGameState): void;
+  /** Reset to default initial state */
+  $reset(): void;
+}
 
 /** Plugin interface for project-level engine customization */
 export interface VylosPlugin {
@@ -8,4 +29,11 @@ export interface VylosPlugin {
 
   /** Override Vue components by component ID */
   components?: Record<string, Component>;
+
+  /**
+   * Provide a custom Pinia game state store factory.
+   * When set, setupVylos will use this instead of the default `useGameStateStore`.
+   * Useful for projects that extend VylosGameState with additional fields.
+   */
+  gameStore?(pinia?: any): VylosGameStore;
 }

package/src/index.ts

@@ -20,6 +20,10 @@ export { assetUrl } from './utils/assetUrl';
 export { useEngineStateStore } from './stores/engineState';
 export { useGameStateStore } from './stores/gameState';
 
+// Setup
+export { setupVylos } from './setup';
+export type { SetupOptions } from './setup';
+
 // Core engine
 export { Engine } from './engine/core/Engine';
 export type { EngineLoopCallbacks } from './engine/core/Engine';

package/src/setup.ts

@@ -0,0 +1,211 @@
+import 'reflect-metadata';
+import { createApp, watch, toRaw } from 'vue';
+import { createPinia } from 'pinia';
+import GameShell from './components/app/GameShell.vue';
+import { createEngine } from './engine/core/EngineFactory';
+import { useEngineStateStore } from './stores/engineState';
+import { useGameStateStore } from './stores/gameState';
+import { ENGINE_INJECT_KEY } from './composables/useEngine';
+import { CONFIG_INJECT_KEY } from './composables/useConfig';
+import { LocationManager } from './engine/managers/LocationManager';
+import { ActionManager } from './engine/managers/ActionManager';
+import { LanguageManager } from './engine/managers/LanguageManager';
+import { EnginePhase } from './engine/types/engine';
+import type { VylosConfig } from './engine/types/config';
+import type { VylosPlugin, VylosGameStore } from './engine/types/plugin';
+import type { VylosLocation } from './engine/types/locations';
+import type { VylosEvent, TextEntry } from './engine/types/events';
+import type { VylosAction } from './engine/types/actions';
+import type { VylosCharacter } from './engine/types/dialogue';
+import type { EventRunnerCallbacks } from './engine/core/EventRunner';
+import type { EngineLoopCallbacks } from './engine/core/Engine';
+
+export interface SetupOptions {
+  config: VylosConfig;
+  plugin?: VylosPlugin;
+  locations?: VylosLocation[];
+  events?: VylosEvent[];
+  actions?: VylosAction[];
+  initLinks?: (lm: LocationManager) => void;
+  /** When true, skip the MainMenu phase and go directly to Running (triggers startGame). */
+  skipMainMenu?: boolean;
+}
+
+/**
+ * One-call setup function that replaces all main.ts boilerplate.
+ * Creates the Vue app, Pinia stores, engine, and wires everything together.
+ */
+export function setupVylos(options: SetupOptions): void {
+  const { config, plugin, locations = [], events = [], actions = [], initLinks, skipMainMenu = false } = options;
+
+  const app = createApp(GameShell);
+  const pinia = createPinia();
+  app.use(pinia);
+
+  const gameStore: VylosGameStore = plugin?.gameStore
+    ? plugin.gameStore(pinia)
+    : useGameStateStore(pinia);
+  const engineState = useEngineStateStore(pinia);
+
+  const languageManager = config.languages.length > 1
+    ? createLanguageManager(config)
+    : null;
+  const resolveText = buildResolveText(languageManager, config);
+
+  const locationManager = new LocationManager();
+  locationManager.registerAll(locations);
+
+  if (locations.length > 0 && !locationManager.has(config.defaultLocation)) {
+    console.error(
+      `[Vylos] Default location "${config.defaultLocation}" is not registered. ` +
+      `Registered locations: [${locationManager.getAll().map(l => l.id).join(', ')}]. ` +
+      `Check your vylos.config.ts defaultLocation value.`
+    );
+  }
+
+  const actionManager = new ActionManager();
+  actionManager.registerAll(actions);
+
+  const callbacks = buildCallbacks(engineState, gameStore, locationManager, resolveText);
+  const engine = createEngine({ callbacks, projectId: config.id, plugin });
+
+  app.provide(ENGINE_INJECT_KEY, engine);
+  app.provide(CONFIG_INJECT_KEY, config);
+  app.mount('#app');
+
+  if (initLinks) {
+    initLinks(locationManager);
+  }
+
+  if (skipMainMenu) {
+    engineState.setPhase(EnginePhase.Running);
+    startGame();
+  } else {
+    engineState.setPhase(EnginePhase.MainMenu);
+
+    const stopWatch = watch(() => engineState.phase, (newPhase) => {
+      if (newPhase === EnginePhase.Running) {
+        stopWatch();
+        startGame();
+      }
+    });
+  }
+
+  function startGame(): void {
+    const startGameTime = config.startGameTime ?? 12;
+    gameStore.setState({
+      ...gameStore.getState(),
+      locationId: config.defaultLocation,
+      gameTime: startGameTime,
+    });
+
+    engineState.setLocation(config.defaultLocation);
+
+    const bg = locationManager.resolveBackground(config.defaultLocation, startGameTime);
+    if (bg) engineState.setBackground(bg);
+
+    const loopCallbacks: EngineLoopCallbacks = {
+      onTick(state) {
+        const locs = locationManager.getAccessibleFrom(state.locationId, state);
+        engineState.setLocations(locs.map(l => ({
+          id: l.id,
+          name: resolveText(l.name),
+          accessible: true,
+        })));
+
+        const acts = actionManager.getAvailable(state.locationId, state);
+        engineState.setActions(acts.map(a => ({
+          id: a.id,
+          label: resolveText(a.label),
+          locationId: a.locationId ?? '',
+        })));
+
+        engineState.setDrawableEvents(
+          engine.eventManager.getDrawableEvents(state, resolveText),
+        );
+
+        const bg = locationManager.resolveBackground(state.locationId, state.gameTime);
+        if (bg) engineState.setBackground(bg);
+      },
+      onAction(actionId, state) {
+        actionManager.execute(actionId, state);
+      },
+    };
+
+    engine.run(events, () => gameStore.getState(), loopCallbacks).catch(console.error);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createLanguageManager(config: VylosConfig): LanguageManager {
+  const lm = new LanguageManager();
+  lm.setLanguage(config.defaultLanguage ?? config.languages[0]);
+  return lm;
+}
+
+function buildResolveText(
+  languageManager: LanguageManager | null,
+  config: VylosConfig,
+): (entry: string | TextEntry) => string {
+  if (languageManager) {
+    return (entry) => languageManager.resolve(entry);
+  }
+  const lang = config.defaultLanguage ?? 'en';
+  return (entry) =>
+    typeof entry === 'string'
+      ? entry
+      : entry[lang] ?? Object.values(entry)[0] ?? '';
+}
+
+type EngineStateStore = ReturnType<typeof useEngineStateStore>;
+
+function buildCallbacks(
+  engineState: EngineStateStore,
+  gameStore: VylosGameStore,
+  locationManager: LocationManager,
+  resolveText: (entry: string | TextEntry) => string,
+): EventRunnerCallbacks {
+  return {
+    onSay(text: string, speaker: VylosCharacter | null) {
+      engineState.setDialogue({ text, speaker, isNarration: !speaker });
+    },
+    onChoice(options) {
+      engineState.setChoices({ prompt: null, options });
+    },
+    onSetBackground(path) {
+      engineState.setBackground(path);
+    },
+    onSetForeground(path) {
+      engineState.setForeground(path);
+    },
+    onShowOverlay(componentId, props) {
+      engineState.setOverlay(componentId, props);
+    },
+    onHideOverlay() {
+      engineState.setOverlay(null);
+    },
+    onSetLocation(locationId) {
+      const state = gameStore.getState();
+      state.locationId = locationId;
+      engineState.setLocation(locationId);
+      const bg = locationManager.resolveBackground(locationId, state.gameTime);
+      if (bg) engineState.setBackground(bg);
+    },
+    onClear() {
+      engineState.setDialogue(null);
+      engineState.setChoices(null);
+    },
+    resolveText(entry) {
+      return resolveText(entry);
+    },
+    getState() {
+      return JSON.parse(JSON.stringify(gameStore.getState()));
+    },
+    setState(newState) {
+      gameStore.setState(newState);
+    },
+  };
+}

package/tests/bootstrap.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { LocationManager } from '../src/engine/managers/LocationManager';
+import type { VylosLocation, VylosGameState } from '../src/engine/types';
+
+function makeState(overrides: Partial<VylosGameState> = {}): VylosGameState {
+  return {
+    locationId: 'room_a',
+    gameTime: 12,
+    flags: {},
+    counters: {},
+    player: { id: 'player', name: 'Player' },
+    inventories: {},
+    ...overrides,
+  };
+}
+
+const roomA: VylosLocation = {
+  id: 'room_a',
+  name: 'Room A',
+  backgrounds: [{ path: '/room_a.jpg' }],
+};
+
+const roomB: VylosLocation = {
+  id: 'room_b',
+  name: 'Room B',
+  backgrounds: [{ path: '/room_b.jpg' }],
+};
+
+const roomC: VylosLocation = {
+  id: 'room_c',
+  name: 'Room C',
+  backgrounds: [{ path: '/room_c.jpg' }],
+};
+
+const roomD: VylosLocation = {
+  id: 'room_d',
+  name: 'Room D',
+  backgrounds: [{ path: '/room_d.jpg' }],
+};
+
+describe('LocationManager.link()', () => {
+  let lm: LocationManager;
+
+  beforeEach(() => {
+    lm = new LocationManager();
+    lm.registerAll([roomA, roomB, roomC, roomD]);
+  });
+
+  it('creates directed links from one location to multiple targets', () => {
+    lm.link('room_a', ['room_b', 'room_c']);
+
+    const state = makeState();
+    const accessible = lm.getAccessibleFrom('room_a', state);
+    expect(accessible.map(l => l.id)).toEqual(['room_b', 'room_c']);
+  });
+
+  it('creates a single directed link with string shorthand', () => {
+    lm.link('room_a', 'room_b');
+
+    const state = makeState();
+    const accessible = lm.getAccessibleFrom('room_a', state);
+    expect(accessible.map(l => l.id)).toEqual(['room_b']);
+  });
+
+  it('creates a link with a condition', () => {
+    lm.link('room_a', ['room_b'], {
+      condition: (state) => state.flags['has_key'] === true,
+    });
+
+    const stateWithout = makeState();
+    expect(lm.getAccessibleFrom('room_a', stateWithout)).toHaveLength(0);
+
+    const stateWith = makeState({ flags: { has_key: true } });
+    expect(lm.getAccessibleFrom('room_a', stateWith).map(l => l.id)).toEqual(['room_b']);
+  });
+
+  it('is additive across multiple calls', () => {
+    lm.link('room_a', 'room_b');
+    lm.link('room_a', 'room_c');
+
+    const state = makeState();
+    const accessible = lm.getAccessibleFrom('room_a', state);
+    expect(accessible.map(l => l.id)).toEqual(['room_b', 'room_c']);
+  });
+
+  it('accumulates links alongside setLinks()', () => {
+    // link() first
+    lm.link('room_a', 'room_b');
+
+    // setLinks() replaces everything
+    lm.setLinks([{ from: 'room_a', to: 'room_c' }]);
+
+    const state = makeState();
+    // After setLinks, the link() entry is gone — only room_c remains
+    expect(lm.getAccessibleFrom('room_a', state).map(l => l.id)).toEqual(['room_c']);
+
+    // Now link() adds on top of the setLinks result
+    lm.link('room_a', 'room_d');
+    expect(lm.getAccessibleFrom('room_a', state).map(l => l.id)).toEqual(['room_c', 'room_d']);
+  });
+
+  it('link() after setLinks() accumulates on existing links', () => {
+    lm.setLinks([
+      { from: 'room_a', to: 'room_b' },
+      { from: 'room_b', to: 'room_a' },
+    ]);
+
+    lm.link('room_a', 'room_c');
+
+    const state = makeState();
+    const accessible = lm.getAccessibleFrom('room_a', state);
+    expect(accessible.map(l => l.id)).toEqual(['room_b', 'room_c']);
+  });
+
+  it('does not create reverse links (directed only)', () => {
+    lm.link('room_a', 'room_b');
+
+    const state = makeState({ locationId: 'room_b' });
+    const accessible = lm.getAccessibleFrom('room_b', state);
+    expect(accessible).toHaveLength(0);
+  });
+
+  it('handles mixed conditional and unconditional links', () => {
+    lm.link('room_a', 'room_b');
+    lm.link('room_a', ['room_c'], {
+      condition: (state) => state.gameTime >= 18,
+    });
+    lm.link('room_a', 'room_d');
+
+    const daytime = makeState({ gameTime: 12 });
+    expect(lm.getAccessibleFrom('room_a', daytime).map(l => l.id)).toEqual(['room_b', 'room_d']);
+
+    const nighttime = makeState({ gameTime: 20 });
+    expect(lm.getAccessibleFrom('room_a', nighttime).map(l => l.id)).toEqual([
+      'room_b',
+      'room_c',
+      'room_d',
+    ]);
+  });
+
+  it('clear() removes links added via link()', () => {
+    lm.link('room_a', ['room_b', 'room_c']);
+    lm.clear();
+
+    const state = makeState();
+    // Locations are gone too, so getAccessibleFrom returns empty
+    expect(lm.getAccessibleFrom('room_a', state)).toHaveLength(0);
+  });
+});
+
+/**
+ * bootstrapVylos unit tests are intentionally omitted.
+ *
+ * bootstrapVylos() is a high-level orchestration function that:
+ * - Creates a Vue application with createApp(GameShell)
+ * - Sets up Pinia stores
+ * - Creates the engine via createEngine() (which uses tsyringe DI)
+ * - Mounts the app to #app
+ * - Sets up a phase watcher to start the game loop
+ *
+ * Testing it in isolation would require mocking nearly every dependency
+ * (Vue createApp, Pinia, GameShell component, createEngine, stores, etc.),
+ * which would produce brittle tests that test the mock wiring rather than
+ * real behavior. The function's correctness is better validated through:
+ *
+ * 1. Integration tests via the example projects (pnpm dev:basic, pnpm dev:romance)
+ * 2. Unit tests of the individual pieces it orchestrates (LocationManager, ActionManager,
+ *    EventRunner, stores, etc.) which are already well-covered
+ * 3. The helper functions (buildResolveText, buildCallbacks) are private to the module
+ *    and tested indirectly through their integration with the managers and stores
+ */