@vylos/core 0.1.0

package/src/engine/managers/EventManager.ts

@@ -0,0 +1,166 @@
+import type { VylosEvent, BaseGameState, DrawableEventEntry } from '../types';
+import { EventStatus } from '../types';
+import { logger } from '../utils/logger';
+
+interface EventEntry {
+  event: VylosEvent;
+  status: EventStatus;
+}
+
+/**
+ * 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
+ * - Running: currently executing
+ * - Locked: completed (won't trigger again)
+ */
+export class EventManager {
+  private events = new Map<string, EventEntry>();
+
+  /** Register an event */
+  register(event: VylosEvent): void {
+    this.events.set(event.id, {
+      event,
+      status: EventStatus.NotReady,
+    });
+    logger.debug(`Event registered: ${event.id}`);
+  }
+
+  /** Register multiple events */
+  registerAll(events: VylosEvent[]): void {
+    for (const event of events) {
+      this.register(event);
+    }
+  }
+
+  /** Get an event by ID */
+  get(id: string): VylosEvent | undefined {
+    return this.events.get(id)?.event;
+  }
+
+  /** Get event status */
+  getStatus(id: string): EventStatus | undefined {
+    return this.events.get(id)?.status;
+  }
+
+  /** Evaluate conditions and update statuses. Returns newly unlocked events. */
+  evaluate(state: BaseGameState): VylosEvent[] {
+    const unlocked: 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;
+
+      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}`);
+      }
+    }
+
+    return unlocked;
+  }
+
+  /** Get the next unlocked event matching the current location (first registered wins). Skips drawable events. */
+  getNextUnlocked(state: BaseGameState): VylosEvent | undefined {
+    for (const entry of this.events.values()) {
+      if (entry.status !== EventStatus.Unlocked) continue;
+      if (entry.event.draw) continue; // Drawable events don't auto-trigger
+      if (entry.event.locationId && entry.event.locationId !== state.locationId) continue;
+      return entry.event;
+    }
+    return undefined;
+  }
+
+  /** Get all unlocked drawable events at the current location */
+  getDrawableEvents(state: BaseGameState, 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.event.draw) continue;
+      if (entry.event.locationId && entry.event.locationId !== state.locationId) continue;
+      const draw = entry.event.draw;
+      const label = typeof draw.label === 'string'
+        ? draw.label
+        : resolveText?.(draw.label) ?? Object.values(draw.label)[0] ?? entry.event.id;
+      result.push({
+        id: entry.event.id,
+        label,
+        position: draw.position ?? 'center',
+        icon: draw.icon,
+      });
+    }
+    return result;
+  }
+
+  /** Mark event as running */
+  setRunning(id: string): void {
+    const entry = this.events.get(id);
+    if (entry) {
+      entry.status = EventStatus.Running;
+    }
+  }
+
+  /** Mark event as locked (completed) */
+  setLocked(id: string, state: BaseGameState): void {
+    const entry = this.events.get(id);
+    if (entry) {
+      entry.status = EventStatus.Locked;
+      entry.event.locked?.(state);
+      logger.debug(`Event locked: ${id}`);
+    }
+  }
+
+  /** Reset an event back to NotReady */
+  reset(id: string): void {
+    const entry = this.events.get(id);
+    if (entry) {
+      entry.status = EventStatus.NotReady;
+    }
+  }
+
+  /** Reset all events */
+  resetAll(): void {
+    for (const entry of this.events.values()) {
+      entry.status = EventStatus.NotReady;
+    }
+  }
+
+  /** Get all events for a specific location */
+  getByLocation(locationId: string): VylosEvent[] {
+    const result: VylosEvent[] = [];
+    for (const entry of this.events.values()) {
+      if (entry.event.locationId === locationId) {
+        result.push(entry.event);
+      }
+    }
+    return result;
+  }
+
+  /** Get locked event IDs (for save data) */
+  getLockedIds(): string[] {
+    const ids: string[] = [];
+    for (const [id, entry] of this.events) {
+      if (entry.status === EventStatus.Locked) {
+        ids.push(id);
+      }
+    }
+    return ids;
+  }
+
+  /** Restore locked state from save data */
+  restoreLockedIds(ids: string[]): void {
+    for (const id of ids) {
+      const entry = this.events.get(id);
+      if (entry) {
+        entry.status = EventStatus.Locked;
+      }
+    }
+  }
+}

package/src/engine/managers/HistoryManager.ts

@@ -0,0 +1,84 @@
+import type { Checkpoint } from '../types';
+import { logger } from '../utils/logger';
+
+export interface HistoryEntry {
+  eventId: string;
+  checkpoints: Checkpoint[];
+}
+
+/**
+ * Manages navigation history: back/forward through past events and checkpoints.
+ * Each completed event is pushed as a HistoryEntry.
+ */
+export class HistoryManager {
+  private history: HistoryEntry[] = [];
+  private currentIndex = -1;
+
+  /** Total history entries */
+  get count(): number {
+    return this.history.length;
+  }
+
+  /** Current navigation index */
+  get index(): number {
+    return this.currentIndex;
+  }
+
+  /** Whether back navigation is possible */
+  get canGoBack(): boolean {
+    return this.currentIndex > 0;
+  }
+
+  /** Whether forward navigation is possible */
+  get canGoForward(): boolean {
+    return this.currentIndex < this.history.length - 1;
+  }
+
+  /** Current history entry */
+  get current(): HistoryEntry | undefined {
+    return this.history[this.currentIndex];
+  }
+
+  /** Push a completed event to history */
+  push(eventId: string, checkpoints: Checkpoint[]): void {
+    // Trim forward history if we branched
+    if (this.currentIndex < this.history.length - 1) {
+      this.history.length = this.currentIndex + 1;
+    }
+
+    this.history.push({ eventId, checkpoints });
+    this.currentIndex = this.history.length - 1;
+    logger.debug(`History: pushed ${eventId}, total ${this.history.length}`);
+  }
+
+  /** Go back one entry. Returns the entry to restore, or undefined. */
+  goBack(): HistoryEntry | undefined {
+    if (!this.canGoBack) return undefined;
+    this.currentIndex--;
+    return this.history[this.currentIndex];
+  }
+
+  /** Go forward one entry. Returns the entry to restore, or undefined. */
+  goForward(): HistoryEntry | undefined {
+    if (!this.canGoForward) return undefined;
+    this.currentIndex++;
+    return this.history[this.currentIndex];
+  }
+
+  /** Clear all history */
+  clear(): void {
+    this.history = [];
+    this.currentIndex = -1;
+  }
+
+  /** Get all history for save data */
+  getAll(): HistoryEntry[] {
+    return structuredClone(this.history);
+  }
+
+  /** Restore history from save data */
+  restore(entries: HistoryEntry[], index: number): void {
+    this.history = structuredClone(entries);
+    this.currentIndex = Math.min(index, this.history.length - 1);
+  }
+}

package/src/engine/managers/InputManager.ts

@@ -0,0 +1,117 @@
+import { logger } from '../utils/logger';
+
+export type InputCallback = (action: string) => void;
+
+type KeyboardLayout = 'unknown' | 'qwerty' | 'azerty';
+
+/**
+ * Manages keyboard and mouse input for the game.
+ * Auto-detects QWERTY vs AZERTY layout on first relevant keypress.
+ */
+export class InputManager {
+  private callback: InputCallback | null = null;
+  private keyHandler: ((e: KeyboardEvent) => void) | null = null;
+  private skipMode = false;
+  private layout: KeyboardLayout = 'unknown';
+
+  /** Custom overrides set via setBinding() */
+  private customBindings = new Map<string, string>();
+
+  /** Start listening for input */
+  start(callback: InputCallback): void {
+    this.callback = callback;
+
+    this.keyHandler = (e: KeyboardEvent) => {
+      // Check custom bindings first
+      const custom = this.customBindings.get(e.key);
+      if (custom) {
+        e.preventDefault();
+        this.callback?.(custom);
+        return;
+      }
+
+      const action = this.resolveAction(e);
+      if (action) {
+        e.preventDefault();
+        this.callback?.(action);
+      }
+    };
+
+    if (typeof window !== 'undefined') {
+      window.addEventListener('keydown', this.keyHandler);
+      logger.debug('InputManager started');
+    }
+  }
+
+  /** Stop listening */
+  stop(): void {
+    if (this.keyHandler && typeof window !== 'undefined') {
+      window.removeEventListener('keydown', this.keyHandler);
+    }
+    this.keyHandler = null;
+    this.callback = null;
+    logger.debug('InputManager stopped');
+  }
+
+  /** Override a key binding */
+  setBinding(key: string, action: string): void {
+    this.customBindings.set(key, action);
+  }
+
+  /** Get detected keyboard layout */
+  get detectedLayout(): KeyboardLayout {
+    return this.layout;
+  }
+
+  /** Get skip mode state */
+  get isSkipping(): boolean {
+    return this.skipMode;
+  }
+
+  /** Toggle skip mode */
+  toggleSkip(): void {
+    this.skipMode = !this.skipMode;
+    logger.debug(`Skip mode: ${this.skipMode}`);
+  }
+
+  /** Set skip mode */
+  setSkip(enabled: boolean): void {
+    this.skipMode = enabled;
+  }
+
+  /** Resolve a keyboard event to an action, with layout auto-detection */
+  private resolveAction(e: KeyboardEvent): string | null {
+    const key = e.key;
+
+    // Universal keys (work on all layouts)
+    if (key === ' ' || key === 'Enter') return 'continue';
+    if (key === 'Escape') return 'menu';
+    if (key === 'ArrowRight') return 'forward';
+    if (key === 'ArrowLeft') return 'back';
+
+    // Skip toggle — same key on both layouts
+    if (key === 's' || key === 'S') return 'skip-toggle';
+
+    // Forward key: E on both layouts
+    if (key === 'e' || key === 'E') return 'continue';
+
+    // Layout-dependent back key
+    if (key === 'q' || key === 'Q') {
+      this.detectLayout('qwerty');
+      return 'back';
+    }
+    if (key === 'a' || key === 'A') {
+      this.detectLayout('azerty');
+      return 'back';
+    }
+
+    return null;
+  }
+
+  /** Auto-detect layout on first relevant keypress */
+  private detectLayout(detected: 'qwerty' | 'azerty'): void {
+    if (this.layout !== 'unknown') return;
+    this.layout = detected;
+    logger.debug(`Keyboard layout detected: ${detected}`);
+  }
+}

package/src/engine/managers/LanguageManager.ts

@@ -0,0 +1,51 @@
+import type { TextEntry } from '../types';
+import { interpolate } from '../utils/TimeHelper';
+import { logger } from '../utils/logger';
+
+/**
+ * Manages language selection and text resolution.
+ * Resolves TextEntry objects to the current language string.
+ */
+export class LanguageManager {
+  private currentLang = 'en';
+  private fallbackLang = 'en';
+
+  /** Get current language */
+  get language(): string {
+    return this.currentLang;
+  }
+
+  /** Set current language */
+  setLanguage(lang: string): void {
+    this.currentLang = lang;
+    logger.debug(`Language set to: ${lang}`);
+  }
+
+  /** Set fallback language */
+  setFallback(lang: string): void {
+    this.fallbackLang = lang;
+  }
+
+  /**
+   * Resolve a text entry to a string in the current language.
+   * If entry is already a string, return it as-is.
+   * If it's a TextEntry record, look up current language, then fallback, then first key.
+   */
+  resolve(entry: string | TextEntry): string {
+    if (typeof entry === 'string') return entry;
+
+    return entry[this.currentLang]
+      ?? entry[this.fallbackLang]
+      ?? Object.values(entry)[0]
+      ?? '';
+  }
+
+  /**
+   * Resolve text with variable interpolation.
+   * "{varName}" in the resolved string is replaced with the value from variables.
+   */
+  resolveWithVars(entry: string | TextEntry, variables: Record<string, string | number>): string {
+    const text = this.resolve(entry);
+    return interpolate(text, variables);
+  }
+}

package/src/engine/managers/LocationManager.ts

@@ -0,0 +1,76 @@
+import type { VylosLocation, LocationLink, BaseGameState, BackgroundEntry } from '../types';
+import { resolveBackground } from '../utils/TimeHelper';
+import { logger } from '../utils/logger';
+
+/**
+ * Manages locations: registration, linking, accessibility, background resolution.
+ */
+export class LocationManager {
+  private locations = new Map<string, VylosLocation>();
+  private links: LocationLink[] = [];
+
+  /** Register a location */
+  register(location: VylosLocation): void {
+    this.locations.set(location.id, location);
+    logger.debug(`Location registered: ${location.id}`);
+  }
+
+  /** Register multiple locations */
+  registerAll(locations: VylosLocation[]): void {
+    for (const loc of locations) {
+      this.register(loc);
+    }
+  }
+
+  /** Set the location link graph */
+  setLinks(links: LocationLink[]): void {
+    this.links = links;
+  }
+
+  /** Get a location by ID */
+  get(id: string): VylosLocation | undefined {
+    return this.locations.get(id);
+  }
+
+  /** Get all registered locations */
+  getAll(): VylosLocation[] {
+    return [...this.locations.values()];
+  }
+
+  /** Get locations accessible from a given location, considering state conditions */
+  getAccessibleFrom(locationId: string, state: BaseGameState): VylosLocation[] {
+    const linkedIds = this.links
+      .filter(link => {
+        if (link.from !== locationId) return false;
+        if (link.condition && !link.condition(state)) return false;
+        return true;
+      })
+      .map(link => link.to);
+
+    return linkedIds
+      .map(id => this.locations.get(id))
+      .filter((loc): loc is VylosLocation => {
+        if (!loc) return false;
+        if (loc.accessible && !loc.accessible(state)) return false;
+        return true;
+      });
+  }
+
+  /** Resolve the background image for a location at a given game time */
+  resolveBackground(locationId: string, gameTime: number): string | null {
+    const location = this.locations.get(locationId);
+    if (!location) return null;
+    return resolveBackground(location.backgrounds, gameTime);
+  }
+
+  /** Check if a location exists */
+  has(id: string): boolean {
+    return this.locations.has(id);
+  }
+
+  /** Clear all locations */
+  clear(): void {
+    this.locations.clear();
+    this.links = [];
+  }
+}

package/src/engine/managers/NavigationManager.ts

@@ -0,0 +1,75 @@
+import { WaitManager } from './WaitManager';
+import { logger } from '../utils/logger';
+
+export enum NavigationAction {
+  Continue = 'continue',
+  Back = 'back',
+  Forward = 'forward',
+  Action = 'action',
+  Location = 'location',
+  DrawableEvent = 'drawable_event',
+}
+
+export interface NavigationResult {
+  action: NavigationAction;
+  payload?: string;
+}
+
+/**
+ * Manages navigation between game loop ticks.
+ * The engine waits here for player input after each event completes.
+ */
+export class NavigationManager {
+  private waitManager = new WaitManager();
+
+  /** Whether the engine is currently waiting for navigation input */
+  get isWaiting(): boolean {
+    return this.waitManager.isWaiting;
+  }
+
+  /** Wait for the next navigation action from the player */
+  async waitForNavigation(): Promise<NavigationResult> {
+    return this.waitManager.wait<NavigationResult>();
+  }
+
+  /** Player wants to continue (advance to next event) */
+  continue(): void {
+    logger.debug('Navigation: continue');
+    this.waitManager.resolve({ action: NavigationAction.Continue });
+  }
+
+  /** Player wants to go back */
+  goBack(): void {
+    logger.debug('Navigation: back');
+    this.waitManager.resolve({ action: NavigationAction.Back });
+  }
+
+  /** Player wants to go forward */
+  goForward(): void {
+    logger.debug('Navigation: forward');
+    this.waitManager.resolve({ action: NavigationAction.Forward });
+  }
+
+  /** Player selected an action */
+  selectAction(actionId: string): void {
+    logger.debug('Navigation: action', actionId);
+    this.waitManager.resolve({ action: NavigationAction.Action, payload: actionId });
+  }
+
+  /** Player selected a location to travel to */
+  selectLocation(locationId: string): void {
+    logger.debug('Navigation: location', locationId);
+    this.waitManager.resolve({ action: NavigationAction.Location, payload: locationId });
+  }
+
+  /** Player clicked a drawable event */
+  selectDrawableEvent(eventId: string): void {
+    logger.debug('Navigation: drawable event', eventId);
+    this.waitManager.resolve({ action: NavigationAction.DrawableEvent, payload: eventId });
+  }
+
+  /** Cancel waiting (e.g., on game reset). Resolves the wait with Continue to unblock. */
+  cancel(): void {
+    this.waitManager.resolve({ action: NavigationAction.Continue });
+  }
+}

package/src/engine/managers/SaveManager.ts

@@ -0,0 +1,86 @@
+import type { SaveSlot, SaveMeta } from '../types';
+import { VylosStorage } from '../storage/VylosStorage';
+import { logger } from '../utils/logger';
+
+const SAVE_VERSION = 1;
+const STORE = 'saves';
+
+/**
+ * Manages save/load with versioned IndexedDB slots.
+ */
+export class SaveManager {
+  private storage: VylosStorage;
+  private ready: Promise<void>;
+
+  constructor(storage: VylosStorage) {
+    this.storage = storage;
+    this.ready = storage.open();
+  }
+
+  /** Save a complete slot (timestamp and version are set automatically) */
+  async save(slot: number, saveData: Omit<SaveSlot, 'slot' | 'timestamp' | 'version'>): Promise<void> {
+    await this.ready;
+    const data: SaveSlot = {
+      slot,
+      timestamp: Date.now(),
+      version: SAVE_VERSION,
+      ...JSON.parse(JSON.stringify(saveData)),
+    };
+
+    try {
+      await this.storage.put(STORE, slot, data);
+      logger.info(`Saved to slot ${slot}`);
+    } catch (error) {
+      logger.error('Save failed:', error);
+    }
+  }
+
+  /** Load game state from a slot */
+  async load(slot: number): Promise<SaveSlot | null> {
+    await this.ready;
+    try {
+      const data = await this.storage.get<SaveSlot>(STORE, slot);
+      if (!data) return null;
+
+      if (data.version !== SAVE_VERSION) {
+        logger.warn(`Save version mismatch: expected ${SAVE_VERSION}, got ${data.version}`);
+      }
+
+      logger.info(`Loaded from slot ${slot}`);
+      return data;
+    } catch (error) {
+      logger.error('Load failed:', error);
+      return null;
+    }
+  }
+
+  /** Delete a save slot */
+  async delete(slot: number): Promise<void> {
+    await this.ready;
+    await this.storage.delete(STORE, slot);
+    logger.info(`Deleted slot ${slot}`);
+  }
+
+  /** Get metadata for all save slots */
+  async listSlots(): Promise<SaveMeta[]> {
+    await this.ready;
+    try {
+      const all = await this.storage.getAll<SaveSlot>(STORE);
+      return all.map(d => ({
+        slot: d.slot,
+        timestamp: d.timestamp,
+        label: d.label,
+        thumbnail: d.thumbnail,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  /** Check if a slot has data */
+  async hasSlot(slot: number): Promise<boolean> {
+    await this.ready;
+    const data = await this.storage.get(STORE, slot);
+    return data !== undefined;
+  }
+}