Getting Started

Prerequisites

Naninovel is an extension for the Unity game engine ↗, so it's strongly recommended to at least learn the basics ↗ of using the engine before starting with Naninovel.

In case you're not going to build any custom gameplay outside Naninovel, feel free to ignore the scene-related information altogether, as Naninovel will take care of that.

Create New Unity Project

When creating a project we recommend choosing Built-in Render Pipeline (BiRP) template. While Universal (URP) and High Definition (HDRP) will generally work as well, they have limitations compared to the built-in renderer, require additional setup and support for them is limited; fine more info in the render pipelines guide.

Choosing 2D or 3D depends on the style of the game you're building. For most standard visual novels we recommend choosing 2D, so that images will be imported as sprite assets by default and you won't have to manually change the import settings. You can change the editor behaviour mode later using the project settings ↗.

When creating new project, Unity automatically includes a sample scene with "Main Camera" and (in some templates) "Directional Light" game objects inside it.

Naninovel is scene-independent, hence we recommend removing those objects from the scene to prevent unnecessary performance overhead or conflicts with Naninovel systems. You can also remove the sample scene itself, though it's recommended to keep at least one scene in a project for some editor features to work correctly.

Optimizing Editor Performance

This step is optional but recommended to significantly improve editor startup, reload and enter play mode times.

First, go to Edit -> Project Settings -> Editor menu and select Do not reload Domain or Scene under "Enter Play Mode Settings" option to reduce the time it takes to enter play mode.

Now, open and inspect manifest.json file at the "Packages" folder stored under the Unity project root. It lists all the installed packages and modules. Depending on the template, Unity includes many modules by default, while you'll most likely never need most of those, while each of them increases the time of the editor startup and code reload. Below are the modules required by Naninovel; consider removing all the other entries, in case they are not needed:

Packages/manifest.json

{
    "dependencies": {
        "com.unity.modules.audio": "1.0.0",
        "com.unity.modules.video": "1.0.0",
        "com.unity.modules.imgui": "1.0.0",
        "com.unity.modules.uielements": "1.0.0",
        "com.unity.modules.particlesystem": "1.0.0",
        "com.unity.modules.imageconversion": "1.0.0",
        "com.unity.ugui": "2.0.0"
    }
}

VCS Setup

In case you're using a version control system, such as Git, consider ignoring following paths to prevent unnecessary churn:

.gitignore

# Auto-generated Unity assets of transient nature.
/Assets/NaninovelData/Transient*
# Transient artifacts of the external tools.
/Assets/NaninovelData/.nani/Transient*

— note that Assets/NaninovelData is an auto-generated folder. After it's initially generated, you can rename or move it to any folder under Assets (Naninovel will still be able to locate it), in which case the above ignore paths have to be updated accordingly.

EXAMPLE

Find .gitignore ↗ in our samples project for an example Git ignore profile. Notice how NaninovelData folder in the project is renamed to just Naninovel and moved under Assets/Profiles for organization purposes — you're free to move the folder in a similar fashion in your own project.

Install Naninovel

Release Streams

Naninovel is distributed across 3 release streams: preview, stable and final.

Preview is the bleeding edge: it's updated most often and has all the latest features. However, it's subject to occasional breaking changes and bugs. Pick this stream when you're early in development or need a specific feature not available in the other releases.

Stable is the middle-ground: it only receives bug fixes, doesn't have the latest features, but is also free from any breaking changes. It's recommended in most cases.

Final, while being the most tested and stable one, is also the most outdated and is not covered by the tech support. Only stay on the final release in case the project is already released and it's not possible to upgrade.

Stable stream is published on both GitHub and Unity's Asset Store (though not as often as on GitHub), while preview and final streams are only available on GitHub.

Install from GitHub

All the release streams are distributed via a UPM registry hosted on a private GitHub repository. To access the repository, register your Naninovel license ↗ and follow the instructions on the dashboard.

Once you have access to the repository, go to Window -> Package Manager in Unity editor and add https://github.com/naninovel/upm.git#X.X as a Git package, where X.X is the Naninovel release version you'd like to install, for example 1.20. You can find all the available releases and their versions on the releases page ↗.

If you get an error when installing the package, make sure you're authenticated (on the local machine) as the GitHub user, which was assigned in the account dashboard; refer to the Unity guide for more info on authentication ↗.

