Handbook overview
Understand the authoring workflow and choose a path from your first scene to a native game release.
PrismatiXEngine is a visual novel engine with a native C++ Player. You primarily edit .pxstory scripts, JSON content definitions, and assets. Add a JavaScript extension when you need custom behavior. Your first story does not require learning C++, implementing a menu, or writing a save interface.
Understand the four layers
| Layer | What you author or run | Execution environment |
|---|---|---|
| Story and content | Dialogue, choices, characters, assets, configuration | Compiled during authoring; executed by the native runtime |
| CLI / authoring SDK | Project creation, validation, preview, packaging | Node.js on the author's machine |
| Extensions | Custom Story commands, UI Actions, game logic | QuickJS-NG embedded in the Player |
| Player / Preview | Graphics, sound, interaction | Native applications, not Node.js applications |
@prismatix/authoring-sdk is a build-time tool. @prismatix/runtime supplies extension types and a thin facade; it does not put Node.js into your game. TSX UI also generates native UI data during the build rather than rendering a React website.
Recommended reading order
Start with Getting started, Project structure, and Your first complete story. Then add Variables and control flow and Assets. This path reuses the CLI's bundled character and background so you do not need to collect artwork or generate a collection of identifiers before writing dialogue.
For custom presentation and behavior, continue with UI, Extensions, Runtime APIs, and Animation and effects. Before shipping, read Localization, Saves and compatibility, and Packaging. Keep the CLI reference, Story reference, and Troubleshooting available while working.
Conventions used throughout this handbook
Unless stated otherwise, shell commands run from the parent of my-game/. Inside the project, replace the my-game argument with .. A JSON merge fragment belongs in the existing object or array; it is not a replacement for the entire project file. Only examples explicitly labeled as complete replacements should overwrite a whole file.
Story blocks use a plain-text code fence for documentation compatibility; save the actual script with the .pxstory extension. JSON does not accept comments or trailing commas. Asset paths in examples are illustrative filenames, not automatic downloads: supply the actual files before validating them.
Version and support boundaries
This handbook describes engine source snapshot 89e1f71e97ed1c61397ef795dc51909706fc6ba3, reviewed on 2026-09-22, for the 0.2.0 candidate interface. The upstream installation interface exists, but testing candidate packages does not establish public npm publication. Windows x64, Linux x64, and macOS x64/arm64 are intended desktop targets; check release evidence for your exact version and platform.
Preview is not a packaged game. Successful edits currently restart the scene, and Preview Save/Load slots are session-only checkpoints. WASM is a Studio Preview path, not a promise of full web-game distribution. Relevant chapters explain these distinctions in detail.
Sources: Engine README, Runtime SDK, Release audit.