Lightweight HTML/CSS/JS visual novel engine built for vertical screens.
Offline • No build tools • Portrait-first • 4K vertical display ready
A lightweight offline visual novel engine built with HTML, CSS, and JavaScript.
Designed for vertical screens, portrait displays, and real-world installations — from kiosks to 4K TVs.
No setup. No dependencies. Just open index.html and start.
- 📱 UI optimized for vertical screens
- 🖥 optimized for 4K displays
- 📐 interface ratio 7:16, with support for other aspect ratios
- 🌐 fully offline
- ⚡ no build tools or frameworks required
- 🧾 simple text-based scripting format
- 🖼 support for backgrounds
- 🎭 characters and emotions
- 💬 dialogue system
- 🔀 branching storylines
- 🎵 background music support
- 📊 built-in resource loading statistics
- 📘 Specifications: Story scripting, Mini-games
Also supports horizontal mode:
Script validation and graph generation in Mermaid format.
Graph rendering inside the engine with navigation support. Useful for debugging scripts and detecting unreachable nodes (marked in red).
This engine is suitable for:
- interactive stories
- museum installations
- exhibition stands
- educational projects
- university interactive displays
- browser-based narrative games
- vertical information kiosks
project/
│
├── index.html
├── story.js
├── README.md
├── LICENSE
├── NOTICE.md
├── FIRST-STEPS.md
├── FIRST-STEPS-RU.md
│
├── engine/
│ ├── engine.css
│ ├── engine.js
│ └── story-loader.js
│
├── docs/
│ └── specs/
│ ├── SPEC-STORY.md ← scripting specification
│ └── SPEC-GAME.md ← mini-game specification
│
├── lib/
└── assets/
├── backgrounds/
├── characters/
├── audio/
└── games/
- Download the latest version:
-
Extract the archive.
-
Open index.html in your browser.
The engine runs completely offline.
Use these guides for the recommended workflow: story idea → draft script → optional mini-games → integration → testing.
Use GitHub Discussions for questions, ideas, feedback, and showcase posts.
- Q&A — setup help, scripting questions, engine behavior, and unexpected errors
- Ideas — feature suggestions, scripting improvements, and workflow ideas
- Show and Tell — projects, demos, experiments, and screenshots made with the engine
- Issues are disabled by design
- Projects are disabled by design
- Use Discussions instead of issue reports for questions, feedback, and unexpected problems
- Pull requests are disabled by design
For versioned updates and downloads, see Releases.
To add top and bottom margins (useful for floor-mounted displays), use URL parameters:
index.html?topSpacing=500&bottomSpacing=800
Replace 500 and 800 with your desired values (in pixels).
The script is stored in story.js as a text block.
Example:
window.STORY_TEXT = `
[meta]
title = Demo Story
startScene = intro
lang = en
[bg]
campusHall file=assets/backgrounds/bg-campus-hall.jpg
[char]
anna emotion=neutral file=assets/characters/ch-anna-neutral.png name="Anna" color=#0F0
anna emotion=smile file=assets/characters/ch-anna.png # add another emotion for anna
igor emotion=neutral file=assets/characters/ch-igor-neutral.png name="Igor" color=#F00
igor name="Igor" file=assets/characters/ch-igor-smile.png # if emotion is omitted, neutral is used
igor color=#F00 # values can also be extended in separate lines
[audio]
bgmDay file=assets/audio/bgm-campus-day.mp3
[var]
resultGame = 0
[game]
gameCoffeeRush file=assets/games/coffee-rush.html
[scene]
scene intro
bg hall
show anna neutral
anna: "Welcome to the demo."
menu
"Go to the lab" -> lab_scene
"Go to the cafe" -> cafe_scene
scene cafe_scene
game gameCoffeeRush difficulty=3 result=resultGame
if resultGame == 1 -> good_end
if resultGame == 0 -> bad_end
`;scene scene_id
bg backgroundId
show character emotion
hide all
Character:
anna: "Text"
Narrator:
"Text"
menu
"Option 1" -> scene_a
"Option 2" -> scene_b
goto scene_id
bgm musicId
bgm musicId loop
bgm stop
The engine supports embedding mini-games via iframe.
This includes:
- initialization via
gameInit - returning results via
gameResult - strict rules required for compatibility
The UI is designed for tall vertical displays.
Available settings:
- top spacing
- bottom spacing
This allows adapting the interface for very tall screens and vertical TVs.
- no save/load system
- minimalistic script format
The engine is focused on simple interactive projects and installations.
The engine source code (engine/engine.js, engine/engine.css, index.html,
engine/story-loader.js) is licensed under the MIT License.
Copyright (c) 2026 Ilya Barilo
See the full license text in the LICENSE.
All media files located in the assets/ folder - including character
images, backgrounds, videos, audio files, and other materials used in
the demo novel - are NOT covered by the MIT License.
These files are provided for demonstration purposes only. You are not allowed to use them in your own projects (commercial or non-commercial) without obtaining separate permission from the copyright holder.
When creating your own stories using this engine, you must replace all demo assets with your own content.
This project uses the following open-source libraries:
- Purpose: visualization of story graphs in debug and analysis mode
- File:
lib/mermaid.min.js(version 11.x) - License: MIT (see NOTICE.md for details)
- Usage: included in the repository without modifications, works fully offline
Detailed information about licenses and usage terms of third-party software can be found in the NOTICE.md file.
- save/load system
- animations
- additional scripting commands
Mermaid is updated manually as new versions are released.