A lightweight, web-based runtime for Visual Novels.
This library renders the story data generated by the Hikarin Framework.
⚠️ Important: This viewer is designed to play scripts created using the Hikarin Framework Python SDK. You do not need to write the JSON manually.👉 Get the SDK here: github.com/Iteranya/hikarin-framework
Great for static sites or quick testing. Add this to your HTML <head>:
<script src="https://unpkg.com/hikarin-vn-viewer@latest/dist/hikarin-vn-viewer.umd.js"></script>Great for bundlers (Vite, Webpack, React, Vue).
npm install hikarin-vn-viewer- Export your script using the Python SDK (e.g.,
story.json). - Create a container in your HTML.
- Initialize the viewer by fetching your JSON.
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/hikarin-vn-viewer@latest/dist/hikarin-vn-viewer.umd.js"></script>
</head>
<body>
<!-- 1. The Container (Set a width/height or let it fill the screen) -->
<div id="vn-container" style="width: 1000px; margin: 0 auto;"></div>
<script>
// 2. Fetch the JSON generated by the Python SDK
fetch('./story.json')
.then(res => res.json())
.then(scriptData => {
// 3. Initialize the Engine
const vn = new window.HikarinVN('vn-container', scriptData, {
assetsPath: "./assets/", // Path to your images folder
debug: false, // Set to true during development
globals: {} // Initial Save Data (optional)
});
// 4. Start the game
vn.start();
})
.catch(err => console.error("Could not load script:", err));
</script>
</body>
</html>| Option | Type | Default | Description |
|---|---|---|---|
assetsPath |
string |
"" |
The base URL or local folder where your images are stored. The SDK generates relative paths (e.g., chars/cupa.png), and the viewer prepends this path to them. |
debug |
boolean |
false |
Enables the visual Debug Panel, showing active variables, engine state, and sprite bounding boxes. |
globals |
object |
{} |
Inject an object here to load Save Data or set initial flags (e.g., { affection: 10 }). |
If your story isn't behaving correctly, set debug: true in the configuration.
- The Debug Panel: A UI will appear below the game window.
- Globals: Shows persistent variables (Affection, Story Flags).
- Locals: Shows temporary variables for the current scene.
- Status: Shows the current engine state (PLAYING, WAITING, CHOICE).
- Sprite Boxes: Sprites will have colored borders to help you visualize their alignment and padding.
- Console Logs: Open your browser's Developer Tools (F12). The engine provides color-coded logs for every step, logic check, and jump.
The Hikarin Framework SDK defines image paths in your Python script.
- If your Python script says:
characters/cupa/happy.png - And your Viewer config is:
assetsPath: "https://my-game.com/static/" - The browser will load:
https://my-game.com/static/characters/cupa/happy.png
Ensure your web server's folder structure matches the folder structure used in your Python project.