Skip to content
Visual Novel Creator

Runtime Overview

The runtime is the playable system installed into your Roblox game. It is what players see when they start the visual novel, open the menu, save, load, change settings, and advance through the story.

The plugin is for creators. The runtime is for players.

If you have not installed it yet, start with Install the Runtime. Use this page when you want to understand what that installed bundle is responsible for.

Runtime features

Section titled “Runtime features”

Menu flow

Main menu, new game, continue, return-to-menu, settings, log, and chapter select.

Save flow

Save slots, load slots, autosave, continue, chapter unlocks, completed stories, and player settings.

Story presentation

Dialog, choices, text input, sprites, image and parallax backgrounds, overlays, audio, title cards, transitions, and player input.

Runtime rules

The installed runtime keeps story state, text filtering, saves, purchase prompts, and world-facing actions consistent during play.

Runtime responsibility split

Section titled “Runtime responsibility split”

The runtime tracks the active story session, save data, text input filtering, and actions that affect the experience world.

Player actions are accepted only when the story is waiting for them. For example, Choose only matters while a Choice node is active.

The runtime supports click/tap controls plus Roblox’s newer Input Action system for story advance, opening the menu, and back/close commands.

On touch screens, the dialog text itself follows the same reveal-first behavior as the other advance controls. When a skippable line is still typing, the first tap completes it. A later tap advances once the story is waiting. Dragging the text to scroll a long line does not count as a tap, so players can read without skipping ahead.

Session flow

Section titled “Session flow”

Starting a new game creates a session from the story’s Story Starts At chapter and that chapter’s first scene. If chapter title cards are enabled and the entry scene starts a chapter, the runtime queues the title card before advancing into nodes.

Runtime requests are state-aware:

  • Advance works only when the session is waiting for advance input or a timer.
  • Choose works only when the session is waiting for a Choice node, and locked options stay locked during play.
  • Submit Text Input works only when the session is waiting for a Text Input node, and the target must be a Text variable. If Roblox returns tagged text, the node can route to If Text Is Filtered instead of storing that value when Filtered Text is set to Use Filtered Branch.
  • Resolve Choice Timeout works only for a timed Choice with a configured timeout target.
  • Purchase prompt outcomes work only while a Prompt Purchase node is waiting. Preview and unsupported contexts follow Cancelled; live GamePass and Developer Product prompts need the installed runtime.
  • Activate Sprite works only for an interactable sprite that matches the waiting sprite or slot.
  • Resolve World Trigger works only while a World Wait node is active.

When a route moves into a purchase prompt or another interactive wait without showing new dialog, the completed line stays in place while that wait updates. If a later Dialog node intentionally repeats the same speaker and text, VNC still treats it as a new line.

This is why runtime testing matters. Preview can show the authored path, but the installed runtime proves the real play rules.

Save behavior

Section titled “Save behavior”

The runtime keeps player-facing save actions responsive while preserving the current story checkpoint. Save and load entries display authored chapter and scene names when available, while stable IDs remain behind the scenes.

VNC saves runtime checkpoints. A checkpoint can include the current chapter, scene, node, variables, render state, effect sequence, wait flags, world trigger fields, timer duration, log entries, and end state. This is more precise than saving only a scene number.

The default player save document contains:

  • version = 1
  • settings: autoAdvanceEnabled = false, textSpeed = 1, bgmVolume = 1, sfxVolume = 1
  • no unlocked chapters beyond the entry chapter summary logic
  • no completed stories
  • no autosave
  • no manual saves

Settings are normalized before use. Text speed is clamped from 0.5 to 2; BGM and SFX volume are clamped from 0 to 1.

Manual saves cannot overwrite the autosave slot. Save summaries include the slot ID, save time, chapter, scene, node, display title, and current background when that data exists. The save/load menu shows up to 100 slots, with 6 slots per page.

If a save points to a scene, node, or chapter that no longer exists, VNC marks the slot as an outdated save. Players cannot load that slot, but they can overwrite it from the Save page.

When a story ends, VNC records completed-story progress separately from loadable checkpoints. Continue keeps the last playable autosave instead of replacing it with the ended screen.

In published places, VNC stores player save documents through profile storage backed by ProfileStore. If a player’s save profile is still being released by another server, the runtime asks them to wait instead of opening stale data.

Logs and continue

Section titled “Logs and continue”

The runtime log records dialog and choice entries, including prompt text and whether a timed choice resolved through timeout. The log keeps up to 200 entries.

Continue restores the autosave checkpoint when one exists. Loading a manual slot restores that slot’s checkpoint with the current player settings.

Testing

Section titled “Testing”
  1. Preview inside the plugin while authoring a scene.
  2. Compile the project.
  3. Install or update the runtime.
  4. Start a Studio play session to test menu and story behavior.
  5. Use a published test place for save persistence checks because local Studio behavior is not always the same as a live game.

Use Testing Runtime for the beta checklist before shipping a route.