Install from Package

It's also possible to install Naninovel from a .unitypackage file. In case you've purchased Naninovel on the Unity's Asset Store, use "My Assets" tab of the package manager ↗. Otherwise, you can get the package from our download archive ↗.

NOTE

Asset Store packages and the download archive are updated 2-3 months later than the UPM repository and don't include preview releases, so we recommend installing Naninovel directly from GitHub for the latest updates.

Core Concepts

Before setting up and using Naninovel, let's skim through some of the core concepts.

An essential one, which you will constantly encounter in the rest of the guide, is actor. Actor is an entity described by an identifier (ID), appearance, position in space (scene) and some other parameters.

Actor is an abstract entity and can't exist directly; instead, specialized versions with various additional parameters are used:

Actor Type	Additional Parameters	Description
Character	Look Direction	Represents a character on scene.
Background	None	Represents a background on scene; placed behind character actors by default.
Text Printer	Text, Author ID, Reveal Progress	Gradually reveals (prints) text messages over time.
Choice Handler	Choices	Allows player to pick one of the available choices.

Consider a typical visual novel setup, with a character portrayed on top of a background. In Naninovel terms, it will be represented in the following way.

Now, let's say you want to make "Kohaku" character look happy. You have several textures (images) of that character, each portraying different emotion. In Naninovel such textures are called appearances of an actor. To achieve the goal, we have to change appearance of the character actor. Similarly, to make "MainBackground" display something else, we have to change appearance of that background actor.

Actors and their parameters are controlled (directed) via commands specified in naninovel scripts.

Another widely used concept is user interface (UI). UIs are used by player to interact with actors and the rest of the game. This includes various menus (title, save-load, settings, etc) and control panels (toggle auto read mode, skip text, etc). UI elements are positioned on top of actors by default.

Text printers and choice handlers are considered both actors and UI elements, meaning they share actor qualities and can be controlled via naninovel scripts, while, at the same time, used by players to interact with the game.

In case you're familiar with programming, take a look at the engine architecture to get a grasp on how it's designed from the software engineering perspective.

Add Naninovel Script

Use Create -> Folder assets context menu and create a "Scenario" folder, under which all the Naninovel scenario script assets will be stored. Then, under the created folder, click Create -> Naninovel -> Naninovel Script to create your first scenario script.

NOTE

You can store Naninovel scripts (and other resources) in any project folder and organize them however you like; naming is also entirely up to you. However, note that all scenario scripts must be stored within a single root directory. You can create as many nested folders as needed for organizational purposes, as long as all sub-folders eventually resolve to a common root within the Unity project.

WARNING

Unity treats folders named Resources in a special manner: assets stored under such folders are force-included to the build, which may cause performance issues ↗. Most importantly, never store anything under Resources/Naninovel folder, unless specifically required in the guide, as this may cause all sorts of conflicts and undefined behaviour.

Naninovel scripts are text documents (.nani extension) where you control what happens on scenes. You can open and edit them with a text editor of your choice, like Microsoft Word, Google Docs or VS Code ↗.

You can also use visual script editor to edit the naninovel scripts. Select the created script asset and you'll see the visual editor automatically open in the inspector window.

To add a new line to the script, either right-click the place, where you want to insert the line, or press Ctrl+Space (you can change the default key bindings in the input configuration menu) and select the desired line or command type. To re-order lines, drag them using their number labels. To remove a line, right-click it and choose "Remove".

When you've changed the script using visual editor, you'll see an asterisk (*) over the script path in the inspector header. That means the asset is dirty and need to be saved; press Ctrl+S to save the asset. In case you'll attempt to select another asset while the script is dirty, a dialogue window will pop up allowing to either save or revert the changes.

The visual editor will automatically sync edited script if you update it externally, so you can seamlessly work with the scripts in both text and visual editors.

NOTE

In the rest of this guide we will use a text editor, but you can repeat all the same steps with the visual editor, if you wish.

In order for a Naninovel-related asset (like our created script) to become "visible" for the engine, it should be assigned as a project resource. When creating the scripts via the create assets menu, they're assigned automatically. To assign (or edit/remove) a script resource manually use script resources window accessible with Naninovel -> Resources -> Scripts editor context menu. To add a script, press + (plus sign) button in the list to add a new record and drag-drop script asset to the list. It's also possible to drag-drop multiple assets or even whole folders to the list to add them in batch.

