Concept Mapping

Use this page as a translation guide when rebuilding an SVNE story in VNC.

Story structure

SVNE concept	VNC concept	Notes
`vnm.registerChapter()`	Chapter entity	VNC chapters use stable IDs and user-facing names.
`scenes = { "intro", "choiceScene" }`	Chapter scene list	VNC stores scene order in project data.
`vnm.registerScene()`	Scene entity	A VNC scene owns nodes and a start node.
Scene function body	Node chain	Each story action becomes a node.
`story.playChapter(1)`	Runtime start / chapter start request	Runtime checks chapter availability.

Dialog and flow

SVNE API or pattern	VNC node or property	Notes
`vnm.dialog()`	Dialog node	Speaker, portrait, text, cues, scroll speed, skippable, and advance behavior are Properties fields.
`waitForAdvanceInput = false`	Dialog node with no advance input	Use auto-advance delay for authored timing.
`vnm.waitForAdvanceInput()`	Dialog, title card, or wait state	Most waits are represented by node properties instead of manual yields.
`task.wait(seconds)`	Wait node	Use a wait node for authored pacing.
`vnm.titleCard()`	Title Card node	Project-level chapter title cards are also supported.
`vnm.scheduleCue()`	Dialog cues	Cues are data on the dialog node.

Choices and conditions

SVNE API or pattern	VNC node or property	Notes
`vnm.promptChoice()`	Choice node	Each option has text, optional condition, and a target node.
`choicesUnlocked`	Choice option condition	Locked options are driven by variables and conditions.
`variableName` on a choice	Choice variable	VNC stores selected option IDs in a string variable when configured.
Timed choice fallback	Choice timeout path	VNC can route to a timeout target and use default timeout values when fields are left unset.
`if choice == 1 then ...`	Choice branches	Connect each option to its target node.
`if vnm.getStoryVariable(...) then ...`	Condition node	Conditions are explicit and visible in the Story Map.
`vnm.setStoryVariable()`	Set Variable node	Supports typed variable operations.

Assets and presentation

SVNE API or pattern	VNC node or property	Notes
`vnm.setBackground()`	Background node	Supports transition kind and duration.
`vnm.addColorCover()` / `addImageCover()`	Overlay node	Use overlay mode, color/image, transparency, and transition fields.
`vnm.playSound()`	Audio or SFX node	Use Audio for tracks and SFX for one-shots.
`vnm.stopAudioTrack()`	Audio node with stop action	Track IDs are explicit.
`linkSubjectToScrollSoundSet()`	Subject defaults or Scroll Sound Link node	Use subject configuration for stable defaults.
`linkSubjectToPortrait()`	Subject defaults or Portrait Link node	Use subject configuration when possible.
Color or image cover	Overlay node	Use `image`, `color`, or `clear` overlay mode.

Sprites

SVNE API or pattern	VNC node or property	Notes
`vnm.createSprite()`	Sprite Enter node	The sprite asset is explicit; the node does not create missing assets automatically.
`sprite:setImage()`	Sprite Update node	Use pose fields for character sprite variations.
`sprite:reposition()` / `resize()`	Sprite slot fields or Sprite Update position fields	Prefer project sprite slots for repeatable layouts.
`autoPosition`	Sprite position mode: Auto	VNC has deterministic auto positioning without copying SVNE’s source structure.
`vnm.exitStage()`	Sprite Exit node	Supports transition kind and duration.
`vnm.emphasize()` / `deemphasize()`	Effect node or dialog auto-emphasis	Dialog can emphasize by speaker; effects can target sprites explicitly.
`sprite.jump()` / `shake()`	Effect node or sprite transition	Use effect nodes for one-shot motion.

Runtime UI

SVNE feature	VNC equivalent	Notes
Main menu	Runtime menu	Title, subtitle, background, music, sounds, and colors are Properties fields.
Save/load UI	Runtime save/load	Uses authored names for display and stable IDs for consistency.
Settings UI	Runtime settings	Persists player settings through the runtime.
Chapter select	Runtime chapter select	Uses unlocked chapter IDs and authored chapter names.
Log	Runtime log	VNC stores runtime log entries as part of session/checkpoint state.

Custom behavior

SVNE pattern	VNC approach	Notes
Editing engine scripts	Avoid when possible	Prefer Properties fields and documented extension points.
Scene-local custom Luau	Future function nodes or runtime extensions	Keep custom code behind documented extension points.
`vnm.logStoryConnection()` cleanup	Runtime-owned waits and world interactions	VNC should own cleanup for built-in node behavior.
Roaming mode	Roaming and world interaction nodes	Use explicit nodes for world transitions and waits.
Custom button behavior	Runtime button extension	Use `ReplicatedStorage.VisualNovelCreatorExtensions.Client.Buttons` with the documented button module shape.

What may not map one-to-one

Some SVNE scripts use arbitrary Luau side effects inside scene functions. VNC should not automatically import that kind of logic. Rebuild the story using native nodes first, then isolate truly custom behavior into an extension.