Troubleshooting

Most VNC problems are either missing authoring data, stale compiled runtime data, or Roblox services that cannot be proven in preview. Start with the warning shown in Properties, Explorer, Story Map, or Output, then use the matching check below.

Missing or invisible assets

If a background, sprite pose, portrait, overlay, or sound is missing:

• Confirm the selected asset exists under the installed runtime StoryAssets folders.
• For imported assets, confirm the Roblox asset ID is valid and available to the place.
• Image-like fields need Roblox Image assets. If you are starting from a Decal, use its image content ID instead of the Decal asset ID. Sound fields need Roblox Audio assets.
• Built-in VNC assets are copied to runtime only when the current project references them, or when you save a demo project.
• Compile after changing asset references, then restart the Studio play session you are using to test.

If preview shows an asset but play mode does not, the preview may still be reading the plugin-side bundled asset. Compile and check the runtime StoryAssets hierarchy.

Runtime is missing or outdated

The installed runtime should include:

ReplicatedStorage.VisualNovelCreatorRuntime
ServerScriptService.VNCServer

Use Install / Update Runtime when those roots are missing, after updating the plugin, or when Output reports a runtime version mismatch. Ordinary story edits usually need Compile Project, not a full runtime reinstall.

The editable plugin bundle should not be left inside Workspace or ReplicatedStorage as VisualNovelCreatorPlugin. Only the installed runtime roots should remain in a playable place.

Runtime installation reports a reserved-name collision

VNC never deletes an Instance merely because it uses a runtime name. If Output reports a collision, inspect the exact path it names. Common reserved paths include the two runtime roots above, old client/server bootstrap locations, and top-level StoryAssets, StoryProjectSource, or StoryProject folders.

If the Instance belongs to your game or another plugin, rename or move it and retry. Complete historical VNC runtime installs and exact historical VNC data-only roots migrate automatically. If the collision is part of a partial older install, keep a place backup, remove the incomplete collision explicitly, and run Install / Update Runtime again. Do not rename unrelated content to imitate VNC ownership attributes.

A compile that encounters this refusal remains failed: VNC keeps the last successful compiled story and does not publish new runtime data. After resolving the collision, run Compile Project again; the retry performs installation before publishing the new artifact.

Compile looks stale

After changing story data, assets, styling, runtime menu fields, or extension settings:

1. Run Compile Project.
2. Fix any Output errors.
3. Restart the Studio play session before judging runtime behavior.

If a compile fails, VNC keeps the last successful compiled story installed so play testing does not fall to a blank or missing story. The runtime will not reflect the failed edit until a later compile succeeds.

If the installed runtime reports that the compiled story is invalid, read the data path in the runtime error, fix the corresponding project data, compile again, and reinstall the runtime. The runtime stays unavailable until it can load a valid compiled story.

Asset import does nothing

Asset import is strict by design. If import refuses an ID:

• Use a numeric asset ID or a valid Roblox asset URL.
• Remove extra spaces before or after the ID.
• Confirm the asset exists and is the right kind for the field.
• Confirm the asset is accessible to the place or account context Studio is using.

Failed imports should show a warning toast or Output message. If the editor blocks the import without feedback, treat that as a bug.

Saves do not persist

Studio play sessions are useful for menu and flow checks, but published-place style persistence needs a published test place.

Verify:

• The runtime is installed and current.
• The experience has DataStore access enabled for your test environment.
• You tested leave/rejoin behavior in a published or publish-equivalent place.
• The save slot does not point at a chapter, scene, or node that was deleted after the save was made.

If a slot says it belongs to a different story, VNC found an explicit story identity that does not match the currently installed project. This protects progress from being imported into another project that reuses the same internal target IDs. Load the slot with the story that created it, or overwrite it from the current story’s Save page.

Outdated saves should fail soft and explain that the saved checkpoint no longer matches the compiled story.

Text input behaves differently in preview

Preview can prove that the route reaches a Text Input node, but Roblox text filtering is runtime behavior.

Verify:

• The Text Input node targets a Text variable.
• Filtered Text is set to Use Filtered Branch if you want a recovery route when Roblox tags text.
• If Text Is Filtered points to a valid node when that branch is enabled.
• The installed runtime is being tested in Studio play or a published test place.

If filtering is unavailable in the current test context, the runtime may warn and use local text so the route remains testable.

Purchase or GamePass routes do not match expectations

Preview cannot prove real purchase prompts. Test Prompt Purchase, Owns GamePass, and related routes with the installed runtime.

Verify:

• Developer Product IDs are used for Developer Product prompts.
• GamePass IDs are used for GamePass prompts and GamePass condition checks.
• Purchased, Cancelled, and GamePass-only Already Owned routes are connected where your story needs them.
• Developer Product rewards are granted through Roblox receipt processing. The VNC Purchased branch waits until that receipt owner calls the server receipt integration; prompt closure alone is not proof of purchase.

Unsupported or unavailable MarketplaceService calls should fail soft and continue through a safe route rather than silently granting rewards.

Badge awards fail

Award Badge requires a real badge that belongs to the experience.

Verify:

• The Badge ID is a positive whole number.
• The badge belongs to the same experience you are testing.
• The installed runtime reaches the Award Badge node.
• BadgeService is available in the test context.

Preview can prove the story reaches the node. It cannot prove Roblox will award the badge.

Extension modules do not run

Runtime extension code is loaded only through the supported extension paths:

ReplicatedStorage.VisualNovelCreatorExtensions.Client.Buttons
ServerScriptService.VisualNovelCreatorExtensions.Server.Functions
ServerScriptService.VisualNovelCreatorExtensions.Server.Generated.Story

Verify:

• Project-level runtime extensions are enabled.
• Button extensions return function(button) ... end.
• Run Function modules live under ServerScriptService.VisualNovelCreatorExtensions.Server.Functions.
• Run Function modules return function(context) ... end.
• The selected Run Function module name exactly matches the ModuleScript name.
• The module loads without an error and its returned function does not throw.
• A Run Function that yields eventually resumes and returns. An indefinite yield leaves that player’s story waiting at the node.

The editor may scaffold and inspect supported module shapes, but it does not execute extension code while validating authoring data. Check Studio output for the surfaced load or invocation failure message.

If Output reports a duplicate-name or wrong-class extension path, inspect the exact path in the message. VNC refuses the whole setup, validation, or compile operation instead of deleting existing content or leaving a partial extension tree. Rename or move the conflicting Instance, then retry the action.

World interactions never fire

For World Wait, Runtime Action, roaming, teleport, and sprite activation issues:

• Test in Studio play with the installed runtime, not preview only.
• Confirm the Roblox instance path exists in the live place.
• Confirm the trigger kind matches the target: Touch part, ClickDetector, or ProximityPrompt.
• Confirm the player is actually in roaming/world mode when the interaction should happen.
• Confirm the next story node is connected so the runtime has somewhere to continue.

If the target exists only in a preview mock or plugin-only source tree, the installed runtime cannot see it.