Open the created script in a text editor and add the following text:

Hello World!
@stop

The first line will print the text "Hello World!" when the game is run and the second is required to gracefully stop script execution.

Enter play mode and start a new game to see the result.

NOTE

All the available built-in script commands, supported parameters and usage examples are listed in the API reference. It's also possible to add custom commands; see the guide for more information.

In case "NEW GAME" button of the title menu is not active, make sure Start Game Script property in the script configuration (Naninovel -> Configuration -> Scripts) is equal to the name of the created script.

Add Character

Characters in Naninovel can be based on regular and diced sprites, animated Live2D or Spine models and 3D meshes; you can add your own implementations as well. For the purpose of this tutorial, we’ll use a sprite implementation.

Each character is represented by ID and a set of appearances. To add a character, use character manager GUI accessible via Naninovel -> Resources -> Characters menu, add a new character actor record specifying its ID, then double-click the record (or press button at the end of the record) and add all the appearance sprites to the Resources list. Just like with naninovel scripts, you can drag-drop multiple assets and folders to the list.

Let’s assume the added character ID is "Kohaku". Edit naninovel script to show the added character:

@char Kohaku
Hello World!
@stop

Run the game and you’ll see one of the character appearance sprites at the center of the screen. When you don’t specify an appearance, either the one named equal to character's ID or "Default" will be chosen by default. To select a specific appearance, add its name after the character ID separated by a dot like this:

@char Kohaku.Happy
Hello World!
@stop

Given there is an appearance with the name "Happy" added for the character "Kohaku", the corresponding sprite will now be shown instead of the default one.

You can now associate the printed text with the character by adding its ID followed by a colon before the text:

@char Kohaku.Happy
Kohaku: Hello World!
@stop

It's also possible to join character's appearance with the printed text to save some typing:

Kohaku.Happy: Hello World!
@stop

To hide a character (or any other actor, like background, text printer, etc), use @hide command followed by actor ID:

Kohaku.Happy: Hello World!
@hide Kohaku
@stop

Add Background

Similar to characters, a background can be represented in multiple ways in Naninovel: sprite, generic object, video and scene; custom user implementations are also possible.

While you can create multiple independent background actors, in a typical VN game you'll usually use just one and transition it to different appearances. To simplify the routine, a MainBackground actor is added to the background actors list by default and you don't have to specify the ID every time to change its appearance in naninovel scripts.

Add background sprites via Naninovel -> Resources -> Backgrounds menu. MainBackground record will open automatically, but you can still return to the actors list and create others, if you wish.

Let’s assume the added background appearance sprite is named "City". To show a background, use a @back command followed by the background appearance name:

@back City

When switching between backgrounds a cross-fade transition effect will be used by default. To change the effect, specify transition type after the appearance name:

@back City
@back School.RadialBlur

This will transition "City" to "School" using "RadialBlur" transition effect.

To reference a background other than the main one (eg, in case you wish to compose multiple backgrounds on top of each other), specify ID of the actor. For example, given a background actor with ID Flower exists beside the main one, following commands will change its appearance to "Bloomed" and then to "Withered":

@back Bloomed id:Flower
@back Withered id:Flower

Add Music and Sound Effects

To add a BGM (background music) or SFX (sound effect) asset, use Naninovel -> Resources -> Audio editor menu. You can use any audio formats supported by Unity ↗.

Let’s assume the added BGM file name is "ThePromenade". To play this track as a background music use @bgm command followed by the name of the track:

@bgm ThePromenade

A cross-fade effect will be automatically applied when switching the music tracks. The music will loop by default, though you can change this, as well as volume and fade duration using command parameters.

On the contrary, sound effects won't loop by default. Assuming you've added an "Explosion" SFX, use an @sfx command to play it back:

@sfx Explosion

TIP

Over the course of using Naninovel a number of assets (settings, resources, various caches, etc) will be automatically generated under Assets/NaninovelData folder. You're free to move or rename the folder, just make sure to not store it under a "Resources" folder, as it'll cause conflicts.

Video Guide

In case you prefer following video guides, here is one illustrating the above instructions.

Demo Project

In case your prefer to learn from a complete solution, check the sample project, which contains the complete sources of the demo showed on the website.