@vylos/core 0.3.0 → 0.4.0

package/src/engine/types/events.ts

@@ -1,11 +1,12 @@
-import type { BaseGameState } from './game-state';
+import type { VylosGameState } from './game-state';
+import type { VylosCharacter } from './dialogue';
 
 /** A text entry with per-language strings */
 export type TextEntry = Record<string, string>;
 
 /** Options for engine.say() */
 export interface SayOptions {
-  from?: string | TextEntry;
+  from?: VylosCharacter;
   variables?: Record<string, string | number>;
 }
 
@@ -17,6 +18,17 @@ export interface ChoiceItem<T extends string = string> {
   condition?: () => boolean;
 }
 
+/** Inventory operations available to event authors via engine.inventory */
+export interface InventoryAPI {
+  add(bag: string, itemId: string, qty?: number): number;
+  remove(bag: string, itemId: string, qty?: number): number;
+  has(bag: string, itemId: string, qty?: number): boolean;
+  hasAll(bag: string, items: Record<string, number>): boolean;
+  count(bag: string, itemId: string): number;
+  list(bag: string): Array<[string, number]>;
+  clear(bag: string): void;
+}
+
 /**
  * The API available to event execute() functions.
  * This is what visual novel authors interact with.
@@ -46,6 +58,9 @@ export interface VylosAPI {
   /** End the current event */
   end(): never;
 
+  /** Inventory operations (add, remove, has, count, etc.) */
+  readonly inventory: InventoryAPI;
+
   /** Wait for a specified duration (ms) */
   wait(ms: number): Promise<void>;
 
@@ -81,7 +96,7 @@ export interface DrawableEventEntry {
 }
 
 /** A visual novel event definition */
