Skip to content

@Elringus Elringus released this Dec 25, 2019 · 568 commits to master since this release


Target Unity version: 2019.3 Previous versions are not supported; any issues with newer versions will be addressed in the next releases or patches.

Upgrade Guide

When upgrading a project with a previous Naninovel version, follow the steps below:

  1. Remove Naninovel folder from the project before importing the updated package.
  2. In case you have any of the extensions packages installed, update them using the following links:
  3. In case you're using managed text feature, remove all the existing documents (including localized versions) and re-generate them. Existing records will be lost, but you can copy-paste content of the old documents into the new ones.
  4. In case you have issues when generating localization documents for naninovel scripts with Try Update option enabled, you may have to delete the old generated documents.
  5. Reset all the actor (background, character, text printer, choice handler) implementations in the corresponding configuration menus (including default meta sections).
  6. Delete UI configuration asset stored at NaninovelData/Resources/Naninovel/Configuration/UIConfiguration.asset (custom UI config will be lost).
  7. If you have any custom UIs with a modified (disabled) Visible On Awake property, make sure it's still disabled (it could have been reset due to a name change).
  8. Script defines have been removed, so make sure to remove define lines and expressions from the naninovel scripts (eg, >defineKey defineValue); below you can find more information on the change and suggested workarounds.
  9. Predefined custom variables menu now expects script expressions instead of raw values; make sure the value (expression) fields contain valid script expressions.
  10. In case you're using time parameter of the @bgm and @sfx commands to control fade-in duration, use fade parameter instead.
  11. Custom variables (in the configuration menu) will reset after the upgrade, so make sure to copy the values to restore them later.
  12. In case you're using sprite dicing extension, install it via Unity's package manager; see diced sprite characters guide for more info on how to install the extension.

Remember to keep NaninovelData/Resources folder and NaninovelData/EditorResources.asset file when updating the engine to preserve project configuration and asset references.

In case you're using Atom IDE extension, don't forget to update the package to handle changes in the commands API.

Script Defines Removal

The defines were introduced with the first alpha release; at the time there was no script expressions and display names available. Currently, the aforementioned features take care of most of the use cases defines were initially designed for; at the same time, defines complicate script parsing process and impose substantial performance overhead at runtime (especially for mobile devices).

After a discussion and poll held in Naninovel's discord with the registered users, we decided to remove script defines feature to improve the performance and refine naninovel script syntax. Below you can find suggested ways to handle various use cases script defines were previously designed for.

Replacing Parameter Values

Use script expressions to inject pre-defined values (or parts of the values) to the command parameters.


>boldRed color=#ff0000,b,size=45
>right 85
@style {boldRed}
@char CharId pos:{right},50,0


@set boldRed="color=#ff0000,b,size=45"
@set right=85
@style {boldRed}
@char CharId pos:{right},50,0

Global Defines

Instead of declaring define expression in the global defines script, specify pre-defined custom variables in the configuration window.

Character ID Shortcuts

Instead of using defines to shortcut character IDs, change the IDs to the short variants you've used as define keys and use display names to assign full character names.


>k Kohaku
@char {k}.Happy
k: Hello World!

Change "Kohaku" to "k" in the character resources and set "Kohaku" as display name in the character configuration, then:

@char k.Happy
k: Hello World!

Replacing Multiple Parameters

Instead of replacing multiple parameters in char and back commands with a define expression, use actor poses feature.


>CenterSmall pos:50 scale:0.5
@char CharId {CenterSmall}


; Given `CenterSmall ` pose is defined for the char.
@char CharId.CenterSmall

Alternatively, use custom variables for each parameter:

@set center=50;half=0.5
@char CharId pos:{center} scale:{half}


  • It's now possible to specify author appearance in the generic text lines; eg Felix.Happy: Hello!.
  • It's now possible to update parameters of the spawned (FX) objects; when @spawn or @fx commands are used over an already spawned object, the spawn parameters will be updated.
  • It's now possible to override shader used to render character and background actors.
  • It's now possible to add new lines in visual editor with hotkey while editing a text field in a line.
  • It's now possible to insert a new generic text line with a hotkey while visual editor's "insert new line" window is in focus; effectively, you can now press insert new line hotkey (ctrl+space by default) twice to add a new generic text line without distracting from typing.
  • It's now possible to stop/start rendering (hide/show) the entire UI via @hideUI and @showUI commands by omitting UI name (nameless) parameter.
  • It's now possible to perform state rollback via hotkey when the UI is hidden.
  • It's now possible to start playing a naninovel script or execute commands in reaction to any Unity event with Play Script component.
  • It's now possible to cycle through text fields using tab key while editing command lines in visual script editor.
  • It's now possible to generate script localization documents over already generated ones using translated lines as the source for translation to another language.
  • It's now possible to provide custom serialization handlers for game saves, global state and settings; see state management guide for more info.
  • It's now possible to reference Unity event arguments in "Play Script" component.
  • It's now possible to use script expressions in the custom predefined variables menu to initialize custom variables.
  • It's now possible to remove records in resources and metadata list editors with delete keyboard key.
  • It's now possible to spawn multiple FX of the same type; see "Special Effects" guide for more information.
  • It's now possible to affect all the visible character and background actors with @char and @back commands respectively by specifying * for actor ID parameter.
  • Characters now support transition effects (same as backgrounds); the transition type can be specified via transition parameter of @char command.
  • Visual script editor will now automatically scroll to the played line if it's out of the view bounds.
  • All the sprite actors are now rendered with an additional depth pass making them exposed for various effects that use z-buffer; depth pass can be disabled per actor in the configuration menu.
  • Diced sprite characters now support appearance animations and all the other character features. (#87)
  • Added hot-reload feature allowing to apply changes to the naninovel scripts (made via both visual and external editors) at play mode without restarting the game.
  • Added Poses property to characters and backgrounds configuration menus, allowing to specify named states (poses) of the actors; pose name can be used as appearance in @char and @back commands to apply associated state.
  • Added depth of field (bokeh) special FX.
  • Added support for Unity's new input system.
  • Added @animate command allowing to perform an animation over multiple actors with support for key frames, looping, easings and shader transitions.
  • Added @startTrans and @finishTrans commands allowing to perform full scene transitions.
  • Added @clearChoice command allowing to reset (clear) a choice handler, removing all the existing choice options.
  • Added @purgeRollback command allowing to prevent player from rolling back to the previous state snapshots.
  • Added search to custom variable debug window. (#100)
  • Added layered character and background implementations. (#92)
  • Added an option (enabled by default) to automatically place highlighted characters on top (closer to the camera over z-axis).
  • Added an option to disable showing actors by default when using modification commands (@char and @back); can be used when constantly changing character avatars, while the character itself should remain hidden.
  • Added an option to link a text printer to a character, making the linked printer to be used automatically when the character is an author of a printed message.
  • Added an option to control z-offset amount for the background and character sprites.
  • Added swipes input support for touch screens; continue and rollback inputs can now be activated with left and right swipes respectively. (#93)
  • Added "Apply" and "Revert" buttons to the visual script editor.
  • Added an option to navigate to novel script asset referenced in "goto" and "gosub" lines and parameters via visual editor context menu.
  • Added reset parameter to @goto, @gosub and @return commands allowing to control which engine services to reset.
  • Added an option to show script player debug window on engine initialization; can be enabled in script player configuration window.
  • Added preview printer when changing message speed in the game settings menu.
  • Added @skip command, allowing to enable or disable script player skip mode.
  • Added @slide command, allowing to slide actors over X-axis, while (optionally) revealing or hiding them and changing appearance.
  • Added Allowed Samplers property to the CustomUI component allowing to specify a set of input samplers that are allowed in case the UI is set to block input.
  • Added indicators for currently selected target locale to the localization utility window; a warning will now be shown when the selected path is not valid.
  • Added Highlight Character Count property to the characters config, allowing to limit highlight feature effect based on number of visible characters.
  • Added ManagedTextProvider component allowing to translate arbitrary game objects's text via managed text documents without any scripting.
  • Added font type and size settings to the game menu.
  • Added group parameter to @bgm, @sfx and @voice commands allowing to play the audio via a custom audio mixer group.
  • Added "auto delay" setting to the game menu, allowing to control the time to wait (scaled per printed characters) while in auto play mode; added an option to set the available interval to the text printers configuration.
  • Added (limited) support for scriptable render pipelines (both URP and HDRP); see render pipelines guide for more information. (#98)
  • Total word count contained in the generated localization documents (excluding the hash lines) will now be shown in the localization menu. (#94)
  • "OnSpeak" character events are now compatible with voice over; when a voice clip is played at the start of the event, finish event will be invoked when the voice clip stops playing. (#101)
  • Voice overlap can now be limited per character. (#91)
  • When adding new line with visual script editor using hot key and a line is focused, new line will be added after the focused one.
  • Custom commands with duplicated IDs or aliases will no longer throw exception during the engine initialization.
  • Expression evaluation errors will now be logged with script name and line number info.
  • Visual script editor fields now support undo/redo operations.
  • Each engine service now has a corresponding C# interface; the sources has been refactored to only reference services via interfaces, which allows to provide a custom implementation for any engine service. See engine services guide for more information.
  • Managed text utility will now automatically set default path to the output folder and create it when necessary.
  • Leaving an unassigned element in the Custom UI list will no longer cause a nullref exception.
  • Assigned object resources in the editor will now only load on hover for better performance. (#100)
  • Visual script editor now indicates waiting for input mode by highlighting currently played lines.
  • "Rollback" visual editor context menu item will now be disabled when it's not possible to rollback to the target line.
  • Update the built-in UIs layout to support 9:16 (aka mobile portrait mode) aspect ratio.


  • Script defines feature has been removed.
  • Managed text documents are now serialized as .txt files (instead of .nani) to prevent confusion with naninovel scripts; it's required to manually re-generate all the documents and their localized counterparts.
  • Managed text for builtin UI is now stored in a single "DefaultUI" document.
  • Command parameters are now expected to be fields of a supported type; related attributes has been changed. See custom commands guide for more info.
  • Both background and character actors are now automatically distributed by z-axis to prevent z-fighting issues; the offset is controlled in the config menus and can be disabled by setting the value to zero.
  • Backward slashes (\) in the resource paths will now be automatically replaced with forward slashes (/) for consistent behavior across target platforms.
  • Play Script On Button Click component has been renamed to Play Script and will no longer execute the script on button click; use Unity events to invoke Play() method of the component instead.
  • @gosub and @return commands will no longer cause the engine state to reset by default; the reset can still be forced using reset parameter.
  • Visible On Awake of Custom UI component is now disabled by default.
  • Total commands counter will no longer be updated automatically by default; enable Count Total Commands in the scripts configuration in case you're using CalculateProgress function to track current game progress.
  • All the actor modifications (@char and @back commands) except visibility will now be applied instantly (without animation) when the actor is hidden.
  • Removed default values from all the @camera command parameters, allowing to selectively modify them (eg, @camera offset:5 will modify only the offset; zoom, rotation and others won't reset to default values).
  • Engine version and build number will no longer be displayed in the built-in title menu UI (it's still available in the Naninovel -> About editor menu).
  • "next" and "previous" buttons removed from debug GUI; use "rewind" console command or in-game controls to rollback and fast-forward (skip) the playback instead.
  • Predefined custom variables menu now expects script expressions instead of raw values.
  • @bgm and @sfx commands no longer use time parameter to control fade-in duration; use fade parameter instead.
  • State rollback (driven by player input) now only happens between points where player had a meaningful interaction with the game to progress forward (eg, clicked to continue reading, picked a choice, etc).
  • Merged UnityCommon and UnityConsole under Naninovel namespace.
  • Removed "SpriteDicing" third-party from the distributed package; it can now be installed via Unity's package manager when required.
  • All the command parameters, that expected an all value (as an indicator to perform something over all the available targets), now expect * instead.


  • Fixed compatibility issues with Unity 2019.3.
  • Fixed z-fighting issues of overlapping diced sprite characters.
  • Fixed visual editor sometimes not being updated when modifying naninovel script via external editor.
  • Fixed save script visual editor hotkey also causing scene save.
  • Fixed some of the naninovel script parsing errors were not providing error position.
  • Fixed TMProBubble printer option not appearing in the create asset menu.
  • Fixed visual script editor sometime loses focus on the added lines.
  • Fixed choice button template having zero width.
  • Fixed RenderUI property of camera manager not being serialized on state save/loading.
  • Fixed CustomUI assigned as a custom engine initialization UI causing exceptions.
  • Fixed naninovel scripts with empty lines at the start reporting wrong playback spots.
  • Fixed character look direction not being applied when auto arrange is active.
  • Fixed incorrect command inline numbers reported when running under a non-source locale.
  • Fixed issues with playback positions when switching languages while a script is playing.
  • Fixed character highlight feature not applying appropriate tint when adding a non-sprite character on scene.
  • Fixed @resetState command not preserving local variables.
  • Fixed custom actor implementations not being instantiated correctly.
  • Fixed custom UI breaks UI toggling feature. (#105)
  • Fixed assigned custom UI list elements not removed the first time remove button is clicked.
  • Fixed Script managed text document deleted when generating managed text documents with "Delete Unused" option enabled.
  • Fixed issues with resources provider when using addressables and running under WebGL.
  • Fixed default character avatar paths not mapped on initialization.
  • Fixed orphaned game objects remaining on scene when exiting editor playmode during engine initialization.
  • Fixed visual editor sometimes loosing edited script asset when saving changes.
  • Fixed script (forward) rewinding causing loss of rollback data and executing target line twice.
  • Fixed nullref exceptions when using rollback over chat printer with empty messages.
  • Fixed rollback state invalidation when using debug window buttons to rewind played script.
  • Fixed auto play mode adding redundant delays.
  • Fixed nullref exception when exiting playmode while a "shake" FX is active.
  • Fixed variable input UI fails to serialize state.
  • Fixed actor modification effects via naninovel scripts sometimes differ in editor and player builds.
  • Fixed temp folders not deleted when player build fails.
Assets 2