@vylos/core 0.1.0

package/src/engine/types/locations.ts

@@ -0,0 +1,32 @@
+import type { BaseGameState } from './game-state';
+import type { TextEntry } from './events';
+
+/** Background resolution entry — time-based or default */
+export interface BackgroundEntry {
+  path: string;
+  /** Time range in game hours, e.g. [6, 18] for daytime */
+  timeRange?: [number, number];
+}
+
+/** Location definition */
+export interface VylosLocation {
+  /** Unique location ID */
+  id: string;
+
+  /** Display name */
+  name: string | TextEntry;
+
+  /** Background images (resolved by time of day) */
+  backgrounds: BackgroundEntry[];
+
+  /** Whether this location is accessible — defaults to true */
+  accessible?<TState extends BaseGameState>(state: TState): boolean;
+}
+
+/** Location link (navigation graph edge) */
+export interface LocationLink {
+  from: string;
+  to: string;
+  /** Whether this link is currently traversable */
+  condition?<TState extends BaseGameState>(state: TState): boolean;
+}

package/src/engine/types/plugin.ts

@@ -0,0 +1,11 @@
+import type { DependencyContainer } from 'tsyringe';
+import type { Component } from 'vue';
+
+/** Plugin interface for project-level engine customization */
+export interface VylosPlugin {
+  /** Register DI overrides (custom managers, etc.) */
+  setup?(container: DependencyContainer): void;
+
+  /** Override Vue components by component ID */
+  components?: Record<string, Component>;
+}

package/src/engine/types/save.ts

@@ -0,0 +1,40 @@
+import type { BaseGameState } from './game-state';
+import type { Checkpoint } from './checkpoint';
+
+/** A single save slot */
+export interface SaveSlot {
+  /** Slot number */
+  slot: number;
+  /** When this save was created */
+  timestamp: number;
+  /** Save format version for migration */
+  version: number;
+  /** Game state snapshot */
+  gameState: BaseGameState;
+  /** Current event ID (if mid-event) */
+  eventId: string | null;
+  /** Checkpoint step number (if mid-event) */
+  stepNumber: number;
+  /** Player-visible label */
+  label: string;
+  /** Screenshot thumbnail (data URL) */
+  thumbnail: string | null;
+  /** Checkpoints for mid-event resume */
+  checkpoints?: Checkpoint[];
+  /** Game state before event started (for redo support after load) */
+  initialState?: BaseGameState;
+  /** Completed event history */
+  history?: Array<{ eventId: string; checkpoints: Checkpoint[] }>;
+  /** Current history navigation index */
+  historyIndex?: number;
+  /** IDs of events that were locked (completed) at save time */
+  lockedEventIds?: string[];
+}
+
+/** Save metadata (displayed in save/load menu without loading full state) */
+export interface SaveMeta {
+  slot: number;
+  timestamp: number;
+  label: string;
+  thumbnail: string | null;
+}

package/src/engine/utils/TimeHelper.ts

@@ -0,0 +1,39 @@
+import type { BackgroundEntry } from '../types';
+
+/** Resolve the correct background for a given game time */
+export function resolveBackground(backgrounds: BackgroundEntry[], gameTime: number): string | null {
+  if (backgrounds.length === 0) return null;
+
+  // Find time-specific background first
+  for (const bg of backgrounds) {
+    if (bg.timeRange) {
+      const [start, end] = bg.timeRange;
+      const hour = gameTime % 24;
+      if (start <= end) {
+        // Normal range (e.g., 6-18)
+        if (hour >= start && hour < end) return bg.path;
+      } else {
+        // Wrapping range (e.g., 22-6)
+        if (hour >= start || hour < end) return bg.path;
+      }
+    }
+  }
+
+  // Fall back to first entry without time range, or first entry overall
+  const defaultBg = backgrounds.find(bg => !bg.timeRange) ?? backgrounds[0];
+  return defaultBg.path;
+}
+
+/** Format game time as HH:MM string */
+export function formatGameTime(gameTime: number): string {
+  const hours = Math.floor(gameTime % 24);
+  const minutes = Math.floor((gameTime % 1) * 60);
+  return `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}`;
+}
+
+/** Interpolate variables in text: "Hello {name}!" → "Hello Alice!" */
+export function interpolate(text: string, variables: Record<string, string | number>): string {
+  return text.replace(/\{(\w+)\}/g, (match, key: string) => {
+    return key in variables ? String(variables[key]) : match;
+  });
+}

