A node-based authoring tool for building interactive video experiences and artistic games. Authors compose a directed graph of scenes, decisions, conditions, and state mutations in a visual editor; the engine compiles it into a self-contained, offline-capable playable package with localization support, customizable runtime styling, menu and pause flows, save/resume support, and configurable presentation.
- Author interactive graphs — Open the editor in a browser and build a node graph:
- Scene nodes — layered video compositing, audio tracks, optional background music, per-layer looping, scene looping, auto-continue, conditional decisions, keyboard-mapped decisions, and an end flag.
- State nodes — SpEL expressions that mutate global variables such as
#VISIT_COUNT = #VISIT_COUNT + 1. - Condition nodes — ordered boolean conditions with else/fallback routing.
- Manage assets, localization, and presentation — Upload video/audio assets, organize folders, tag media, define locales, edit subtitles and translated decision labels, and assign scene-level properties such as background color, decision timeout behavior, and default decisions.
- Preview quickly — Compile individual scenes or transitions at preview resolution and watch the result in-browser without leaving the editor.
- Validate graphs before export — Catch missing root nodes, missing default decisions, decisions without matching outgoing edges, invalid transition targets, missing else branches, and unreachable nodes.
- Customize the runtime — Edit runtime CSS in dedicated tabs, tune project settings, and control runtime options such as menu flow, button styling, keyboard-only decision input, subtitles, locale selection, music behavior, and display preferences.
- Compile and export — Run the full pipeline: FFmpeg compositing → HLS conversion → manifest generation → packaging. The editor produces a runnable
dist/folder and adist.zipbundle. - Play offline or self-host — Extract
dist.zipand run./start.sh(Linux/macOS) orstart.bat(Windows). Openhttp://localhost:8090in any browser — no internet connection required for local playback.
- Visual graph authoring with React Flow for scene, state, and condition nodes.
- Scene editing with layered video compositing, audio tracks, layer ordering, start offsets, freeze-last-frame support, and per-layer looping.
- Scene properties including end nodes, auto-continue, scene-level loop video, background color, and background music selection.
- Decision authoring with default decisions, keyboard hotkey assignment, conditional availability expressions, and scene decision ordering.
- State mutation nodes using Spring SpEL.
- Conditional branching with ordered condition nodes and explicit else/fallback logic.
- Localization tools for locale management, scene subtitles, and translated decision labels.
- Asset management for upload, folder creation, tagging, and media browsing.
- Validation tooling for root/end-node issues, missing default decisions, missing scene decision edges, invalid transition targets, missing else branches, and unreachable nodes.
- Preview compilation for individual scenes and transitions.
- Project settings for assets/output paths, preview and compile resolutions, FPS, audio settings, decision timeout, default locale, default background color, FFmpeg threads, hidden decision buttons, and input indicators.
- Custom CSS editing split into
buttons.css,subtitles.css, andcustom.css, plus an in-editor runtime CSS reference tab. - Auto-save of project state in the embedded SQLite database.
- Main menu with Continue, New Game, and Settings actions.
- Pause overlay for in-game control and quick access to settings.
- Settings panel for music volume, video volume, music toggle, button placement, button colors, subtitles on/off, locale selection, and resolution.
- Save/resume support with saved-game detection and Continue flow.
- Offline playback from the packaged runtime bundle.
- Background music playback during scenes, with current music preserved when a scene does not override it.
- Localized subtitles and translated decision labels when locales are configured.
- Freeze-frame decision UI when a scene ends and the player needs to choose the next path.
- Keyboard decision input with per-decision hotkeys, optional visible key hints, and project-level hidden-button mode.
- Bottom-screen input indicator for keyboard-only decision mode.
- Decision timeout fallback for automatic default-choice selection.
- Conditional decisions evaluated from current runtime state.
- Scene auto-continue when no explicit decision is required.
- Looping scene playback while waiting for decisions when enabled.
- Decision, transition, and next-scene preloading to keep playback smooth.
- End screen with replay and return-to-menu actions.
- Self-contained Java server/client bundle for local or hosted playback.
- Compiled multi-resolution HLS output for scenes and transitions, with master playlists for browser-friendly delivery.
- Generated manifest filtered to the reachable graph and localization content used by the game.
- Included runtime styling files with
default.css,buttons.css,subtitles.css, andcustom.css. - Bundled startup scripts and package README for quick local launch on Linux/macOS and Windows.
- Referenced background-music assets copied into the package so exported projects remain self-contained.
- Runnable
dist/folder plusdist.ziparchive for distribution. - Cross-platform output for Linux and Windows.
- For interactive storytelling — It gives creators a structured way to build branching narratives without hand-coding every path.
- For artistic games and video essays — The engine is well-suited to experiences where video, audio, and decisions are the core medium.
- For rapid iteration — The editor supports previews, asset management, and in-browser authoring, which makes experimentation faster.
- For offline distribution — The final package can run without internet access, making it practical for exhibitions, installations, and local demos.
- For customization — Runtime CSS and settings let creators tailor the player presentation to their project identity.
- For maintainability — The graph model, manifest-driven compilation, and separated editor/runtime architecture keep the system easier to extend.
engine/
├── docs/
│ ├── system-design.md Full system design, graph rules, and design decisions
│ └── tasks.md Ordered implementation tasks with completion status
│
├── editor/
│ ├── README.md Editor setup, running instructions, full API reference
│ ├── backend/ Java Spring Boot backend (REST API, FFmpeg, SQLite)
│ └── frontend/ React + React Flow frontend (Vite, TypeScript, Tailwind)
│
├── runtime/ Compiled runtime — lightweight Java server + web client
│
├── mockup/ Early UI mockup (React, not production code)
│
└── README.md This file
| Goal | Document |
|---|---|
| Understand the design and data model | docs/system-design.md |
| Check implementation progress | docs/tasks.md |
| Set up and run the editor | editor/README.md |
| Browse the full REST API reference | editor/README.md → API Reference |
Quickest way to run the editor and start a new project is to download available binaries in releases.
| Tool | Version | Notes |
|---|---|---|
| Java JDK | 21+ | java -version |
| Maven | 3.9+ | mvn -v |
| Node.js | 18+ | node -v |
| FFmpeg | Any recent | ffmpeg -version — required for compilation and preview |
# Easy way on linux
./build.shOr make native binary
./build-native.sh
Or
# 1. Build the frontend
cd editor/frontend
npm install
# 2. Build and start the backend. It will host frontend too.
cd editor/backend
mvn package -DskipTests
java -jar target/editor-backend-{VERSION}.jar # replace with valid versionOpen http://localhost:8080 in a browser.
# Extract the dist.zip downloaded from the editor, then:
./start.sh # Linux / macOS
start.bat # WindowsOpen http://localhost:8090 in a browser.
- Editor backend — Java 21, Spring Boot, SQLite (Flyway migrations), Spring SpEL
- Editor frontend — React 18, React Flow, Vite, TypeScript, Tailwind CSS
- Video processing — FFmpeg (CLI, abstraction layer)
- Compiled runtime — Lightweight embedded Java HTTP server, hls.js (bundled, no CDN)
- Streaming — HLS (
.m3u8+.tssegments), multi-resolution
