UGTK cat mascotUGTKengine within an engine Request access

UGTK / Toolkit / Gameplay Systems / Visual Novel System In progress

Gameplay Systems — UGTK

Visual Novel System

Summary

The Visual Novel System is a complete, node-based framework for building story-driven games and interactive narratives inside Unity with minimal custom code.
Designers can author chapters, dialogues, choices, variables, checkpoints, movements, fades, events and timers directly in a dedicated graph editor, while programmers integrate the runtime managers with UI, audio and other UGTK or custom Framework.
The system supports branching flows, conditional logic, autoskip, checkpoints, chapter selection menus and save/load of player progress, making it suitable for full-length visual novels and story-heavy games.

Commercial-grade player features (2026-07): multi-slot saves with screenshot thumbnails + quicksave/autosave (Mn_VNSaveManager), rollback ("back one line", Mn_VN_GameManager.Back()), dialogue backlog/history with voice replay (Mn_VNBacklog), read/unread line tracking with skip modes (VN_ReadLinesTracker, SetSkipMode), player settings for text speed / auto-advance / auto-voice (VN_Settings), per-line voice-over with auto-voice naming convention (voiceKey / VO_{chapterId}_{blockId}), background crossfade transitions, variable interpolation in text ({variableName}), CG gallery & unlockables (VN_Unlockables, SO_VNGalleryDatabase), hide-UI screenshot mode.

AI game generation (unique on the market): Mn_VNClaudeStoryGenerator generates ENTIRE playable visual novels via the Claude API (Anthropic) from configurable fields (premise, genre, tone, language, chapters, cast). Structured outputs guarantee valid JSON; block ids, graph wiring and editor layout are generated by code — never by the model — so the imported graph is always consistent. Characters and backgrounds get procedural placeholder art so the generated game is playable immediately; the generated visualDescription fields are ready-to-use prompts for final art. The API key is NEVER stored in assets (PlayerPrefs / env var / runtime only). Claude does not generate bitmap images: final art comes from your artist or an external image provider.

Content

Modules Dependencies

The Visual Novel System integrates with several UGTK modules:

Setup

  1. Create or assign a VN project asset
  2. Open the editor window with UGTK/Visual Novel Editor.
  3. In the top toolbar, assign an existing SO_VNProject or click New Project... to create a new visual novel project.

  4. The editor will automatically create and link all required VN databases if they are missing.

  5. Check databases in SO_VNProject

  6. In the inspector of SO_VNProject make sure the following fields are assigned:

    • SO_VNChapterDatabase
    • SO_VNCharacterDatabase
    • SO_VNBackgroundDatabase
    • SO_VNDialogueDatabase
    • SO_VNChoiceDatabase
    • SO_VNConditionDatabase
    • SO_VNSetFlagDatabase
    • SO_VNModifyIntDatabase
    • SO_VNCheckpointDatabase
    • SO_VNMovementDatabase
    • SO_VNBackgroundBlockDatabase
    • SO_VNFadeOverlayDatabase
    • SO_VNEventDatabase
    • SO_VNTimerDatabase
    • SO_VNSoundDatabase
    • SO_VNTextBlockDatabase
    • SO_VNPortraitBlockDatabase

  7. Create the UI in a scene

  8. Add a Canvas with:

    • A background Image for scene art.
    • Left and right portrait Image for characters.
    • A TextMeshProUGUI for the speaker name (optionally inside a container RectTransform with left/right/center anchors).
    • TextMeshProUGUI fields for:
    • Dialogue text (Mn_TextTyperComponent – main text).
    • Optional message text (Mn_TextTyperComponent – secondary text).
    • Optional title text (Mn_TextTyperComponent – title).
    • A “Next” button for advancing dialogues.
    • A root GameObject to host choice buttons for player choices.

  9. Add the main manager

  10. Add Mn_VN_GameManager to the scene and assign:
    • project: your SO_VNProject.
    • startChapterId: optional; if empty, the manager uses the first chapter by order.
    • Character position transforms: positionOffLeft, positionOffRight, positionLeft, positionRight, positionCenter.
    • UI references: backgroundImage, fadeOverlayImage, leftPortrait, rightPortrait.
    • Name UI: speakerNameText, speakerNameContainer, speakerNameLeftAnchor, speakerNameRightAnchor, speakerNameCenterAnchor.
    • Text typers: dialogueTextTyper, messageTextTyper, titleTextTyper.
    • Choices: choiceManager, choicesRoot.
    • Optional: chapterSelectManager, nextReadyButton, sharedTimer, typingAudioUser.

  11. Set autoStart true if you want the VN to start automatically on OnEnable, or false if you will start it from code.

  12. Configure characters and backgrounds

  13. In the VN databases:
    • Define characters (S_VNCharacter) with ids, display names, portraits, base facing and name colors/fonts.
    • Define backgrounds (S_VNBackground) with ids and sprites.

  14. In SO_VNProject.variables define bool and int VN variables used for branching and checkpoints.

  15. Switch to the graph view

  16. In UGTK/Visual Novel Editor:
    • In Chapters mode, create chapters and set their ids, titles and order.
    • Double?click a chapter to open its Chapter Graph, where you can create and connect all VN blocks.

How To Use