package/src/engine/utils/logger.ts

@@ -0,0 +1,43 @@
+export enum LogLevel {
+  Debug = 0,
+  Info = 1,
+  Warn = 2,
+  Error = 3,
+  Silent = 4,
+}
+
+let currentLevel: LogLevel = typeof import.meta !== 'undefined' &&
+  (import.meta as Record<string, unknown>).env &&
+  (import.meta as Record<string, Record<string, unknown>>).env.DEV
+  ? LogLevel.Debug
+  : LogLevel.Warn;
+
+export const logger = {
+  setLevel(level: LogLevel) {
+    currentLevel = level;
+  },
+
+  debug(...args: unknown[]) {
+    if (currentLevel <= LogLevel.Debug) {
+      console.debug('[Vylos]', ...args);
+    }
+  },
+
+  info(...args: unknown[]) {
+    if (currentLevel <= LogLevel.Info) {
+      console.info('[Vylos]', ...args);
+    }
+  },
+
+  warn(...args: unknown[]) {
+    if (currentLevel <= LogLevel.Warn) {
+      console.warn('[Vylos]', ...args);
+    }
+  },
+
+  error(...args: unknown[]) {
+    if (currentLevel <= LogLevel.Error) {
+      console.error('[Vylos]', ...args);
+    }
+  },
+};

