A lightweight, modular TypeScript-based visual novel engine for creating interactive stories in the browser.
EasyVN provides a simple yet powerful framework for building visual novels with features like character dialogue, sprite management, branching narratives, and interactive choices. Built with TypeScript for type safety and modern web standards.
- Create characters with multiple sprites and expressions.
- Smooth character positioning and movement.
- Chainable method calls for fluid scene composition.
- Organize stories into discrete scenes with backgrounds.
- Smooth transitions between scenes.
- Scene registration with metadata support.
- Advanced routing system for complex story paths.
- Label-based navigation with
goto/jumpmechanics. - Conditional story branching.
- Click-to-continue dialogue system.
- Multiple choice decision points.
- Asynchronous choice handling.
- Background management with automatic switching.
- Character sprite positioning (left, center, right).
- Smooth animations and transitions.
The engine is built with a modular architecture:
- Character: Manages character sprites, dialogue, and positioning.
- Engine: Core scene management and background handling.
- Router: Advanced navigation and branching logic.
- Choices: Interactive decision point system.
- VN: Utility class for simple scene playback.
Follow the installation instructions to set up EasyVN.
- To download this module separately, run:
npm i easyvn - To quickly set up a project, run:
npx create-vn my-vn cd my-vn npm run dev
Your HTML needs these key elements:
#background- Background image element.#character- Character sprite element.#textbox- Dialogue container.#speaker- Character name display.#dialogue- Dialogue text display.#choices- Choice buttons container.
Organize assets in the following directories:
./assets/characters/- Character sprites../assets/backgrounds/- Background images.
The fundamental unit of your story. Each scene is an async function that can contain dialogue, choices, and navigation.
Entities with names, sprites, and the ability to speak and move around the scene.
A powerful system for creating branching narratives with labels and conditional jumps.
Interactive decision points that can trigger different story paths or character reactions.
- Character: Character class for managing sprites and dialogue.
- VN: Utility class for simple scene playback.
- waitClick: Promise-based click waiting.
- showChoice: Interactive choice system.
- startScene, registerScene, setBackground, gotoScene, jumpToScene: Scene management.
- runNextRouteIfAny, route, goto: Advanced routing system.