Authoring chapters and blocks

  1. Create chapters
  2. In Chapters mode, add new chapters to the SO_VNProject.

  3. For each chapter, set:

    • id: internal unique id (also used for checkpoints and save data).
    • title: player?visible name in the chapter selection UI.
    • order: numeric order used to decide which chapter is first and how progression works.

  4. Build the chapter graph

  5. Double?click a chapter to open its graph.
  6. Use the left block toolbar to add:
    • Dialogue blocks (S_VNDialogueBlock) for spoken lines.
    • Choice blocks (S_VNChoiceBlock) for branching options.
    • Condition blocks (S_VNConditionBlock) for flag/int?based branching.
    • Set Flag / Modify Int blocks (S_VNSetFlagBlock, S_VNModifyIntBlock) for changing VN variables.
    • Checkpoint blocks (S_VNCheckpointBlock) for saving progress.
    • Movement blocks (S_VNMovementBlock) for character movement between positions.
    • Background blocks (S_VNBackgroundBlock) for changing background art.
    • Fade Overlay blocks (S_VNFadeOverlayBlock) for fading overlay, background, characters or dialogue UI.
    • Event blocks (S_VNEventBlock) for invoking custom UnityEvents.
    • Timer blocks (S_VNTimerBlock) for timed waits.
    • Sound blocks (S_VNSoundBlock) for playing/pausing/stopping sounds.
    • Text blocks (S_VNTextBlock) for non?dialogue text in different UI targets.
    • Portrait blocks (S_VNPortraitBlock) for controlling which portraits appear on left/right.
  7. Connect each block’s next (and nextIfTrue / nextIfFalse, choice options, etc.) to build the narrative flow.
  8. Set the chapter’s startNode so the runtime knows where to begin.

Controlling the VN at runtime

Basic bootstrap:

using UGTK.Framework.VisualNovel;
using UnityEngine;

public class VNBootstrap : MonoBehaviour
{
    [SerializeField] private Mn_VN_GameManager vnManager;

    private void Start()
    {
        if (vnManager != null)
            vnManager.PlayFromFirstChapter();
    }

    public void PlaySpecificChapter(string chapterId)
    {
        if (vnManager != null)
            vnManager.PlayChapter(chapterId);
    }

    public void ContinueFromCheckpointOrFirst()
    {
        if (vnManager != null)
            vnManager.PlayFromCheckpointOrFirstChapter();
    }
}

Advancing dialogues with a button:

using UGTK.Framework.VisualNovel;
using UnityEngine;

public class VNNextButton : MonoBehaviour
{
    [SerializeField] private Mn_VN_GameManager vnManager;

    public void OnClickNext()
    {
        if (vnManager != null)
            vnManager.Next();
    }
}

Working with VN variables from code

using UGTK.Framework.VisualNovel;
using UnityEngine;

public class VNVariablesExample : MonoBehaviour
{
    [SerializeField] private Mn_VN_GameManager vnManager;

    public void GrantSecretPath()
    {
        if (vnManager == null) return;

        vnManager.SetFlag("UnlockedSecretPath", true);
        vnManager.AddToInt("AffinityPoints", 5);
    }

    public bool HasUnlockedSecretPath()
    {
        return vnManager != null && vnManager.GetFlag("UnlockedSecretPath");
    }
}

Checkpoints and saves

using UGTK.Framework.VisualNovel;
using UnityEngine;

public class VNSaveMenu : MonoBehaviour
{
    [SerializeField] private Mn_VN_GameManager vnManager;

    public void RestartFromCheckpoint(string checkpointIdOrName)
    {
        if (vnManager != null)
            vnManager.RestartFromCheckpoint(checkpointIdOrName);
    }

    public void DeleteCheckpointOnly()
    {
        if (vnManager != null)
            vnManager.DeleteCheckpointSave();
    }

    public void DeleteAllVNData()
    {
        if (vnManager != null)
            vnManager.DeleteSaveData();
    }
}

Testing Scene

A typical test setup can include the following demo scenes:

  1. Basic flow
  2. A scene with:
    • Mn_VN_GameManager wired to:
    • A background image.
    • Left/right portraits.
    • A dialogue TextMeshProUGUI + Mn_TextTyperComponent.
    • A “Next” button.
    • A SO_VNProject with:
    • One chapter.
    • A few characters and backgrounds.
    • A linear sequence of dialogue, background and portrait blocks.

  3. Goal: verify basic text typing, speaker name placement and next?button behaviour.

  4. Branching and checkpoints

  5. A scene that:
    • Uses choice blocks, condition blocks, SetFlag/ModifyInt blocks.
    • Uses checkpoint blocks and the PlayFromCheckpointOrFirstChapter() API.
    • Provides a small chapter select menu via ShowChapterSelectMenu() and Mn_ChapterSelectManager.

  6. Goal: test branching logic, save/load and chapter completion.

  7. Advanced integration

  8. A scene demonstrating:
    • Movement blocks moving characters between positions.
    • Fade overlay blocks affecting background, characters and dialogue UI.
    • Timer blocks for timed events.
    • Sound blocks playing BGM and SFX through the UGTK Audio System.
    • Event blocks triggering external gameplay, UI transitions or analytics.

You can optionally document these scenes by adding GIFs/screenshots hosted in your repository.

Technical Info

The Visual Novel System is composed of several main parts:

© 2026 Marcello De Bonis. All rights reserved

Real dependenciesOpen in the map →

Depends on 10

Used by 0

  • No other module depends on it.

Measured from the repository: code references (asmdef) plus prefab and asset GUIDs. Importing this module alone brings in 22 modules in total.

More in Gameplay Systems.

all 18 →

Tris System

Tic-tac-toe in four variants — classic, matriosca, sliding and inception — with an AI opponent whose difficulty is selectable.

Completed

Tournament System

Tournament framework for managing brackets, users and match progression.

Completed

Checkpoint System

Save points that remember where the player was, and restore them after a death.

Completed

First Person 3D

First-person character controller: movement, look, jump and ground handling, driven from UI or keys.

Completed
Request access All tools Report an issue
← previousLoading Systemnext →Platform 2D Framework