cheap-web-sound-novel-engine

A lightweight, framework-free web-based sound novel (visual novel) engine for TypeScript projects.

Features

• Scene-based storytelling: Define scenes with narration, dialogue, choices, and conditional branching
• Typewriter text animation: Configurable text display speed
• Choice system: Branching narratives with flag-based conditional next scenes
• Save/Load system: 3-slot save system with localStorage persistence
• Audio controls: BGM/SE playback with fade transitions and volume controls
• Text speed settings: Configurable text display speed with localStorage persistence
• Title screen: Background rotation, ripple effects, save slot display
• Multi-language support: Separate SCSS and locale files for each language
• Zero dependencies: No framework required, pure TypeScript/JavaScript

Installation

npm install cheap-web-sound-novel-engine
# or
pnpm add cheap-web-sound-novel-engine

Quick Start

import { StoryEngine, bootstrap, createFlagStore } from 'cheap-web-sound-novel-engine';
import type { StoryManifest, Scene, FlagDefinition } from 'cheap-web-sound-novel-engine';

// Define your game data
const manifest: StoryManifest = {
  title: 'My Game',
  chapters: []
};

const flags: Record<string, FlagDefinition> = {};

// Bootstrap the engine
const engine = await bootstrap(manifest, flags, document.getElementById('game-container')!);
await engine.initialize();

Importing Styles

// English version
@use 'cheap-web-sound-novel-engine/scss/en/style.scss';

// Japanese version
@use 'cheap-web-sound-novel-engine/scss/ja/style.scss';

Or use the compiled CSS:

<link rel="stylesheet" href="node_modules/cheap-web-sound-novel-engine/css/en/style.css">

Exports

Classes

• StoryEngine: Main game engine with scene management, typewriter text, choices, save/load
• AudioController: BGM/SE playback with fade transitions

Functions

• bootstrap: Initialize the engine
• createFlagStore: Create flag store for conditional scene branching
• createResourceLookup: Create resource lookup helper
• loadAudioSettings / saveAudioSettings: Audio settings persistence
• loadTextSettings / saveTextSettings: Text settings persistence
• bindVolumeControls: Bind UI controls to audio settings
• bindTextSpeedControl: Bind UI controls to text settings
• loadResources / loadUiStrings: Title screen utilities
• renderSaveSlots / createSaveSlotCard: Save slot UI helpers

Types

• StoryManifest, Scene, SceneLine, Chapter
• CharacterDefinition, FlagDefinition, Resources
• SaveData, SaveSlot
• UIStrings
• AudioSettings, TextSettings

Building

npm run build

Output is generated in dist/ directory.

Development

npm run dev

Starts a development server with hot reload.

License

MIT