NovelVisual (prototype)

Prototype visual novel engine and tooling.

Status: paused. This branch is open-sourced as-is while the project restarts on a new stack.

What’s here

• Haxe + Heaps runtime with a VN presentation pipeline (backgrounds, characters, dialogue, choices).
• NVSL scripting language (compiler + VM + bytecode).
• Two editors:
  • Haxe/Heaps editor (in-engine UI + stage preview).
  • C++ ImGui editor prototype (needVN) with node graph scaffolding.

Submodules

This repo uses submodules for Heaps and C++ editor dependencies.

git submodule update --init --recursive

Run the game (VN preview)

Build and run the Haxe/Heaps runtime:

haxe build.hl.hxml
./run.sh

Haxe editor (in-engine)

Build and run the Haxe editor build:

haxe build.editor.hxml
./run-editor-hx.sh

C++ editor (needVN)

Build and run the ImGui editor prototype:

cd needVN/build
cmake .. -DNEEDVN_BUILD_IMNODES=ON
make -j4
./bin/needVN

NVSL tools

Compiler + VM are available as HashLink binaries:

haxe build.nvslc.hxml
haxe build.nvslvm.hxml

# Examples:
./.deps/hashlink/hl ./bin/nvslc.hl <project> <out.nvbc> --entry game.app.main
./.deps/hashlink/hl ./bin/nvslvm.hl <out.nvbc>

Layout

• src/ — Haxe runtime, editor, NVSL compiler/VM
• demo-game/ — sample story project
• needVN/ — C++ editor prototype
• docs/ — language/runtime docs

Notes

• run.sh always launches the VN runtime.
• The Haxe editor is separate (run-editor-hx.sh).
• The C++ editor is built via CMake in needVN/.
• Demo assets are sourced from itch.io packs. Check each pack’s license before using them in a commercial project.

Demo video

License

See LICENSE. Note: submodules keep their own licenses.

Why NVSL instead of HScript?

Short answer: NVSL is purpose-built for VN workflows and long-term maintainability.

Reasons:

• Static types and stricter checks make story logic safer and easier to refactor.
• Deterministic execution + explicit runtime model makes save/load and rollback reliable.
• Bytecode VM gives predictable performance without relying on host reflection.
• Builtin API surface is intentionally small and sandboxed (no accidental OS access).
• Tailored error messages and source mapping for story teams.

HScript is great for fast iteration and dynamic behavior, and the macro approach can help performance. But for this engine, the VN‑specific constraints (save‑state safety, deterministic runtime, and controlled API surface) are easier to guarantee with a dedicated language and VM.