Extensions

Extensions are for advanced projects that need code without modifying the core runtime.

Most projects should start with Properties fields and built-in nodes. Extensions are for the cases where your story needs behavior that would be too specific to build into the plugin for everyone.

Extension model

VNC exposes a small, documented shape for user-authored modules. Instead of editing the runtime directly, you point the story to extension modules that match that shape.

The current supported seam is runtime button behavior. The conventional module path is:

ReplicatedStorage.VisualNovelCreatorExtensions.Client.Buttons

Use Runtime Menu > Button Extensions > Create Module in Properties to scaffold it, then enable extensions from plugin settings when the project intentionally uses trusted code.

Use built-in controls first

If a menu, dialog, sprite, or node property can express the behavior, prefer that.

Use extensions for project logic

If the behavior belongs to your game or story style, keep it in a small extension module.

Avoid runtime edits

Changing core runtime scripts directly makes updates harder and creates merge work later.

Safety

Extensions are disabled by default. Only enable them when the project intentionally uses trusted code.

VNC can check the conventional Buttons module shape without running your extension code from the editor. Runtime execution still happens in-game, so test extensions in a play session.

Why use the documented shape

The documented shape makes customization safer:

The core runtime remains updateable.
Extension modules have predictable button inputs.
Advanced users can get better autocomplete and type guidance.
Story authors do not need to request every possible styling or behavior option in the plugin UI.

Button module

The Buttons module must return one function. It receives a ButtonAdapter and may return a cleanup function.

--!strict

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Runtime = ReplicatedStorage:WaitForChild("VisualNovelCreatorRuntime")
local Contracts = require(Runtime:WaitForChild("ExtensionContracts"))

return function(button: Contracts.ButtonAdapter): (() -> ())?
  if button.Role == Contracts.ButtonRoles.Primary then
    return button:OnHoverChanged(function(isHovered)
      button:SetScale(if isHovered then 1.04 else 1)
    end)
  end
end

The adapter exposes:

Member	Use
`Id`	Stable button ID from `Contracts.ButtonIds`.
`Role`	Broad role from `Contracts.ButtonRoles`.
`Instance`	The underlying `GuiButton`.
`Metadata`	Button-specific metadata table.
`SetText(text)`	Change visible button text.
`SetEnabled(enabled)`	Enable or disable interaction.
`SetScale(scale)`	Apply presentation scale.
`SetTransparency(transparency)`	Apply presentation transparency.
`OnHoverChanged(callback)`	Subscribe to hover state. Returns cleanup.
`OnPressedChanged(callback)`	Subscribe to pressed state. Returns cleanup.
`OnActivated(callback)`	Subscribe to activation. Returns cleanup.

Button IDs and roles

Contracts.ButtonIds.RuntimeMenu.NewGame
Contracts.ButtonIds.RuntimeMenu.Continue
Contracts.ButtonIds.RuntimeMenu.Settings
Contracts.ButtonIds.RuntimeMenu.ChapterSelect
Contracts.ButtonIds.RuntimeMenu.SaveGame
Contracts.ButtonIds.RuntimeMenu.LoadGame
Contracts.ButtonIds.RuntimeMenu.Log
Contracts.ButtonIds.RuntimeMenu.Return
Contracts.ButtonIds.RuntimeMenu.Close
Contracts.ButtonIds.RuntimeMenu.OpenMenu

Contracts.ButtonIds.SaveLoad.SaveSlot
Contracts.ButtonIds.SaveLoad.LoadSlot
Contracts.ButtonIds.SaveLoad.PreviousPage
Contracts.ButtonIds.SaveLoad.NextPage
Contracts.ButtonIds.Settings.AutoAdvance
Contracts.ButtonIds.Settings.DeleteStoryData
Contracts.ButtonIds.ChapterSelect.Chapter

Contracts.ButtonIds.Confirmation.Confirm
Contracts.ButtonIds.Confirmation.Cancel

Contracts.ButtonRoles.Primary
Contracts.ButtonRoles.Secondary
Contracts.ButtonRoles.Danger
Contracts.ButtonRoles.Navigation
Contracts.ButtonRoles.Slot

Use these constants instead of hardcoded strings. That keeps your extension aligned when button text or layout changes.

A good extension workflow

Confirm the behavior cannot be expressed with existing nodes or properties.
Enable extensions in plugin settings.
Create the extension module using the documented module shape.
Keep the module focused on one behavior.
Test the behavior in a Studio play session, not only in preview.

Keep extension code cosmetic or presentation-oriented unless a future extension point explicitly allows game-state changes. That boundary keeps the core runtime updateable.

Extensions are part of the beta surface. Check Beta Limitations before depending on them for a release-critical workflow.