package/src/env.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const component: DefineComponent<Record<string, never>, Record<string, never>, unknown>;
+  export default component;
+}
+
+declare module 'vylos:project' {
+  export const config: Record<string, unknown>;
+  export const plugin: import('./engine/types/plugin').VylosPlugin | undefined;
+}
+
+declare module 'vylos:texts/*' {
+  const texts: Record<string, Record<string, string>>;
+  export default texts;
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+import 'reflect-metadata';
+
+// Types
+export * from './engine/types';
+
+// Schemas
+export { baseGameStateSchema, extendGameStateSchema } from './engine/schemas/baseGameState.schema';
+export { engineStateSchema, engineSettingsSchema } from './engine/schemas/engineState.schema';
+export { checkpointSchema } from './engine/schemas/checkpoint.schema';
+export { locationSchema, locationLinkSchema } from './engine/schemas/location.schema';
+
+// Errors
+export { JumpSignal } from './engine/errors/JumpSignal';
+export { EventEndError } from './engine/errors/EventEndError';
+export { InterruptSignal } from './engine/errors/InterruptSignal';
+export { StateValidationError } from './engine/errors/StateValidationError';
+
+// Utils
+export { logger, LogLevel } from './engine/utils/logger';
+export { resolveBackground, formatGameTime, interpolate } from './engine/utils/TimeHelper';
+
+// Stores
+export { useEngineStateStore } from './stores/engineState';
+export { useGameStateStore } from './stores/gameState';
+
+// Core engine
+export { Engine } from './engine/core/Engine';
+export type { EngineLoopCallbacks } from './engine/core/Engine';
+export { EventRunner } from './engine/core/EventRunner';
+export type { EventRunnerCallbacks, HistoryStep } from './engine/core/EventRunner';
+export { CheckpointManager } from './engine/core/CheckpointManager';
+export { createEngine, getComponentOverride, clearComponentOverrides, DI_TOKENS } from './engine/core/EngineFactory';
+
+// Managers
+export { EventManager } from './engine/managers/EventManager';
+export { HistoryManager } from './engine/managers/HistoryManager';
+export { NavigationManager, NavigationAction } from './engine/managers/NavigationManager';
+export { WaitManager } from './engine/managers/WaitManager';
+export { LocationManager } from './engine/managers/LocationManager';
+export { ActionManager } from './engine/managers/ActionManager';
+export { SaveManager } from './engine/managers/SaveManager';
+export { SettingsManager } from './engine/managers/SettingsManager';
+export { LanguageManager } from './engine/managers/LanguageManager';
+export { InputManager } from './engine/managers/InputManager';
+
+// Storage
+export { VylosStorage } from './engine/storage/VylosStorage';
+
+// Composables
+export { useEngine, ENGINE_INJECT_KEY } from './composables/useEngine';
+export { useGameState } from './composables/useGameState';
+export { useLanguage } from './composables/useLanguage';
+export { CONFIG_INJECT_KEY } from './composables/useConfig';
+
+// Components — app
+export { default as GameShell } from './components/app/GameShell.vue';
+export { default as EngineView } from './components/app/EngineView.vue';
+export { default as LoadingScreen } from './components/app/LoadingScreen.vue';
+export { default as MainMenu } from './components/app/MainMenu.vue';
+
+// Components — core
+export { default as BackgroundLayer } from './components/core/BackgroundLayer.vue';
+export { default as ForegroundLayer } from './components/core/ForegroundLayer.vue';
+export { default as DialogueBox } from './components/core/DialogueBox.vue';
+export { default as ChoicePanel } from './components/core/ChoicePanel.vue';
+export { default as CustomOverlay } from './components/core/CustomOverlay.vue';
+export { default as DrawableOverlay } from './components/core/DrawableOverlay.vue';
+
+// Components — menu
+export { default as ActionOverlay } from './components/menu/ActionOverlay.vue';
+export { default as LocationOverlay } from './components/menu/LocationOverlay.vue';
+export { default as TopBar } from './components/menu/TopBar.vue';
+export { default as SaveLoadMenu } from './components/menu/SaveLoadMenu.vue';
+export { default as SettingsMenu } from './components/menu/SettingsMenu.vue';

package/src/stores/engineState.ts

@@ -0,0 +1,127 @@
+import { defineStore } from 'pinia';
+import { ref } from 'vue';
+import {
+  EnginePhase,
+  MenuType,
+  type DialogueState,
+  type ChoiceState,
+  type ActionEntry,
+  type LocationEntry,
+  type DrawableEventEntry,
+} from '../engine/types';
+
+export const useEngineStateStore = defineStore('engineState', () => {
+  const phase = ref<EnginePhase>(EnginePhase.Created);
+  const background = ref<string | null>(null);
+  const foreground = ref<string | null>(null);
+  const dialogue = ref<DialogueState | null>(null);
+  const choices = ref<ChoiceState | null>(null);
+  const currentLocationId = ref<string | null>(null);
+  const availableActions = ref<ActionEntry[]>([]);
+  const availableLocations = ref<LocationEntry[]>([]);
+  const menuOpen = ref<MenuType | null>(null);
+  const skipMode = ref(false);
+  const autoMode = ref(false);
+  const historyBrowsing = ref(false);
+  const drawableEvents = ref<DrawableEventEntry[]>([]);
+  const overlayId = ref<string | null>(null);
+  const overlayProps = ref<Record<string, unknown> | null>(null);
+
+  function setDialogue(state: DialogueState | null) {
+    dialogue.value = state;
+  }
+
+  function setChoices(state: ChoiceState | null) {
+    choices.value = state;
+  }
+
+  function setBackground(path: string | null) {
+    background.value = path;
+  }
+
+  function setForeground(path: string | null) {
+    foreground.value = path;
+  }
+
+  function setPhase(p: EnginePhase) {
+    phase.value = p;
+  }
+
+  function setLocation(id: string | null) {
+    currentLocationId.value = id;
+  }
+
+  function setActions(actions: ActionEntry[]) {
+    availableActions.value = actions;
+  }
+
+  function setLocations(locations: LocationEntry[]) {
+    availableLocations.value = locations;
+  }
+
+  function openMenu(type: MenuType) {
+    menuOpen.value = type;
+  }
+
+  function closeMenu() {
+    menuOpen.value = null;
+  }
+
+  function setDrawableEvents(events: DrawableEventEntry[]) {
+    drawableEvents.value = events;
+  }
+
+  function setOverlay(id: string | null, props?: Record<string, unknown>) {
+    overlayId.value = id;
+    overlayProps.value = props ?? null;
+  }
+
+  function $reset() {
+    phase.value = EnginePhase.Created;
+    background.value = null;
+    foreground.value = null;
+    dialogue.value = null;
+    choices.value = null;
+    currentLocationId.value = null;
+    availableActions.value = [];
+    availableLocations.value = [];
+    menuOpen.value = null;
+    skipMode.value = false;
+    autoMode.value = false;
+    historyBrowsing.value = false;
+    drawableEvents.value = [];
+    overlayId.value = null;
+    overlayProps.value = null;
+  }
+
+  return {
+    phase,
+    background,
+    foreground,
+    dialogue,
+    choices,
+    currentLocationId,
+    availableActions,
+    availableLocations,
+    menuOpen,
+    skipMode,
+    autoMode,
+    historyBrowsing,
+    drawableEvents,
+    overlayId,
+    overlayProps,
+    setDialogue,
+    setChoices,
+    setBackground,
+    setForeground,
+    setPhase,
+    setLocation,
+    setActions,
+    setLocations,
+    openMenu,
+    closeMenu,
+    setDrawableEvents,
+    setOverlay,
+    $reset,
+  };
+});

package/src/stores/gameState.ts

@@ -0,0 +1,49 @@
+import { defineStore } from 'pinia';
+import { ref } from 'vue';
+import type { BaseGameState } from '../engine/types';
+
+/** Default initial game state */
+function createDefaultState(): BaseGameState {
+  return {
+    locationId: '',
+    gameTime: 8,
+    flags: {},
+    counters: {},
+    player: {
+      name: 'Player',
+    },
+  };
+}
+
+export const useGameStateStore = defineStore('gameState', () => {
+  const state = ref<BaseGameState>(createDefaultState());
+
+  function getState(): BaseGameState {
+    return state.value;
+  }
+
+  function setState(newState: BaseGameState) {
+    state.value = newState;
+  }
+
+  function getSnapshot(): BaseGameState {
+    return structuredClone(state.value);
+  }
+
+  function restoreSnapshot(snapshot: BaseGameState) {
+    state.value = structuredClone(snapshot);
+  }
+
+  function $reset() {
+    state.value = createDefaultState();
+  }
+
+  return {
+    state,
+    getState,
+    setState,
+    getSnapshot,
+    restoreSnapshot,
+    $reset,
+  };
+});

package/tests/engine/ActionManager.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ActionManager } from '../../src/engine/managers/ActionManager';
+import type { VylosAction, BaseGameState } from '../../src/engine/types';
+
+function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+  return {
+    locationId: 'cafe',
+    gameTime: 12,
+    flags: {},
+    counters: {},
+    player: { name: 'Alice' },
+    ...overrides,
+  };
+}
+
+describe('ActionManager', () => {
+  let am: ActionManager;
+
+  const sleepAction: VylosAction = {
+    id: 'sleep',
+    label: 'Go to Sleep',
+    locationId: 'bedroom',
+    execute(state) {
+      state.gameTime += 8;
+    },
+  };
+
+  const orderCoffee: VylosAction = {
+    id: 'order_coffee',
+    label: 'Order Coffee',
+    locationId: 'cafe',
+    unlocked: (state) => state.counters['coffee_count'] === undefined || state.counters['coffee_count'] < 3,
+    execute(state) {
+      state.counters['coffee_count'] = (state.counters['coffee_count'] ?? 0) + 1;
+    },
+  };
+
+  const globalAction: VylosAction = {
+    id: 'check_phone',
+    label: 'Check Phone',
+    execute(state) {
+      state.flags['checked_phone'] = true;
+    },
+  };
+
+  beforeEach(() => {
+    am = new ActionManager();
+    am.registerAll([sleepAction, orderCoffee, globalAction]);
+  });
+
+  it('registers and retrieves actions', () => {
+    expect(am.get('sleep')).toBeDefined();
+    expect(am.get('order_coffee')).toBeDefined();
+    expect(am.get('nope')).toBeUndefined();
+  });
+
+  it('getAvailable filters by location', () => {
+    const state = makeState();
+    const cafeActions = am.getAvailable('cafe', state);
+    expect(cafeActions.map(a => a.id)).toContain('order_coffee');
+    expect(cafeActions.map(a => a.id)).toContain('check_phone'); // global
+    expect(cafeActions.map(a => a.id)).not.toContain('sleep'); // bedroom only
+  });
+
+  it('getAvailable includes global actions everywhere', () => {
+    const state = makeState();
+    const bedroomActions = am.getAvailable('bedroom', state);
+    expect(bedroomActions.map(a => a.id)).toContain('check_phone');
+    expect(bedroomActions.map(a => a.id)).toContain('sleep');
+  });
+
+  it('getAvailable respects unlock conditions', () => {
+    const state = makeState({ counters: { coffee_count: 3 } });
+    const actions = am.getAvailable('cafe', state);
+    expect(actions.map(a => a.id)).not.toContain('order_coffee');
+  });
+
+  it('execute runs action and mutates state', () => {
+    const state = makeState();
+    const result = am.execute('order_coffee', state);
+    expect(result).toBe(true);
+    expect(state.counters['coffee_count']).toBe(1);
+  });
+
+  it('execute returns false for unknown action', () => {
+    const state = makeState();
+    expect(am.execute('nope', state)).toBe(false);
+  });
+
+  it('clear removes all actions', () => {
+    am.clear();
+    expect(am.get('sleep')).toBeUndefined();
+  });
+});

