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 of Naninovel, feel free to ignore the scene-related information altogether, as Naninovel will take care of that.

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 a software perspective.

Create New Unity Project

With the core concepts in mind, let's start the initial setup. The first thing you'd need is a Unity project. Consult Unity manual ↗ on how to create one.

When creating a project you'd probably like to use 2D Template to set the editor in 2D behaviour mode, 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 you create a new project, Unity will automatically add a sample scene with two game objects inside it: a "Main Camera" and "Directional Light". Naninovel is completely scene-independent, so you can remove those two objects from the scene so they don't produce any unnecessary performance overhead. You can also remove the sample scene itself, though it's recommended to have at least one scene in a project for some editor features to work correctly.

TIP

Disable Reload Domain and Reload Scene options under "Enter Play Mode" project settings to enter play mode faster.

Install Naninovel

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 is the most tested and stable release: it's been receiving bug fixes over a year and battle-tested by the most users. However, it's also the most outdated one 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.

See the guides below on how to access the release of your choice.

Final Release on Asset Store

Naninovel on the Unity's Asset Store is updated once per year with final releases only. To access stable and preview releases, see the guide below.

Import the package via Asset Store menu ↗ and wait for the initial scripts compilation and assets import process. You are free to move Naninovel package folder anywhere inside your project assets directory, if you wish.

WARNING

Don't store, modify or delete anything inside Naninovel folder. Any such change will be lost when the package is updated and we won't provide any support for the modified versions of the package.

Preview and Stable Releases on GitHub

Preview and stable releases are distributed as UPM packages via 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 GitHub: github.com/naninovel/docs/releases ↗.

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. Usually, installing GitHub Desktop ↗ and logging in with your user account is sufficient. Refer to the Unity guide for more info on authentication: docs.unity3d.com/Manual/upm-config-https-git.html ↗.

TIP

Over the course of using Naninovel a number of assets (configuration, settings, saves, etc) will be automatically generated inside Assets/NaninovelData folder. Don't modify the contents of the folder or move it (it'll be automatically regenerated). If you wish to change the location of the data folder, use Generated Data Path property in the engine configuration menu.

Add Naninovel Script

Use Create -> Naninovel -> Naninovel Script assets context menu to create a naninovel script asset.

NOTE

You can create and store naninovel scripts (as well as all the other Naninovel resources) under any project folder and organize them in any way you like; the naming is also up to you. The above illustration is just an example.

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 name 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 and 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

Video Guide

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

Demo Project

Complete sources of the demo project (the same one showcased on the store) are available on GitHub ↗.

You can clone the repository with a Git client ↗ or download it as a zip archive ↗. Be aware, that assets distributed with the demo project may be subject to custom licenses and are provided solely for learning purposes.

WARNING

Naninovel package is not distributed with the project, hence compilation errors will be produced after opening it for the first time; importing the package will resolve the issues.