@vylos/core 0.1.0

package/src/engine/managers/SettingsManager.ts

@@ -0,0 +1,70 @@
+import type { EngineSettings } from '../types';
+import { VylosStorage } from '../storage/VylosStorage';
+import { logger } from '../utils/logger';
+
+const STORE = 'settings';
+const SETTINGS_KEY = 'engine';
+
+const DEFAULT_SETTINGS: EngineSettings = {
+  textSpeed: 50,
+  autoSpeed: 3,
+  volume: { master: 80, music: 70, sfx: 80, voice: 100 },
+  language: 'en',
+  fullscreen: false,
+};
+
+/**
+ * Manages engine settings via IndexedDB.
+ * Settings are loaded once at startup and cached in memory.
+ */
+export class SettingsManager {
+  private storage: VylosStorage;
+  private ready: Promise<void>;
+  private current: EngineSettings = { ...DEFAULT_SETTINGS };
+
+  constructor(storage: VylosStorage) {
+    this.storage = storage;
+    this.ready = this.init();
+  }
+
+  private async init(): Promise<void> {
+    await this.storage.open();
+    try {
+      const saved = await this.storage.get<EngineSettings>(STORE, SETTINGS_KEY);
+      if (saved) {
+        this.current = { ...DEFAULT_SETTINGS, ...saved };
+        logger.debug('Settings loaded from IndexedDB');
+      }
+    } catch {
+      logger.warn('Failed to load settings, using defaults');
+    }
+  }
+
+  /** Wait until settings are loaded */
+  async whenReady(): Promise<void> {
+    await this.ready;
+  }
+
+  /** Get current settings (synchronous after init) */
+  get settings(): EngineSettings {
+    return this.current;
+  }
+
+  /** Update settings and persist */
+  async update(partial: Partial<EngineSettings>): Promise<void> {
+    await this.ready;
+    this.current = JSON.parse(JSON.stringify({ ...this.current, ...partial }));
+    try {
+      await this.storage.put(STORE, SETTINGS_KEY, this.current);
+      logger.debug('Settings saved');
+    } catch (error) {
+      logger.error('Settings save failed:', error);
+    }
+  }
+
+  /** Reset to defaults */
+  async reset(): Promise<void> {
+    this.current = { ...DEFAULT_SETTINGS };
+    await this.storage.put(STORE, SETTINGS_KEY, this.current);
+  }
+}

package/src/engine/managers/WaitManager.ts

@@ -0,0 +1,47 @@
+/**
+ * Generic promise-based wait mechanism.
+ * Creates a promise that external code can resolve (e.g., UI click handlers).
+ */
+export class WaitManager {
+  private resolveFunc: ((value: unknown) => void) | null = null;
+  private rejectFunc: ((reason: unknown) => void) | null = null;
+
+  /** Whether a wait is currently active */
+  get isWaiting(): boolean {
+    return this.resolveFunc !== null;
+  }
+
+  /** Create a new wait and return a promise that resolves when resolve() is called */
+  wait<T = void>(): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      this.resolveFunc = resolve as (value: unknown) => void;
+      this.rejectFunc = reject;
+    });
+  }
+
+  /** Resolve the current wait with a value */
+  resolve(value?: unknown): void {
+    if (this.resolveFunc) {
+      const fn = this.resolveFunc;
+      this.resolveFunc = null;
+      this.rejectFunc = null;
+      fn(value);
+    }
+  }
+
+  /** Reject the current wait with an error */
+  reject(reason?: unknown): void {
+    if (this.rejectFunc) {
+      const fn = this.rejectFunc;
+      this.resolveFunc = null;
+      this.rejectFunc = null;
+      fn(reason);
+    }
+  }
+
+  /** Cancel any pending wait */
+  cancel(): void {
+    this.resolveFunc = null;
+    this.rejectFunc = null;
+  }
+}

package/src/engine/schemas/baseGameState.schema.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+/** Base game state schema — projects extend this with their own fields */
+export const baseGameStateSchema = z.object({
+  locationId: z.string().min(1),
+  gameTime: z.number().nonnegative(),
+  flags: z.record(z.string(), z.boolean()),
+  counters: z.record(z.string(), z.number()),
+  player: z.object({
+    name: z.string().min(1),
+  }),
+});
+
+export type BaseGameStateFromSchema = z.infer<typeof baseGameStateSchema>;
+
+/** Create an extended game state schema by merging with project-specific fields */
+export function extendGameStateSchema<T extends z.ZodRawShape>(extension: T) {
+  return baseGameStateSchema.extend(extension);
+}

package/src/engine/schemas/checkpoint.schema.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { baseGameStateSchema } from './baseGameState.schema';
+
+export const checkpointSchema = z.object({
+  step: z.number().int().nonnegative(),
+  gameState: baseGameStateSchema,
+  type: z.enum(['say', 'choice', 'wait', 'overlay']),
+  choiceResult: z.string().optional(),
+});
+
+export type CheckpointFromSchema = z.infer<typeof checkpointSchema>;

