@vylos/core 0.1.0

package/src/components/menu/TopBar.vue

@@ -0,0 +1,65 @@
+<template>
+  <div class="topbar">
+    <div class="topbar__inner">
+      <span v-if="locationName" class="topbar__item">&#128205; {{ locationName }}</span>
+      <span class="topbar__separator"></span>
+      <span class="topbar__item">&#9200; {{ gameTimeFormatted }}</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useEngineStateStore } from '../../stores/engineState';
+import { useGameStateStore } from '../../stores/gameState';
+
+const engineState = useEngineStateStore();
+const gameState = useGameStateStore();
+
+const locationName = computed(() => engineState.currentLocationId ?? '');
+
+const gameTimeFormatted = computed(() => {
+  const t = gameState.state.gameTime % 24;
+  const h = Math.floor(t);
+  const m = Math.round((t - h) * 60);
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`;
+});
+</script>
+
+<style scoped>
+.topbar {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 25;
+  display: flex;
+  justify-content: center;
+  padding: 1.2cqh 2cqw;
+  pointer-events: none;
+}
+
+.topbar__inner {
+  display: flex;
+  align-items: center;
+  gap: 1.5cqw;
+  padding: 0.8cqh 2cqw;
+  background: rgba(0, 0, 0, 0.3);
+  backdrop-filter: blur(4px);
+  border: 1px solid rgba(255, 255, 255, 0.15);
+  border-radius: 0.8cqw;
+  pointer-events: auto;
+}
+
+.topbar__item {
+  color: rgba(255, 255, 255, 0.85);
+  font-size: 1.6cqw;
+  white-space: nowrap;
+}
+
+.topbar__separator {
+  width: 1px;
+  height: 2cqh;
+  background: rgba(255, 255, 255, 0.2);
+}
+</style>

package/src/composables/useConfig.ts

@@ -0,0 +1,4 @@
+import type { InjectionKey } from 'vue';
+import type { VylosConfig } from '../engine/types';
+
+export const CONFIG_INJECT_KEY: InjectionKey<VylosConfig> = Symbol('vylos-config');

package/src/composables/useEngine.ts

@@ -0,0 +1,16 @@
+import { inject } from 'vue';
+import type { Engine } from '../engine/core/Engine';
+
+export const ENGINE_INJECT_KEY = 'vylos-engine';
+
+/**
+ * Composable that provides access to the engine instance via inject.
+ * Must be used inside a component that is a descendant of GameShell.
+ */
+export function useEngine(): Engine {
+  const engine = inject<Engine>(ENGINE_INJECT_KEY);
+  if (!engine) {
+    throw new Error('[Vylos] useEngine() called outside of GameShell context. Make sure the component is a descendant of GameShell.');
+  }
+  return engine;
+}

package/src/composables/useGameState.ts

@@ -0,0 +1,9 @@
+import { useGameStateStore } from '../stores/gameState';
+
+/**
+ * Composable wrapping the gameState Pinia store for reactive access.
+ */
+export function useGameState() {
+  const store = useGameStateStore();
+  return store;
+}

package/src/composables/useLanguage.ts

@@ -0,0 +1,31 @@
+import { ref, computed } from 'vue';
+import type { TextEntry } from '../engine/types';
+
+const currentLanguage = ref<string>('en');
+
+/**
+ * Composable for language management.
+ */
+export function useLanguage() {
+  const language = computed(() => currentLanguage.value);
+
+  function setLanguage(lang: string): void {
+    currentLanguage.value = lang;
+  }
+
+  /**
+   * Resolve a TextEntry to a string for the current language.
+   * Falls back to 'en', then to the first available key.
+   */
+  function resolveText(entry: string | TextEntry): string {
+    if (typeof entry === 'string') return entry;
+    return (
+      entry[currentLanguage.value] ??
+      entry['en'] ??
+      Object.values(entry)[0] ??
+      ''
+    );
+  }
+
+  return { language, setLanguage, resolveText };
+}

package/src/engine/core/CheckpointManager.ts

@@ -0,0 +1,122 @@
+import { toRaw } from 'vue';
+import type { BaseGameState, Checkpoint, CheckpointType, ChoiceOption } from '../types';
+import type { DialogueState } from '../types/engine';
+
+export interface CaptureDisplayData {
+  dialogue?: DialogueState | null;
+  background?: string | null;
+  choiceOptions?: ChoiceOption[];
+}
+
+/**
+ * Manages checkpoints for event execution and rollback.
+ * Each interaction point (say, choice, wait) creates a checkpoint
+ * containing a deep clone of game state + the result of that interaction.
+ */
+export class CheckpointManager {
+  private checkpoints: Checkpoint[] = [];
+  private replayIndex = -1;
+
+  /** Whether we're currently in replay mode (fast-forwarding during rollback) */
+  get isReplaying(): boolean {
+    return this.replayIndex >= 0 && this.replayIndex < this.checkpoints.length;
+  }
+
+  /** Current replay step (or -1 if not replaying) */
+  get currentReplayStep(): number {
+    return this.replayIndex;
+  }
+
+  /** Total number of checkpoints stored */
+  get count(): number {
+    return this.checkpoints.length;
+  }
+
+  /** Get checkpoint at a specific index */
+  getAt(index: number): Checkpoint | undefined {
+    return this.checkpoints[index];
+  }
+
+  /** Record a checkpoint at the current interaction point */
+  capture(gameState: BaseGameState, type: CheckpointType, choiceResult?: string, display?: CaptureDisplayData): void {
+    const checkpoint: Checkpoint = {
+      step: this.checkpoints.length,
+      gameState: structuredClone(toRaw(gameState)),
+      type,
+      choiceResult,
+      dialogue: display?.dialogue ? structuredClone(toRaw(display.dialogue)) : undefined,
+      background: display?.background,
+      choiceOptions: display?.choiceOptions ? structuredClone(toRaw(display.choiceOptions)) : undefined,
+    };
+
+    // If replaying past the current index, trim future checkpoints
+    if (this.replayIndex >= 0) {
+      this.checkpoints.length = this.replayIndex;
+      this.replayIndex = -1;
+    }
+
+    this.checkpoints.push(checkpoint);
+  }
+
+  /** Get the stored choice result for the current replay step (or undefined) */
+  getReplayChoiceResult(): string | undefined {
+    if (!this.isReplaying) return undefined;
+    return this.checkpoints[this.replayIndex]?.choiceResult;
+  }
+
+  /** Advance replay index by one step. Returns false if replay is done. */
+  advanceReplay(): boolean {
+    if (!this.isReplaying) return false;
+    this.replayIndex++;
+    return this.replayIndex < this.checkpoints.length;
+  }
+
+  /** Get game state snapshot at a specific step */
+  getStateAt(step: number): BaseGameState | undefined {
+    const checkpoint = this.checkpoints[step];
+    if (!checkpoint) return undefined;
+    return structuredClone(checkpoint.gameState);
+  }
+
+  /** Get all checkpoints (for save/load) */
+  getAll(): Checkpoint[] {
+    return this.checkpoints.map(c => structuredClone(c));
+  }
+
+  /** Prepare for rollback: set replay index to target step */
+  prepareRollback(targetStep: number): BaseGameState | undefined {
+    if (targetStep < 0 || targetStep >= this.checkpoints.length) return undefined;
+    this.replayIndex = 0;
+    // Trim checkpoints after target (re-execution will recreate them)
+    const targetState = structuredClone(this.checkpoints[targetStep].gameState);
+    this.checkpoints.length = targetStep;
+    return targetState;
+  }
+
+  /** Update the stored choice result at a specific step */
+  updateChoiceAt(step: number, newChoice: string): void {
+    if (step >= 0 && step < this.checkpoints.length) {
+      this.checkpoints[step].choiceResult = newChoice;
+    }
+  }
+
+  /** Set replay from beginning, trimming checkpoints after endStep */
+  setReplayTo(endStep: number): void {
+    this.replayIndex = 0;
+    if (endStep < this.checkpoints.length) {
+      this.checkpoints.length = endStep;
+    }
+  }
+
+  /** Clear all checkpoints (new event or new game) */
+  clear(): void {
+    this.checkpoints = [];
+    this.replayIndex = -1;
+  }
+
+  /** Restore checkpoints from save data */
+  restore(checkpoints: Checkpoint[]): void {
+    this.checkpoints = structuredClone(checkpoints);
+    this.replayIndex = -1;
+  }
+}

package/src/engine/core/Engine.ts

@@ -0,0 +1,272 @@
+import type { VylosEvent, BaseGameState, Checkpoint, SaveSlot } from '../types';
+import { EventManager } from '../managers/EventManager';
+import { HistoryManager } from '../managers/HistoryManager';
+import { NavigationManager, NavigationAction } from '../managers/NavigationManager';
+import { SaveManager } from '../managers/SaveManager';
+import { SettingsManager } from '../managers/SettingsManager';
+import { EventRunner } from './EventRunner';
+import { JumpSignal } from '../errors/JumpSignal';
+import { logger } from '../utils/logger';
+
+export interface EngineLoopCallbacks {
+  /** Called each loop iteration (update UI: available locations, actions, background) */
+  onTick?(state: BaseGameState): void;
+  /** Called when player selects an action */
+  onAction?(actionId: string, state: BaseGameState): void;
+}
+
+export interface EngineDeps {
+  eventManager: EventManager;
+  historyManager: HistoryManager;
+  navigationManager: NavigationManager;
+  eventRunner: EventRunner;
+  saveManager: SaveManager;
+  settingsManager: SettingsManager;
+}
+
+/**
+ * Main engine orchestrator.
+ * Runs the game loop: evaluate events → execute → wait for navigation → repeat.
+ */
+export class Engine {
+  readonly eventManager: EventManager;
+  readonly historyManager: HistoryManager;
+  readonly navigationManager: NavigationManager;
+  readonly eventRunner: EventRunner;
+  readonly saveManager: SaveManager;
+  readonly settingsManager: SettingsManager;
+  private running = false;
+
+  /** Pending mid-event resume after load */
+  private pendingResume: {
+    eventId: string;
+    checkpoints: Checkpoint[];
+    initialState: BaseGameState;
+  } | null = null;
+
+  /** Flag to skip event lock/push when interrupted by a load */
+  private loadInterrupted = false;
+
+  constructor(deps: EngineDeps) {
+    this.eventManager = deps.eventManager;
+    this.historyManager = deps.historyManager;
+    this.navigationManager = deps.navigationManager;
+    this.eventRunner = deps.eventRunner;
+    this.saveManager = deps.saveManager;
+    this.settingsManager = deps.settingsManager;
+  }
+
+  /** Register events and start the game loop */
+  async run(events: VylosEvent[], getState: () => BaseGameState, loop?: EngineLoopCallbacks): Promise<void> {
+    this.eventManager.registerAll(events);
+    this.running = true;
+
+    logger.info('Engine started');
+
+    while (this.running) {
+      // Handle pending load resume before anything else
+      if (this.pendingResume) {
+        this.loadInterrupted = false;
+        await this.handleResume(getState);
+        continue;
+      }
+
+      const state = getState();
+
+      // Update UI (locations, actions, background)
+      loop?.onTick?.(state);
+
+      // Evaluate event conditions
+      this.eventManager.evaluate(state);
+
+      // Get next unlocked event
+      const event = this.eventManager.getNextUnlocked(state);
+
+      if (event) {
+        await this.executeEvent(event, getState);
+        continue; // Re-evaluate after event execution
+      }
+
+      if (!this.running) break;
+
+      // Wait for navigation input
+      const nav = await this.navigationManager.waitForNavigation();
+
+      switch (nav.action) {
+        case NavigationAction.Back:
+          this.handleBack();
+          break;
+        case NavigationAction.Forward:
+          this.handleForward();
+          break;
+        case NavigationAction.Continue:
+          // Continue to next loop iteration
+          break;
+        case NavigationAction.Location:
+          if (nav.payload) {
+            const s = getState();
+            s.locationId = nav.payload;
+          }
+          break;
+        case NavigationAction.Action:
+          if (nav.payload) {
+            loop?.onAction?.(nav.payload, getState());
+          }
+          break;
+        case NavigationAction.DrawableEvent:
+          if (nav.payload) {
+            const drawableEvent = this.eventManager.get(nav.payload);
+            if (drawableEvent) {
+              await this.executeEvent(drawableEvent, getState);
+            }
+          }
+          break;
+      }
+    }
+
+    logger.info('Engine stopped');
+  }
+
+  /**
+   * Load a save and resume execution.
+   * Restores game state, history, event lock state, and sets up mid-event resume if needed.
+   */
+  loadSave(saveData: SaveSlot, setState: (state: BaseGameState) => void): void {
+    // Restore game state
+    setState(JSON.parse(JSON.stringify(saveData.gameState)));
+
+    // Restore event lock state
+    this.eventManager.resetAll();
+    if (saveData.lockedEventIds) {
+      this.eventManager.restoreLockedIds(saveData.lockedEventIds);
+    }
+
+    // Restore history
+    if (saveData.history) {
+      this.historyManager.restore(saveData.history, saveData.historyIndex ?? -1);
+    } else {
+      this.historyManager.clear();
+    }
+
+    // Set up mid-event resume if saved during an event
+    if (saveData.eventId && saveData.checkpoints?.length && saveData.initialState) {
+      this.pendingResume = {
+        eventId: saveData.eventId,
+        checkpoints: saveData.checkpoints,
+        initialState: saveData.initialState,
+      };
+    }
+
+    // Interrupt current execution so the loop picks up the new state
+    this.loadInterrupted = true;
+    this.eventRunner.interrupt('load');
+    this.navigationManager.cancel();
+  }
+
+  /** Execute a single event, handling jumps */
+  private async executeEvent(event: VylosEvent, getState: () => BaseGameState): Promise<void> {
+    let currentEvent: VylosEvent | undefined = event;
+
+    while (currentEvent) {
+      this.eventManager.setRunning(currentEvent.id);
+      logger.debug(`Executing event: ${currentEvent.id}`);
+
+      try {
+        await this.eventRunner.executeEvent(currentEvent);
+
+        // Skip lock/push if interrupted by a load
+        if (this.loadInterrupted) return;
+
+        // Event completed successfully
+        const state = getState();
+        this.eventManager.setLocked(currentEvent.id, 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
+          const state = getState();
+          this.eventManager.setLocked(currentEvent.id, state);
+          this.historyManager.push(currentEvent.id, this.eventRunner.checkpoints.getAll());
+
+          const target = this.eventManager.get(error.targetEventId);
+          if (target) {
+            logger.debug(`Jump to: ${error.targetEventId}`);
+            currentEvent = target;
+          } else {
+            logger.error(`Jump target not found: ${error.targetEventId}`);
+            currentEvent = undefined;
+          }
+        } else {
+          logger.error('Event execution error:', error);
+          currentEvent = undefined;
+        }
+      }
+    }
+  }
+
+  /** Handle resuming a mid-event save */
+  private async handleResume(getState: () => BaseGameState): Promise<void> {
+    const resume = this.pendingResume!;
+    this.pendingResume = null;
+
+    const event = this.eventManager.get(resume.eventId);
+    if (!event) {
+      logger.error(`Resume: event not found: ${resume.eventId}`);
+      return;
+    }
+
+    this.eventManager.setRunning(resume.eventId);
+    this.eventRunner.checkpoints.restore(resume.checkpoints);
+    logger.debug(`Resuming event: ${resume.eventId} (${resume.checkpoints.length} checkpoints)`);
+
+    try {
+      await this.eventRunner.resumeEvent(event, resume.initialState);
+
+      if (this.loadInterrupted) return;
+
+      const state = getState();
+      this.eventManager.setLocked(resume.eventId, 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.historyManager.push(resume.eventId, this.eventRunner.checkpoints.getAll());
+
+        const target = this.eventManager.get(error.targetEventId);
+        if (target) {
+          logger.debug(`Resume jump to: ${error.targetEventId}`);
+          await this.executeEvent(target, getState);
+        }
+      } else {
+        logger.error('Resume execution error:', error);
+      }
+    }
+  }
+
+  private handleBack(): void {
+    const entry = this.historyManager.goBack();
+    if (entry) {
+      logger.debug(`History back: ${entry.eventId}`);
+    }
+  }
+
+  private handleForward(): void {
+    const entry = this.historyManager.goForward();
+    if (entry) {
+      logger.debug(`History forward: ${entry.eventId}`);
+    }
+  }
+
+  /** Stop the engine loop */
+  stop(): void {
+    this.running = false;
+    this.eventRunner.interrupt('engine stopped');
+    this.navigationManager.cancel();
+  }
+}

package/src/engine/core/EngineFactory.ts

@@ -0,0 +1,102 @@
+import 'reflect-metadata';
+import { container as globalContainer, type DependencyContainer } from 'tsyringe';
+import type { VylosPlugin } from '../types';
+import type { Component } from 'vue';
+import { EventManager } from '../managers/EventManager';
+import { HistoryManager } from '../managers/HistoryManager';
+import { NavigationManager } from '../managers/NavigationManager';
+import { WaitManager } from '../managers/WaitManager';
+import { SaveManager } from '../managers/SaveManager';
+import { SettingsManager } from '../managers/SettingsManager';
+import { EventRunner, type EventRunnerCallbacks } from './EventRunner';
+import { CheckpointManager } from './CheckpointManager';
+import { VylosStorage } from '../storage/VylosStorage';
+import { Engine } from './Engine';
+
+/** Tokens used for DI registration */
+export const DI_TOKENS = {
+  EventManager: 'EventManager',
+  HistoryManager: 'HistoryManager',
+  NavigationManager: 'NavigationManager',
+  WaitManager: 'WaitManager',
+  CheckpointManager: 'CheckpointManager',
+  EventRunner: 'EventRunner',
+  Engine: 'Engine',
+} as const;
+
+/** Component override map (separate from DI) */
+const componentOverrides = new Map<string, Component>();
+
+/** Register all default managers in a DI container */
+function registerDefaults(c: DependencyContainer): void {
+  c.register(DI_TOKENS.EventManager, { useClass: EventManager });
+  c.register(DI_TOKENS.HistoryManager, { useClass: HistoryManager });
+  c.register(DI_TOKENS.NavigationManager, { useClass: NavigationManager });
+  c.register(DI_TOKENS.WaitManager, { useClass: WaitManager });
+  c.register(DI_TOKENS.CheckpointManager, { useClass: CheckpointManager });
+}
+
+export interface CreateEngineOptions {
+  /** Project plugin for DI overrides and component overrides */
+  plugin?: VylosPlugin;
+  /** Callbacks for EventRunner (UI integration) */
+  callbacks: EventRunnerCallbacks;
+  /** Project ID for storage isolation (default: 'default') */
+  projectId?: string;
+}
+
+/**
+ * Create and wire an Engine instance with all managers.
+ * Projects can provide a plugin to override any manager.
+ */
+export function createEngine(options: CreateEngineOptions): Engine {
+  // Create a child container so tests/multiple instances don't conflict
+  const childContainer = globalContainer.createChildContainer();
+
+  // Register defaults
+  registerDefaults(childContainer);
+
+  // Apply plugin overrides (plugin can re-register any token)
+  if (options.plugin?.setup) {
+    options.plugin.setup(childContainer);
+  }
+
+  // Register component overrides
+  if (options.plugin?.components) {
+    for (const [id, component] of Object.entries(options.plugin.components)) {
+      componentOverrides.set(id, component);
+    }
+  }
+
+  // Resolve managers
+  const eventManager = childContainer.resolve<EventManager>(DI_TOKENS.EventManager);
+  const historyManager = childContainer.resolve<HistoryManager>(DI_TOKENS.HistoryManager);
+  const navigationManager = childContainer.resolve<NavigationManager>(DI_TOKENS.NavigationManager);
+
+  // EventRunner needs callbacks, so we construct it directly
+  const eventRunner = new EventRunner(options.callbacks);
+
+  // Storage + persistence managers
+  const storage = new VylosStorage(options.projectId ?? 'default');
+  const saveManager = new SaveManager(storage);
+  const settingsManager = new SettingsManager(storage);
+
+  return new Engine({
+    eventManager,
+    historyManager,
+    navigationManager,
+    eventRunner,
+    saveManager,
+    settingsManager,
+  });
+}
+
+/** Get a component override by ID (returns undefined if no override) */
+export function getComponentOverride(id: string): Component | undefined {
+  return componentOverrides.get(id);
+}
+
+/** Clear all component overrides (for testing) */
+export function clearComponentOverrides(): void {
+  componentOverrides.clear();
+}