Characters are actors used to represent scene entities that are placed on top of the backgrounds.

A character actor is defined with a name, appearance, visibility, transform (position, rotation, scale) and look direction. It can change appearance, visibility, transform and look direction over time.

Characters' behavior can be configured using Naninovel -> Configuration -> Characters context menu; for available options see configuration guide. The characters' resources manager can be accessed using Naninovel -> Resources -> Characters context menu.

Add Character

In naninovel scripts, characters are mostly controlled with @char command:

; Shows character with name `Sora` with a default appearance.
@char Sora

; Same as above, but sets appearance to `Happy`.
@char Sora.Happy

; Same as above, but also positions the character 45% away from the left border
; of the screen and 10% away from the bottom border; also makes him look to the left.
@char Sora.Happy look:left pos:0.45,0.1

Display Names

In the character configuration you can set a Display Name for specific characters. When set, display name will be shown in the printer name label UI, instead of the character's ID. This allows using compound character names, that contains spaces and special characters (which is not allowed for IDs).

For localization, use "CharacterNames" managed text document, which is automatically created when running generate managed text resources task. Values from the "CharacterNames" document won't override values set in the character metadata when under the source locale.

It's possible to bind a display name to a custom variable to dynamically change it throughout the game via naninovel scripts. To bind a display name, specify name of the custom variable wrapped in curly braces in the character configuration menu.

You can then change the variable value in the scripts and it will also change the display name:

@set PlayerName="Mistery Man"
Player: ...

@set PlayerName="Dr. Stein"
Player: You can call me Dr. Stein.

It's also possible to use the name binding feature to allow player pick their display name using @input command:

@input PlayerName summary:"Choose your name."
Player: You can call me {PlayerName}.

Message Colors

When Use Character Color is enabled in the character configuration, printer text messages and name labels will be tinted in the specified colors when the corresponding character ID is specified in a @print command or generic text line.

The following video demonstrates how to use display names and character colors.

Avatar Textures

You can assign avatar textures to characters using avatar parameter of @char command. Avatars will be shown by the compatible text printers when they print a text message that is associated with the character. Currently, only Wide and Chat text printers support the avatars feature.

To use any given avatar, you have to first add it to the avatar resources and give it a name. You can do this via Avatar Resources property in the characters configuration menu.

You can set a default avatar for a character by giving the avatar texture resource name that equals to CharacterID/Default; eg, to set a default avatar for character with ID Kohaku name the avatar resource Kohaku/Default. Default avatars will be used when avatar parameter is not set in the @char commands.

It's also possible to associate avatars with specific character appearances, so that when character changes appearance, the avatar will also change automatically. For this, name the avatar resources using the following format: CharacterID/CharacterAppearance, where CharacterAppearance is the name of the appearance for which to map the avatar resource.

Please note, that the avatars are not directly connected with character appearances and shouldn't be considered as a way to show character on the scene. Appearances are the actual representation of a character on the scene. Avatars is a standalone feature, that "injects" an image to a compatible text printer.

It's possible to show only the avatar of a character inside a text printer, but hide the character itself by setting visible parameter of the @char command to false, eg:

@char CharId visible:false

Speaker Highlight

When enabled in the character configuration, will tint the character based on whether the last printed message is associated with it.

Lip Sync

Generic and Live2D character implementations support so called "lip synchronization" feature, allowing to drive character's mouth animation while its the author of the printed message by sending the appropriate events.

Check the corresponding character implementation docs below for the details on how to setup the lip sync feature.

Sprite Characters

Sprite implementation of the character actors is the most common and simple one; it uses a set of sprite assets to represent appearances of the character. The source of the sprites could be images (textures) of any formats supported by Unity.

Sprite character appearance assets can be either managed by editor GUI or placed in a Resources/Characters/CharacterName folder, CharacterName being the name of the character, for an automatic exposure.

Diced Sprite Characters

Built with an open source SpriteDicing package (distributed with the main Naninovel package), DicedSpriteCharacter implementation allows to significantly reduce build size and texture memory by reusing texture areas of the character sprites.

Sprite Dicing

DicedSpriteAtlas assets containing character appearances are used as the resources for the diced sprite characters. Each appearance is mapped by name to the diced sprites contained in the atlas.

Note, that the implementation doesn't support cross-fading between appearances (they're changed instantly).

The following video guide covers creating and configuring diced sprite atlas, adding new diced character based on the created atlas and controlling the character from a naninovel script.

Generic Characters

Generic character is the most flexible character actor implementation. It's based on a prefab with a CharacterActorBehaviour component attached to the root object. Appearance changes and all the other character parameters are routed as Unity events allowing to implement the behavior of the underlying object in any way you wish.

To setup lip sync feature for generic characters, use On Is Speaking Changed boolean Unity event of the CharacterActorBehaviour component. When the character becomes or ceases to be the author of any printed message, this event will be invoked allowing you to trigger any custom logic, like starting or stopping mouth animation of the controlled character.

Check the following video tutorial for example on setting up a 3D rigged model as a generic character and routing appearance changes to the rig animations via Animator component.

Be aware, that Unity's Animator component could fail to register SetTrigger when the game object is enabled/disabled in the same frame; in case you use GameObject.SetActive to handle visibility changes (as it's shown in the above tutorial), consider enabling/disabling the child objects with renderers instead.

Live2D Characters

Live2D character implementation uses assets created with Live2D Cubism 2D modeling and animation software.

In order to be able to use this implementation you have to first install Live2D Cubism SDK for Unity. Consult official Live2D docs for the installation and usage instructions.

Then install NaninovelLive2D extension package.

Live2D model prefab used as the resource for the implementation should have a Live2DController component attached to the root object. Appearance changes are routed to the animator component as SetTrigger commands appearance being the trigger name. Eg, if you have a "Kaori" Live2D character prefab and want to invoke a trigger with name "Surprise", use the following command:

@char Kaori.Surprise

Note, that the above command will only attempt to invoke a SetTrigger with "Surprise" argument on the animator controller attached to the prefab; you have to compose underlying animator state machine yourself.

When Live2D's CubismLookController and CubismMouthController components are present and setup on the Live2D model prefab, Live2DController can optionally use them to control look direction and mouth animation (aka lip sync feature) of the character.

Consult Live2D documentation on eye tracking and lip sync for the setup details.

Be aware, that Live2DController expects a "Drawables" gameobject inside the Live2D model prefab (created automatically when importing Live2D models to Unity); the controller will scale this gameobject at runtime in correspondence with "scale" parameter of the @char commands. Hence, any local scale values set in the editor will be ignored. To set an initial scale for the Live2D prefabs, please use scale of the parent gameobject as shown in the video guide.

When Live2D extension is installed a "Live2D" item will appear in the Naninovel configuration menu providing following options:

Render layer specifies the layer to apply for the Live2D prefabs and culling mask to use for the cameras that will render the prefabs. Render camera field allows to use a custom setup for the render camera (the default render camera is stored inside the packages "Prefabs" folder). Camera offset allows to offset the render camera from the rendered prefab; you can use this parameters to uniformly position all the Live2D prefabs relative to the camera.

The following video guide covers exporting a Live2D character from Cubism Editor, configuring the prefab, creating a simple animator state machine and controlling the character from a naninovel script.