package/src/engine/schemas/engineState.schema.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+
+const dialogueStateSchema = z.object({
+  text: z.string(),
+  speaker: z.string().nullable(),
+  isNarration: z.boolean(),
+});
+
+const choiceOptionSchema = z.object({
+  text: z.string(),
+  value: z.string(),
+  disabled: z.boolean().optional(),
+});
+
+const choiceStateSchema = z.object({
+  prompt: z.string().nullable(),
+  options: z.array(choiceOptionSchema),
+});
+
+const actionEntrySchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  locationId: z.string(),
+});
+
+const locationEntrySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  accessible: z.boolean(),
+});
+
+export const engineStateSchema = z.object({
+  phase: z.enum(['created', 'loading', 'main_menu', 'running', 'paused']),
+  background: z.string().nullable(),
+  foreground: z.string().nullable(),
+  dialogue: dialogueStateSchema.nullable(),
+  choices: choiceStateSchema.nullable(),
+  currentLocationId: z.string().nullable(),
+  availableActions: z.array(actionEntrySchema),
+  availableLocations: z.array(locationEntrySchema),
+  menuOpen: z.enum(['save_load', 'settings']).nullable(),
+  skipMode: z.boolean(),
+  autoMode: z.boolean(),
+});
+
+export type EngineStateFromSchema = z.infer<typeof engineStateSchema>;
+
+export const engineSettingsSchema = z.object({
+  textSpeed: z.number().min(0).max(1),
+  autoSpeed: z.number().min(0).max(1),
+  volume: z.object({
+    master: z.number().min(0).max(1),
+    music: z.number().min(0).max(1),
+    sfx: z.number().min(0).max(1),
+    voice: z.number().min(0).max(1),
+  }),
+  language: z.string().min(1),
+  fullscreen: z.boolean(),
+});

package/src/engine/schemas/location.schema.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+const backgroundEntrySchema = z.object({
+  path: z.string().min(1),
+  timeRange: z.tuple([z.number(), z.number()]).optional(),
+});
+
+export const locationSchema = z.object({
+  id: z.string().min(1),
+  name: z.union([z.string(), z.record(z.string(), z.string())]),
+  backgrounds: z.array(backgroundEntrySchema),
+});
+
+export type LocationFromSchema = z.infer<typeof locationSchema>;
+
+export const locationLinkSchema = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1),
+});
+
+export type LocationLinkFromSchema = z.infer<typeof locationLinkSchema>;

package/src/engine/storage/VylosStorage.ts

