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.

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.

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, not only by reaching the story branch.

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.

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.