package/tests/engine/CheckpointManager.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { CheckpointManager } from '../../src/engine/core/CheckpointManager';
+import type { BaseGameState } from '../../src/engine/types';
+import { CheckpointType } from '../../src/engine/types';
+
+function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+  return {
+    locationId: 'cafe',
+    gameTime: 8,
+    flags: {},
+    counters: {},
+    player: { name: 'Alice' },
+    ...overrides,
+  };
+}
+
+describe('CheckpointManager', () => {
+  let cm: CheckpointManager;
+
+  beforeEach(() => {
+    cm = new CheckpointManager();
+  });
+
+  it('starts empty', () => {
+    expect(cm.count).toBe(0);
+    expect(cm.isReplaying).toBe(false);
+  });
+
+  it('captures checkpoints incrementally', () => {
+    cm.capture(makeState(), CheckpointType.Say);
+    cm.capture(makeState({ gameTime: 9 }), CheckpointType.Say);
+    cm.capture(makeState({ gameTime: 10 }), CheckpointType.Choice, 'coffee');
+    expect(cm.count).toBe(3);
+  });
+
+  it('stores deep clones (mutations do not affect checkpoints)', () => {
+    const state = makeState();
+    cm.capture(state, CheckpointType.Say);
+    state.gameTime = 999;
+    const restored = cm.getStateAt(0);
+    expect(restored?.gameTime).toBe(8);
+  });
+
+  it('retrieves state at a specific step', () => {
+    cm.capture(makeState({ gameTime: 8 }), CheckpointType.Say);
+    cm.capture(makeState({ gameTime: 9 }), CheckpointType.Say);
+    cm.capture(makeState({ gameTime: 10 }), CheckpointType.Choice, 'tea');
+
+    expect(cm.getStateAt(0)?.gameTime).toBe(8);
+    expect(cm.getStateAt(1)?.gameTime).toBe(9);
+    expect(cm.getStateAt(2)?.gameTime).toBe(10);
+    expect(cm.getStateAt(3)).toBeUndefined();
+  });
+
+  it('prepareRollback sets up replay mode', () => {
+    cm.capture(makeState({ gameTime: 8 }), CheckpointType.Say);
+    cm.capture(makeState({ gameTime: 9 }), CheckpointType.Say);
+    cm.capture(makeState({ gameTime: 10 }), CheckpointType.Choice, 'tea');
+
+    const state = cm.prepareRollback(1);
+    expect(state?.gameTime).toBe(9);
+    expect(cm.isReplaying).toBe(true);
+    // Checkpoints after target are trimmed
+    expect(cm.count).toBe(1);
+  });
+
+  it('replay advances step by step', () => {
+    cm.capture(makeState({ gameTime: 8 }), CheckpointType.Say);
+    cm.capture(makeState({ gameTime: 9 }), CheckpointType.Choice, 'coffee');
+    cm.capture(makeState({ gameTime: 10 }), CheckpointType.Say);
+
+    cm.prepareRollback(2);
+    // After prepareRollback(2), we have checkpoints [0,1] and replayIndex=0
+    expect(cm.isReplaying).toBe(true);
+    expect(cm.count).toBe(2);
+
+    // Advance past checkpoint 0
+    cm.advanceReplay();
+    expect(cm.isReplaying).toBe(true);
+
+    // Advance past checkpoint 1
+    cm.advanceReplay();
+    // Now replayIndex=2 >= count=2, so replaying is done
+    expect(cm.isReplaying).toBe(false);
+  });
+
+  it('getReplayChoiceResult returns stored value during replay', () => {
+    cm.capture(makeState(), CheckpointType.Say);
+    cm.capture(makeState(), CheckpointType.Choice, 'coffee');
+    cm.capture(makeState(), CheckpointType.Say); // step 2
+
+    // Rollback to step 1 — trims to [step0], replays from beginning
+    cm.prepareRollback(1);
+    expect(cm.count).toBe(1);
+    // replayIndex starts at 0, checkpoints[0] is Say (no choice result)
+    expect(cm.getReplayChoiceResult()).toBeUndefined();
+    cm.advanceReplay();
+    // replayIndex=1 >= count=1, replay done — choice at step 1 was trimmed
+    expect(cm.isReplaying).toBe(false);
+  });
+
+  it('clear removes all checkpoints', () => {
+    cm.capture(makeState(), CheckpointType.Say);
+    cm.capture(makeState(), CheckpointType.Say);
+    cm.clear();
+    expect(cm.count).toBe(0);
+    expect(cm.isReplaying).toBe(false);
+  });
+
+  it('getAll returns deep clones', () => {
+    cm.capture(makeState(), CheckpointType.Say);
+    const all = cm.getAll();
+    expect(all.length).toBe(1);
+    all[0].step = 999;
+    expect(cm.getAll()[0].step).toBe(0);
+  });
+
+  it('restore loads checkpoints from save data', () => {
+    const checkpoints = [
+      { step: 0, gameState: makeState({ gameTime: 8 }), type: CheckpointType.Say },
+      { step: 1, gameState: makeState({ gameTime: 9 }), type: CheckpointType.Choice, choiceResult: 'tea' },
+    ];
+
+    cm.restore(checkpoints);
+    expect(cm.count).toBe(2);
+    expect(cm.getStateAt(0)?.gameTime).toBe(8);
+    expect(cm.getStateAt(1)?.gameTime).toBe(9);
+  });
+
+  it('prepareRollback returns undefined for invalid step', () => {
+    expect(cm.prepareRollback(0)).toBeUndefined();
+    cm.capture(makeState(), CheckpointType.Say);
+    expect(cm.prepareRollback(5)).toBeUndefined();
+    expect(cm.prepareRollback(-1)).toBeUndefined();
+  });
+});