@utavn/core

The engine, types, stores, and components for UtaVN — a checkpoint-based visual novel engine built with Vue 3 and TypeScript.

Features

• Checkpoint-based execution — engine.say() and engine.choice() pause via async/await, rollback via re-execute + fast-forward (like Ren'Py)
• Rollback & history — full forward/back navigation through past dialogue
• Save/load with mid-event resume — checkpoint system preserves exact position
• Inventory system — bag-based engine.inventory.add/remove/has/count/list/clear
• Location & action managers — time-of-day backgrounds, linked locations, conditional actions
• Drawable events — clickable characters/objects on screen
• i18n — string | Record<string, string> for multi-language support
• Plugin system — component overrides + custom Pinia game store via a single UtaVNPlugin object
• Dev console — window.UtaVN for debugging and cheating (state, inventory, engine)
• H key — hide all UI to view artwork (Ren'Py style)
• AZERTY/QWERTY auto-detect — keyboard input adapts automatically

Install

pnpm add @utavn/core

Requires Vue 3 and Pinia.

Usage

import {
  createEngine,
  GameShell,
  useEngineStateStore,
  ENGINE_INJECT_KEY,
  type UtaVNEvent,
  type UtaVNEventAPI,
  type UtaVNGameState,
} from '@utavn/core';

Writing events

const intro: UtaVNEvent = {
  id: 'intro',
  conditions: (state) => !state.flags['intro_done'],
  async execute(engine: UtaVNEventAPI, state: UtaVNGameState) {
    await engine.say('Welcome!');

    const pick = await engine.choice([
      { text: 'Start', value: 'start' },
      { text: 'Learn more', value: 'more' },
    ]);

    if (pick === 'more') {
      await engine.say('Events pause at each say() and choice().');
    }

    state.flags['intro_done'] = true;
  },
};

Extending types

import type { UtaVNCharacter, UtaVNGameState } from '@utavn/core';

interface Character extends UtaVNCharacter {
  portrait?: string;
}

interface GameState extends UtaVNGameState {
  player: Character;
  energy: number;
}

Inventory

async execute(engine: UtaVNEventAPI, state: GameState) {
  engine.inventory.add('backpack', 'potion', 3);

  if (engine.inventory.has('backpack', 'key')) {
    engine.inventory.remove('backpack', 'key', 1);
    await engine.say('You used the key.');
  }
}

Key bindings

| Key | Action | |-----|--------| | Space / Enter / E | Advance dialogue | | D / Arrow Right | Forward | | A / Q / Arrow Left | Back | | H | Toggle UI visibility | | S | Toggle skip mode | | Escape | Pause menu |

Documentation

Full docs and examples: gitlab.com/xchanbik-vn/utavn

License

MIT