@@ -0,0 +1,131 @@
+import { logger } from '../utils/logger';
+
+const DB_VERSION = 1;
+
+/**
+ * Low-level IndexedDB wrapper for Vylos.
+ * One database per project, with typed object stores.
+ *
+ * Usage:
+ *   const storage = new VylosStorage('my-project');
+ *   await storage.open();
+ *   await storage.put('saves', 1, { ... });
+ *   const data = await storage.get('saves', 1);
+ */
+export class VylosStorage {
+  private db: IDBDatabase | null = null;
+  private dbName: string;
+
+  static readonly STORES = ['saves', 'settings', 'cache'] as const;
+
+  constructor(projectId = 'default') {
+    this.dbName = `vylos_${projectId}`;
+  }
+
+  async open(): Promise<void> {
+    if (this.db) return;
+
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, DB_VERSION);
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        for (const name of VylosStorage.STORES) {
+          if (!db.objectStoreNames.contains(name)) {
+            db.createObjectStore(name);
+          }
+        }
+      };
+
+      request.onsuccess = () => {
+        this.db = request.result;
+        logger.debug(`VylosStorage opened: ${this.dbName}`);
+        resolve();
+      };
+
+      request.onerror = () => {
+        logger.error('VylosStorage open failed:', request.error);
+        reject(request.error);
+      };
+    });
+  }
+
+  async put<T>(storeName: string, key: IDBValidKey, value: T): Promise<void> {
+    const db = this.requireDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      tx.objectStore(storeName).put(value, key);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  async get<T>(storeName: string, key: IDBValidKey): Promise<T | undefined> {
+    const db = this.requireDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readonly');
+      const request = tx.objectStore(storeName).get(key);
+      request.onsuccess = () => resolve(request.result as T | undefined);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async delete(storeName: string, key: IDBValidKey): Promise<void> {
+    const db = this.requireDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      tx.objectStore(storeName).delete(key);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  async keys(storeName: string): Promise<IDBValidKey[]> {
+    const db = this.requireDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readonly');
+      const request = tx.objectStore(storeName).getAllKeys();
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async getAll<T>(storeName: string): Promise<T[]> {
+    const db = this.requireDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readonly');
+      const request = tx.objectStore(storeName).getAll();
+      request.onsuccess = () => resolve(request.result as T[]);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async clear(storeName: string): Promise<void> {
+    const db = this.requireDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(storeName, 'readwrite');
+      tx.objectStore(storeName).clear();
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  close(): void {
+    this.db?.close();
+    this.db = null;
+  }
+
+  async destroy(): Promise<void> {
+    this.close();
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.deleteDatabase(this.dbName);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  private requireDb(): IDBDatabase {
+    if (!this.db) throw new Error('VylosStorage not opened. Call open() first.');
+    return this.db;
+  }
+}

package/src/engine/types/actions.ts

@@ -0,0 +1,20 @@
+import type { BaseGameState } from './game-state';
+import type { TextEntry } from './events';
+
+/** An action available to the player at a location */
+export interface VylosAction<TState extends BaseGameState = BaseGameState> {
+  /** Unique action ID */
+  id: string;
+
+  /** Display label */
+  label: string | TextEntry;
+
+  /** Location this action belongs to (null for global) */
+  locationId?: string;
+
+  /** Whether this action is currently available */
+  unlocked?(state: TState): boolean;
+
+  /** Execute the action (synchronous state mutation) */
+  execute(state: TState): void;
+}

package/src/engine/types/checkpoint.ts

@@ -0,0 +1,31 @@
+import type { BaseGameState } from './game-state';
+import type { DialogueState, ChoiceOption } from './engine';
+
+/** A checkpoint captured at each interaction point */
+export interface Checkpoint {
+  /** Sequential step number within the event */
+  step: number;
+  /** Deep clone of game state at this point */
+  gameState: BaseGameState;
+  /** Type of interaction at this step */
+  type: CheckpointType;
+  /** Stored choice result (for replay during rollback) */
+  choiceResult?: string;
+  /** Dialogue state at this point (for history browsing) */
+  dialogue?: DialogueState | null;
+  /** Background path at this point */
+  background?: string | null;
+  /** Available choice options at this step (for history redo) */
+  choiceOptions?: ChoiceOption[];
+}
+
+export enum CheckpointType {
+  /** Player pressed continue after dialogue */
+  Say = 'say',
+  /** Player made a choice */
+  Choice = 'choice',
+  /** Wait completed */
+  Wait = 'wait',
+  /** Overlay interaction */
+  Overlay = 'overlay',
+}

package/src/engine/types/config.ts

@@ -0,0 +1,9 @@
+export interface VylosConfig {
+  name: string;
+  id: string;
+  version: string;
+  languages: string[];
+  defaultLanguage: string;
+  defaultLocation: string;
+  resolution: { width: number; height: number };
+}

package/src/engine/types/dialogue.ts

@@ -0,0 +1,15 @@
+import type { TextEntry } from './events';
+
+/** Resolved dialogue line ready for display */
+export interface DialogueLine {
+  text: string;
+  speaker: string | null;
+  isNarration: boolean;
+}
+
+/** Character definition for speaker resolution */
+export interface Character {
+  id: string;
+  name: string | TextEntry;
+  color?: string;
+}

package/src/engine/types/engine.ts

@@ -0,0 +1,85 @@
+import type { DrawableEventEntry } from './events';
+
+/** Engine lifecycle phases */
+export enum EnginePhase {
+  /** Engine created but not initialized */
+  Created = 'created',
+  /** Loading project data */
+  Loading = 'loading',
+  /** Main menu displayed */
+  MainMenu = 'main_menu',
+  /** Game running */
+  Running = 'running',
+  /** Game paused (save/load/settings menu) */
+  Paused = 'paused',
+}
+
+/** Engine UI state (managed by Pinia, drives Vue rendering) */
+export interface EngineState {
+  phase: EnginePhase;
+  background: string | null;
+  foreground: string | null;
+  dialogue: DialogueState | null;
+  choices: ChoiceState | null;
+  currentLocationId: string | null;
+  availableActions: ActionEntry[];
+  availableLocations: LocationEntry[];
+  drawableEvents: DrawableEventEntry[];
+  menuOpen: MenuType | null;
+  skipMode: boolean;
+  autoMode: boolean;
+}
+
+export interface DialogueState {
+  text: string;
+  speaker: string | null;
+  isNarration: boolean;
+}
+
+export interface ChoiceState {
+  prompt: string | null;
+  options: ChoiceOption[];
+  /** Checkpoint step index (present when displaying a history choice for redo) */
+  historyStepIndex?: number;
+  /** Previously chosen value (for highlighting in redo mode) */
+  historySelectedValue?: string;
+}
+
+export interface ChoiceOption {
+  text: string;
+  value: string;
+  disabled?: boolean;
+}
+
+export interface ActionEntry {
+  id: string;
+  label: string;
+  locationId: string;
+}
+
+export interface LocationEntry {
+  id: string;
+  name: string;
+  accessible: boolean;
+}
+
+export enum MenuType {
+  PauseMenu = 'pause_menu',
+  Save = 'save',
+  Load = 'load',
+  Settings = 'settings',
+}
+
+/** Engine settings (persisted separately) */
+export interface EngineSettings {
+  textSpeed: number;
+  autoSpeed: number;
+  volume: {
+    master: number;
+    music: number;
+    sfx: number;
+    voice: number;
+  };
+  language: string;
+  fullscreen: boolean;
+}

package/src/engine/types/events.ts

@@ -0,0 +1,117 @@
+import type { BaseGameState } from './game-state';
+
+/** A text entry with per-language strings */
+export type TextEntry = Record<string, string>;
+
+/** Options for engine.say() */
+export interface SayOptions {
+  from?: string | TextEntry;
+  variables?: Record<string, string | number>;
+}
+
+/** Options for engine.choice() */
+export interface ChoiceItem<T extends string = string> {
+  text: string | TextEntry;
+  value: T;
+  disabled?: boolean;
+  condition?: () => boolean;
+}
+
+/**
+ * The API available to event execute() functions.
+ * This is what visual novel authors interact with.
+ */
+export interface VylosAPI {
+  /** Show dialogue text and wait for player to continue */
+  say(text: string | TextEntry, options?: SayOptions): Promise<void>;
+
+  /** Show choices and return the selected value */
+  choice<T extends string>(items: ChoiceItem<T>[]): Promise<T>;
+
+  /** Set the background image */
+  setBackground(path: string): void;
+
+  /** Show/hide a foreground image (character sprite, etc.) */
+  setForeground(path: string | null): void;
+
+  /** Show a custom overlay component */
+  showOverlay(componentId: string, props?: Record<string, unknown>): Promise<void>;
+
+  /** Hide overlay */
+  hideOverlay(): void;
+
+  /** Jump to another event */
+  jump(eventId: string): never;
+
+  /** End the current event */
+  end(): never;
+
+  /** Wait for a specified duration (ms) */
+  wait(ms: number): Promise<void>;
+
+  /** Change location */
+  setLocation(locationId: string): void;
+
+  /** Play sound effect */
+  playSfx(path: string): void;
+
+  /** Play background music */
+  playMusic(path: string): void;
+
+  /** Stop background music */
+  stopMusic(): void;
+}
+
+/** Configuration for drawable events — clickable characters/objects in a location */
+export interface DrawableEventConfig {
+  /** Display text for the clickable element */
+  label: string | TextEntry;
+  /** Placement hint on screen */
+  position?: 'left' | 'center' | 'right';
+  /** Emoji/unicode icon */
+  icon?: string;
+}
+
+/** A drawable event entry for UI rendering */
+export interface DrawableEventEntry {
+  id: string;
+  label: string;
+  position: 'left' | 'center' | 'right';
+  icon?: string;
+}
+
+/** A visual novel event definition */
+export interface VylosEvent<TState extends BaseGameState = BaseGameState> {
+  /** Unique event ID (derived from file path if not specified) */
+  id: string;
+
+  /** Location this event belongs to (null for global events) */
+  locationId?: string;
+
+  /** Make this event drawable — a clickable element the player interacts with instead of auto-triggering */
+  draw?: DrawableEventConfig;
+
+  /** 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;
+
+  /** Called when event completes (Unlocked → Locked) */
+  locked?(state: TState): void;
+
+  /** The event's narrative logic */
+  execute(engine: VylosAPI, state: TState): Promise<void>;
+}
+
+/** Event lifecycle status */
+export enum EventStatus {
+  /** Conditions not yet met */
+  NotReady = 'not_ready',
+  /** Conditions met, ready to execute */
+  Unlocked = 'unlocked',
+  /** Currently executing */
+  Running = 'running',
+  /** Completed */
+  Locked = 'locked',
+}

package/src/engine/types/game-state.ts

@@ -0,0 +1,15 @@
+/** Base game state that all projects extend via Zod schema */
+export interface BaseGameState {
+  /** Current location ID */
+  locationId: string;
+  /** In-game time (hours since game start, e.g. 14.5 = 2:30 PM) */
+  gameTime: number;
+  /** Generic flags for event gating */
+  flags: Record<string, boolean>;
+  /** Generic counters */
+  counters: Record<string, number>;
+  /** Player data */
+  player: {
+    name: string;
+  };
+}

package/src/engine/types/index.ts

@@ -0,0 +1,10 @@
+export * from './engine';
+export * from './events';
+export * from './actions';
+export * from './locations';
+export * from './dialogue';
+export * from './save';
+export * from './game-state';
+export * from './plugin';
+export * from './checkpoint';
+export * from './config';