-export interface VylosEvent<TState extends BaseGameState = BaseGameState> {
+export interface VylosEvent<TState extends VylosGameState = VylosGameState> {
   /** Unique event ID (derived from file path if not specified) */
   id: string;
 

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

@@ -1,5 +1,8 @@
-/** Base game state that all projects extend via Zod schema */
-export interface BaseGameState {
+import type { VylosCharacter } from './dialogue';
+import type { InventoryData } from './inventory';
+
+/** Base game state — projects extend this into their own GameState */
+export interface VylosGameState {
   /** Current location ID */
   locationId: string;
   /** In-game time (hours since game start, e.g. 14.5 = 2:30 PM) */
@@ -8,8 +11,8 @@ export interface BaseGameState {
   flags: Record<string, boolean>;
   /** Generic counters */
   counters: Record<string, number>;
-  /** Player data */
-  player: {
-    name: string;
-  };
+  /** Player character */
+  player: VylosCharacter;
+  /** Inventory data: bag/category ID -> item ID -> quantity */
+  inventories: InventoryData;
 }

package/src/engine/types/index.ts

@@ -5,6 +5,7 @@ export * from './locations';
 export * from './dialogue';
 export * from './save';
 export * from './game-state';
+export * from './inventory';
 export * from './plugin';
 export * from './checkpoint';
 export * from './config';

package/src/engine/types/inventory.ts

@@ -0,0 +1,26 @@
+import type { TextEntry } from './events';
+
+/** Category definition for organizing inventory items */
+export interface VylosCategory {
+  id: string;
+  name: string | TextEntry;
+  icon?: string;
+  sortOrder?: number;
+  /** Max distinct item types in this category (default: unlimited) */
+  maxSlots?: number;
+}
+
+/** Item definition with metadata */
+export interface VylosItem {
+  id: string;
+  name: string | TextEntry;
+  /** Category ID this item belongs to */
+  category: string;
+  /** Max stack size per slot (default: Infinity) */
+  maxStack?: number;
+  description?: string | TextEntry;
+  icon?: string;
+}
+
+/** Inventory data: bag/category ID -> item ID -> quantity */
+export type InventoryData = Record<string, Record<string, number>>;

package/src/engine/types/locations.ts

@@ -1,4 +1,4 @@
-import type { BaseGameState } from './game-state';
+import type { VylosGameState } from './game-state';
 import type { TextEntry } from './events';
 
 /** Background resolution entry — time-based or default */
@@ -20,7 +20,7 @@ export interface VylosLocation {
   backgrounds: BackgroundEntry[];
 
   /** Whether this location is accessible — defaults to true */
-  accessible?<TState extends BaseGameState>(state: TState): boolean;
+  accessible?<TState extends VylosGameState>(state: TState): boolean;
 }
 
 /** Location link (navigation graph edge) */
@@ -28,5 +28,5 @@ export interface LocationLink {
   from: string;
   to: string;
   /** Whether this link is currently traversable */
-  condition?<TState extends BaseGameState>(state: TState): boolean;
+  condition?<TState extends VylosGameState>(state: TState): boolean;
 }

package/src/engine/types/save.ts

@@ -1,4 +1,4 @@
-import type { BaseGameState } from './game-state';
+import type { VylosGameState } from './game-state';
 import type { Checkpoint } from './checkpoint';
 
 /** A single save slot */
@@ -10,7 +10,7 @@ export interface SaveSlot {
   /** Save format version for migration */
   version: number;
   /** Game state snapshot */
-  gameState: BaseGameState;
+  gameState: VylosGameState;
   /** Current event ID (if mid-event) */
   eventId: string | null;
   /** Checkpoint step number (if mid-event) */
@@ -22,7 +22,7 @@ export interface SaveSlot {
   /** Checkpoints for mid-event resume */
   checkpoints?: Checkpoint[];
   /** Game state before event started (for redo support after load) */
-  initialState?: BaseGameState;
+  initialState?: VylosGameState;
   /** Completed event history */
   history?: Array<{ eventId: string; checkpoints: Checkpoint[] }>;
   /** Current history navigation index */

package/src/engine/utils/deepMerge.ts

@@ -0,0 +1,40 @@
+/**
+ * Deep merge a source object onto a target object.
+ * Arrays are overwritten, but plain objects are merged recursively.
+ */
+export function deepMerge<T extends Record<string, any>>(target: T, source: Record<string, any>): T {
+    const output = { ...target };
+
+    for (const key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            const sourceValue = source[key];
+            const targetValue = output[key];
+
+            // If both are plain objects, merge recursively
+            if (
+                isPlainObject(sourceValue) &&
+                isPlainObject(targetValue)
+            ) {
+                (output as any)[key] = deepMerge(targetValue, sourceValue);
+            } else if (sourceValue !== undefined) {
+                // Otherwise grab the new value if defined
+                (output as any)[key] = sourceValue;
+            }
+        }
+    }
+
+    return output;
+}
+
+/** Check if an item is a plain object */
+function isPlainObject(item: any): item is Record<string, any> {
+    if (item === null || typeof item !== 'object') {
+        return false;
+    }
+
+    // Exclude arrays and dates/regexps
+    if (Array.isArray(item)) return false;
+
+    const proto = Object.getPrototypeOf(item);
+    return proto === Object.prototype || proto === null;
+}

package/src/engine/utils/devConsole.ts

@@ -0,0 +1,53 @@
+import type { Engine } from '../core/Engine';
+import type { VylosGameState } from '../types';
+import { logger } from './logger';
+
+export interface VylosConsole {
+  /** Current game state (read/write — changes are live) */
+  readonly state: VylosGameState;
+  /** Inventory shorthand */
+  readonly inventory: {
+    add(bag: string, itemId: string, qty?: number): number;
+    remove(bag: string, itemId: string, qty?: number): number;
+    has(bag: string, itemId: string, qty?: number): boolean;
+    count(bag: string, itemId: string): number;
+    list(bag: string): Array<[string, number]>;
+    clear(bag: string): void;
+  };
+  /** Raw engine reference */
+  readonly engine: Engine;
+}
+
+declare global {
+  interface Window {
+    Vylos: VylosConsole;
+  }
+}
+
+/** Attach `window.Vylos` for console cheating/debugging */
+export function attachDevConsole(engine: Engine, getState: () => VylosGameState): void {
+  const im = engine.inventoryManager;
+
+  Object.defineProperty(window, 'Vylos', {
+    configurable: true,
+    get() {
+      const state = getState();
+      return {
+        get state() { return state; },
+        get inventory() {
+          return {
+            add: (bag: string, itemId: string, qty?: number) => im.add(state.inventories, bag, itemId, qty),
+            remove: (bag: string, itemId: string, qty?: number) => im.remove(state.inventories, bag, itemId, qty),
+            has: (bag: string, itemId: string, qty?: number) => im.has(state.inventories, bag, itemId, qty),
+            count: (bag: string, itemId: string) => im.count(state.inventories, bag, itemId),
+            list: (bag: string) => im.list(state.inventories, bag),
+            clear: (bag: string) => im.clearBag(state.inventories, bag),
+          };
+        },
+        get engine() { return engine; },
+      };
+    },
+  });
+
+  logger.info('DevConsole ready — type Vylos in the browser console');
+}

package/src/index.ts

@@ -3,21 +3,17 @@ 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';
+export { deepMerge } from './engine/utils/deepMerge';
+export { attachDevConsole } from './engine/utils/devConsole';
+export type { VylosConsole } from './engine/utils/devConsole';
 export { assetUrl } from './utils/assetUrl';
 
 // Stores
@@ -29,10 +25,12 @@ 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 type { InventoryAPI } from './engine/types/events';
 export { CheckpointManager } from './engine/core/CheckpointManager';
 export { createEngine, getComponentOverride, clearComponentOverrides, DI_TOKENS } from './engine/core/EngineFactory';
 
 // Managers
+export { InventoryManager } from './engine/managers/InventoryManager';
 export { EventManager } from './engine/managers/EventManager';
 export { HistoryManager } from './engine/managers/HistoryManager';
 export { NavigationManager, NavigationAction } from './engine/managers/NavigationManager';

package/src/stores/gameState.ts

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

package/tests/engine/ActionManager.test.ts

@@ -1,14 +1,15 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { ActionManager } from '../../src/engine/managers/ActionManager';
-import type { VylosAction, BaseGameState } from '../../src/engine/types';
+import type { VylosAction, VylosGameState } from '../../src/engine/types';
 
-function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+function makeState(overrides: Partial<VylosGameState> = {}): VylosGameState {
   return {
     locationId: 'cafe',
     gameTime: 12,
     flags: {},
     counters: {},
-    player: { name: 'Alice' },
+    player: { id: 'alice', name: 'Alice' },
+    inventories: {},
     ...overrides,
   };
 }

package/tests/engine/CheckpointManager.test.ts

@@ -1,15 +1,16 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { CheckpointManager } from '../../src/engine/core/CheckpointManager';
-import type { BaseGameState } from '../../src/engine/types';
+import type { VylosGameState } from '../../src/engine/types';
 import { CheckpointType } from '../../src/engine/types';
 
-function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+function makeState(overrides: Partial<VylosGameState> = {}): VylosGameState {
   return {
     locationId: 'cafe',
     gameTime: 8,
     flags: {},
     counters: {},
-    player: { name: 'Alice' },
+    player: { id: 'alice', name: 'Alice' },
+    inventories: {},
     ...overrides,
   };
 }

package/tests/engine/EventManager.test.ts

@@ -1,15 +1,16 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { EventManager } from '../../src/engine/managers/EventManager';
-import type { VylosEvent, VylosAPI, BaseGameState } from '../../src/engine/types';
+import type { VylosEvent, VylosAPI, VylosGameState } from '../../src/engine/types';
 import { EventStatus } from '../../src/engine/types';
 
-function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+function makeState(overrides: Partial<VylosGameState> = {}): VylosGameState {
   return {
     locationId: 'cafe',
     gameTime: 8,
     flags: {},
     counters: {},
-    player: { name: 'Alice' },
+    player: { id: 'alice', name: 'Alice' },
+    inventories: {},
     ...overrides,
   };
 }

package/tests/engine/EventRunner.test.ts

@@ -1,21 +1,23 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { EventRunner, type EventRunnerCallbacks } from '../../src/engine/core/EventRunner';
-import type { VylosEvent, VylosAPI, BaseGameState } from '../../src/engine/types';
+import { InventoryManager } from '../../src/engine/managers/InventoryManager';
+import type { VylosEvent, VylosAPI, VylosGameState } from '../../src/engine/types';
 import { JumpSignal } from '../../src/engine/errors/JumpSignal';
 import { EventEndError } from '../../src/engine/errors/EventEndError';
 
-function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+function makeState(overrides: Partial<VylosGameState> = {}): VylosGameState {
   return {
     locationId: 'cafe',
     gameTime: 8,
     flags: {},
     counters: {},
-    player: { name: 'Alice' },
+    player: { id: 'alice', name: 'Alice' },
+    inventories: {},
     ...overrides,
   };
 }
 
-function makeCallbacks(state?: BaseGameState): EventRunnerCallbacks & { state: BaseGameState } {
+function makeCallbacks(state?: VylosGameState): EventRunnerCallbacks & { state: VylosGameState } {
   const s = state ?? makeState();
   return {
     state: s,
@@ -29,7 +31,7 @@ function makeCallbacks(state?: BaseGameState): EventRunnerCallbacks & { state: B
     onClear: vi.fn(),
     resolveText: vi.fn((text: unknown) => typeof text === 'string' ? text : 'resolved'),
     getState: vi.fn(() => s),
-    setState: vi.fn((newState: BaseGameState) => { Object.assign(s, newState); }),
+    setState: vi.fn((newState: VylosGameState) => { Object.assign(s, newState); }),
   };
 }
 
@@ -39,7 +41,7 @@ describe('EventRunner', () => {
 
   beforeEach(() => {
     callbacks = makeCallbacks();
-    runner = new EventRunner(callbacks);
+    runner = new EventRunner(callbacks, new InventoryManager());
   });
 
   describe('say()', () => {
@@ -66,18 +68,19 @@ describe('EventRunner', () => {
       expect(callbacks.onClear).toHaveBeenCalled();
     });
 
-    it('resolves speaker text', async () => {
+    it('passes Character object as speaker', async () => {
+      const barista = { id: 'barista', name: 'Barista' };
       const event: VylosEvent = {
         id: 'test-speaker',
         async execute(engine: VylosAPI) {
-          await engine.say('Hi!', { from: 'Barista' });
+          await engine.say('Hi!', { from: barista });
         },
       };
 
       const promise = runner.executeEvent(event);
 
       await vi.waitFor(() => {
-        expect(callbacks.onSay).toHaveBeenCalledWith('Hi!', 'Barista');
+        expect(callbacks.onSay).toHaveBeenCalledWith('Hi!', barista);
       });
 
       runner.resolveWait();
@@ -273,6 +276,93 @@ describe('EventRunner', () => {
     });
   });
 
+  describe('inventory API', () => {
+    it('add() delegates to InventoryManager with current state', async () => {
+      const event: VylosEvent = {
+        id: 'test-inv-add',
+        async execute(engine: VylosAPI) {
+          engine.inventory.add('backpack', 'potion', 3);
+        },
+      };
+
+      await runner.executeEvent(event);
+      expect(callbacks.state.inventories['backpack']?.['potion']).toBe(3);
+    });
+
+    it('has() reads current state', async () => {
+      callbacks.state.inventories = { backpack: { potion: 5 } };
+      let result = false;
+
+      const event: VylosEvent = {
+        id: 'test-inv-has',
+        async execute(engine: VylosAPI) {
+          result = engine.inventory.has('backpack', 'potion', 3);
+        },
+      };
+
+      await runner.executeEvent(event);
+      expect(result).toBe(true);
+    });
+
+    it('remove() mutates state', async () => {
+      callbacks.state.inventories = { backpack: { potion: 5 } };
+
+      const event: VylosEvent = {
+        id: 'test-inv-remove',
+        async execute(engine: VylosAPI) {
+          engine.inventory.remove('backpack', 'potion', 2);
+        },
+      };
+
+      await runner.executeEvent(event);
+      expect(callbacks.state.inventories['backpack']?.['potion']).toBe(3);
+    });
+
+    it('count() returns correct value', async () => {
+      callbacks.state.inventories = { backpack: { potion: 7 } };
+      let result = 0;
+
+      const event: VylosEvent = {
+        id: 'test-inv-count',
+        async execute(engine: VylosAPI) {
+          result = engine.inventory.count('backpack', 'potion');
+        },
+      };
+
+      await runner.executeEvent(event);
+      expect(result).toBe(7);
+    });
+
+    it('list() returns bag contents', async () => {
+      callbacks.state.inventories = { backpack: { potion: 3, sword: 1 } };
+      let result: Array<[string, number]> = [];
+
+      const event: VylosEvent = {
+        id: 'test-inv-list',
+        async execute(engine: VylosAPI) {
+          result = engine.inventory.list('backpack');
+        },
+      };
+
+      await runner.executeEvent(event);
+      expect(result).toEqual([['potion', 3], ['sword', 1]]);
+    });
+
+    it('clear() empties a bag', async () => {
+      callbacks.state.inventories = { backpack: { potion: 3, sword: 1 } };
+
+      const event: VylosEvent = {
+        id: 'test-inv-clear',
+        async execute(engine: VylosAPI) {
+          engine.inventory.clear('backpack');
+        },
+      };
+
+      await runner.executeEvent(event);
+      expect(callbacks.state.inventories['backpack']).toBeUndefined();
+    });
+  });
+
   describe('checkpoints', () => {
     it('captures checkpoint for each say', async () => {
       const event: VylosEvent = {

package/tests/engine/HistoryManager.test.ts

@@ -11,7 +11,7 @@ function makeCheckpoints(count: number): Checkpoint[] {
       gameTime: 8 + i,
       flags: {},
       counters: {},
-      player: { name: 'Alice' },
+      player: { id: 'alice', name: 'Alice' },
     },
     type: CheckpointType.Say,
   }));