1.20 Release Notes

Release date: Q4 2024

NOTE

This is the current stable release, which receives only bug fixes. Keep using it if you're in the later stages of development or have already published your project. Note that Unity Asset Store distribution usually lags by 2-3 months, so we recommend installing Naninovel from GitHub.

Highlights

Compatibility

Supported Unity versions range: 2022.3.45 - 6000.0

Only LTS releases in the range are supported. Any issues with the future Unity releases will be addressed in the next Naninovel releases. Compatible Unity versions for past releases are specified in the release notes ↗.

Upgrade Guide

When upgrading a project with Naninovel version 1.18 or older first follow v1.19 release upgrade guide, then continue with the following instructions:

1. Backup the project or use a VCS ↗ to be able to rollback in case something goes wrong.
2. In case using VS Code extension, update both the extension and VS Code itself to the latest versions, then run Naninovel: Purge Cached Metadata command via View -> Command Palette and restart VS Code.
3. Remove Naninovel and NaninovelData/Saves folders from the project and add the new release via the following Git URI: https://github.com/naninovel/upm.git#1.20. ^[doc]
4. Reset Script Parser in scripts configuration (when not using custom parsers, just re-select the only available option), restart Unity editor and re-import scenario scripts.
5. Revise how script assets are stored in Unity project: it's now required for all scripts to be stored under a single root directory (Assets/Scenario by default, can be changed in scripts configuration via Script Root option); when a script is stored outside the specified root, a warning will be logged.
6. In case organizing script assets under sub-directories of the script root, make sure to reference them by their local paths; for example, to navigate to Assets/Scenario/Prologue/Day1.nani script, use the following command @goto Prologue/Day1.
7. Due to scripts now being identified by their local paths instead of just name, localization and auto-voicing have to be re-generated; to preserve existing translations, make sure localization documents mirror scripts file structure. For example, Japanese localization document for Assets/Scenario/Prologue/Day1.nani script has to be at Assets/Resources/Naninovel/Localization/ja/Text/Scripts/Prologue/Day1.txt. Use localization sample project ↗ as a reference setup.
8. Some managed text documents may need to be regenerated, as some records associated with static fields used to have incorrect keys; for example, GameSettingsFontDropdown.DefaultFontName record inside DefaultUI document had Naninovel.UI.GameSettingsFontDropdown.DefaultFontName key.
9. Add SkipMovie input binding to the input configuration menu or input actions asset (when using new input system) with the desired bindings to skip movie playback (Esc by default).
10. In case using @if conditional blocks, either make sure the commands inside blocks are not indented or switch to the new syntax with indentation and remove @endif command. ^[doc]
11. In case using @elseif ... commands, replace them with @else if:....
12. In case using do parameter of @choice command, replace it with nested callback. ^[doc]
13. In case using do parameter of @wait command, replace it with @delay command.
14. In case using @startTrans and @stopTrans commands, replace them with @trans.
15. In case using [skipInput] command, replace the occurrences with [< skip!] generic parameter. ^[doc]
16. In case using ExpressionFunctions attribute to expose custom expression functions, remove the attribute from the class and instead apply ExpressionFunction attribute to the methods of the class. ^[doc]
17. In case using remove parameter of @hide, @hideAll or @hideChars commands, remove the parameter and instead use @remove command after hiding the actors.
18. In case using Live2D or Spine extensions, remove the extension directories and follow setup instructions on the dedicated character guides (both extensions have been merged with the main package). You may also have to re-assign character implementation types in the configuration after finishing the setup. ^[doc]
19. In case using async methods of Naninovel C# API, remove the "Async" suffix; eg, Command.ExecuteAsync is now Command.Execute.
20. In case using custom actor shaders, assign materials instead of the shaders. ^[doc]
21. Due to Authored Template and Auto Line Breaks moved to text printer UI setting, revise the formatting settings. For example, "Fullscreen" printer has %AUTHOR%: “%TEXT%” template for authored messages (+) specified by default. ^[doc]
22. In case using @style commands, replace them with @format commands.
23. In case using [br] inlined commands, replace with <br> tags.

WARNING

In-game saves (slots in save/load menu, values in settings menu and global game state) created with previous versions may cause undefined behavior when loaded with the updated version; when patching a shipped project with a new Naninovel version, make sure existing saves work as expected.

Added

• Added compiler localization feature allowing to re-map all the NaniScript compiler specs: control characters, command and parameter names, constants and basically anything you have to type when authoring scenario scripts. ^[doc]
• Added nesting concept to NaniScript allowing to specify a block of commands nested under (associated with) other command. Various existing commands are now using this concept for more readable and concise syntax; added several new commands, which were previously impossible to represent in NaniScript without the new syntax: ^[doc]
  • Upgraded @if and @else commands to support nesting; ^[doc]
  • Upgraded @choice command to support nesting; ^[doc]
  • Merged @startTrans and @finishTrans commands into @trans; additionally, it's no longer required to specify time:0 for each underlying command — they'll complete instantly by default;
  • Added @while command for looping nested commands as long as condition is truthy;
  • Added @delay command allowing to delay execution of nested commands;
  • Added @random command allowing to randomly execute one of its children;
  • Added @group command allowing to join multiple lines into single execution block;
  • Added @await command allowing to await nested async commands before continuing script playback. Intended to be used with Wait By Default disabled in script player configuration, which is now the default in new projects. ^[doc]
• Added boolean flags as shortcuts for boolean parameter values. ^[doc]
• Added a way to apply print parameters for parts or whole generic text lines. ^[doc]
• Added a way to delimit slack white space in generic lines with [] (empty inlined command). ^[doc]
• Added Conservative and Optimistic resource policy modes instead of Static and Dynamic. ^[doc]
• Script file names no longer have to be unique and can be referenced by their local paths; for example you can have Scripts/Prologue/Day1.nani and Scripts/MainRoute/Day1.nani and reference them as @goto Prologue/Day1 and @goto MainRoute/Day1.
• It's no longer required to specify assemblies for custom types via Type Assemblies property in the engine configuration; the option is removed.
• Naninovel can now be installed as a UPM package.
• Live2D and Spine extension have been merged into the main package; it's no longer required to install dedicated packages to activate the integration.
• Improved engine initialization time by caching types on build instead of resolving them via reflection at runtime.
• Script and managed text resources are now loaded on-demand, which significantly reduces RAM usage and improves engine initialize time in large projects.
• Added Label By Scripts option to the resource provider configuration; when enabled (default) will label all the Naninovel addressable assets by the scripts in which they’re used; when Bundle Mode of the addressable group is set to Pack Together By Label, asset bundles will be optimized for the project scenario structure improving load times and RAM usage. ^[doc]
• Player read progress feature no longer incurs runtime overhead, as the required data is cached at build time; Count Total Commands option is removed from the scripts configuration, as it's now always available/enabled by default.
• Added Remove Actors option to resource provider configuration; when enabled (default) unused actors will be automatically removed and associated game objects disposed when unloading script resources, w/o the need to use @remove commands. ^[doc]
• Added Async Instantiation to the engine configuration; when enabled (default) will move the object instantiation off the main thread for improved performance and smooth asset loading.
• Generic, Live2D and Spine actors now support multiple appearances applied at once to make setting up complex animation states easier. ^[doc]
• Added Join Lines to localization utility. When enabled, generic lines in localization documents will be kept in single line for convenience. ^[doc]
• Annotations inside localization docs now also include gist of the translated content to give translators more context. ^[doc]
• Added lock parameter to @choice command allowing to lock/disable a choice. ^[doc]
• Added Auto Detect Locale to localization configuration. When enabled (default) will attempt to auto-detect locale using system language when the game is started first time. ^[doc]
• Added continue input prompt to pagination reveal effect before changing page.
• Layered actor prefab instances are now nested under the associated actor game object; this adds support for behaviour which depends on object transform, such as lighting, interactive spots, etc.
• Added Camera Mask option to layered actor behaviour component allowing to specify additional camera layers to preserve when rendering the actor; use to support render features, which require dedicated camera layers, such as Unity's 2D Light.
• Added Has Name to character configuration; when disabled, neither display name, nor actor ID will be displayed in printer UI. Useful for narrator-type characters with linked printers. ^[doc]
• Added an option to supply font with community localization. ^[doc]
• Added an option to assign custom materials for rendering the actors, allowing to use Shader Graph to author custom actor shaders.
• Added Separator Literal to built-in Tips UI allowing to change character used to separate title, category and tip text in managed text records.
• Added Selected Prefix to built-in Tips UI allowing to change unlockable ID prefix used to indicate that item was selected (seen) at least once.
• Added TipsPanel.HasUnselectedItem() method allowing to check if the tips panel contains any unselected items.
• Added Build Resources editor menu allowing to build Naninovel-related project resources (including addressables, when enabled) without building the player.
• Added lazy flag to @char, @back, @camera, @slide and some other commands allowing to not complete the animation when player skips it; useful for blending long-running async animations, such camera panning.
• Added a way to create identified text references by prepending & to the identifier. ^[doc]
• Added an option to specify alias and documentation for custom expression functions.
• Numeric expression function parameters are no longer limited to double.
• Added Play SFX While Skipping option to audio settings; when disabled, @sfx commands without loop! will not play while skipping.
• Added as parameter to @print command allowing to set custom name label; when combined with author parameter now handling multiple authors (delimited with ,) and all authors specified with * — useful for representing multiple characters authoring single text line. ^[doc]
• Added a way to include script expressions to localization documents and force re-evaluation when locale is changed. ^[doc]
• Added graceful handler for missing fonts: warning is logged and default font is used instead of throwing an exception.
• Added block parameter to @movie command allowing to block player interaction while the movie is playing to prevent skipping.
• Added @format command instead of @style for more powerful text formatting capabilities.
• Added folder selector to GeneratedDataPath option in the engine configuration.
• Added SkipMovie input binding dedicated to skipping movies (previously shared Cancel binding).
• Added @remove command for disposing actors.
• Added Support Custom Opacity option to text reveal fader effect; when enabled the effect will respect <alpha> tags and limit max opacity when fully revealed at the cost of some performance overhead.
• Added type parameter to @input command allowing to enforce type of the input variable value.
• Added Include Author To Backlog option to text printers configuration allowing to not include author of the printed messages to the backlog; disabled by default for "Fullscreen" printer.
• Added Scene Path Root option to scene background actor settings allowing to change the root directory of the scene assets associated with the actor appearances. ^[demo] ↗
• Engine now has its own CSV parser and no longer depends on the third-party library.
• IDE (VS Code) extension improvements:
  • New file-based bridging service makes the connection between Unity, VS Code and Web Editor more reliable and doesn't require any setup or tweaking, such as specifying preferred socket ports. ^[guide]
  • Added visual indicator for the bridging connection status. ^[demo] ↗
  • Added rename refactor option for labels, script files and folders. ^[demo] ↗
  • The extension is now capable of formatting NaniScript documents. ^[demo] ↗
  • Label auto-completion and diagnostics no longer requires syncing metadata with editor;
  • Added Debounce Delay setting to optimize diagnostic performance. The extension will no longer diagnose on each document change and instead accumulate changes and process them in batch with the specified debounce interval (500ms by default).
  • Already specified parameters are no longer suggested in the auto-completion list;
  • Parameters, that has no effect or not supported by the command, such as if parameter in @if command and wait parameters in commands that are not async, are no longer suggested in the auto-completion list;
  • Parameter values with expression context are now highlighted as expressions, even when the value is not wrapped in {};
  • Localizable parameter values, such as printed text and choice labels are now highlighted independently to better distinguish "natural" text presented to player from other values.
  • Indented lines are now foldable. Useful for folding nested blocks, as well as adding custom folding regions by indenting lines;
  • Added an option to specify custom folding blocks; ^[doc]
  • Added an option to specify context for expression function parameters. ^[doc]
  • Added support for minimap section headers. ^[doc] ↗
  • Added code highlighting to the example snippets inside tooltips.
  • Added common configuration defaults to the extension contributions: token colors, hiding .meta files, word wrapping, etc.
  • Added weak (informational) warnings in VS Code when a dynamic parameter value is preventing resource preloading.
  • Appearances metadata (used for auto-completion in VS Code) for generic, live2d and spine actors is now generated based on trigger parameters in Animator component of the implementation prefab.

Changed

• Minimum supported Unity version changed to 2022.3.
• State reset now additionally invokes all the tasks added with IStateManager.AddOnGameDeserializeTask with an empty game state. This affects built-in variable trigger component, as well as backlog, variable input, chat printer and choice handler UIs, resetting their local state when exiting to title and starting new game.
• Target script of @gosub command is now always preloaded. ^[doc]
• Removed @elseif command; use @else if:... instead.
• Removed do parameter of @choice command; use nested callback instead. ^[doc]
• Removed do parameter of @wait command; use @delay command instead.
• Wait By Default in script player configuration is now disabled by default in new projects. ^[doc]
• Removed "Lazy" resource policy; use the new "Conservative" or "Optimistic" policies instead. ^[doc]
• Removed [skipInput] command; use [< skip!] generic parameter instead. ^[doc]
• Removed ExpressionFunctions class attribute; use ExpressionFunction method attribute instead. ^[doc]
• Movies are now skipped with dedicated SkipMovie input binding (previously shared Cancel binding).
• Removed remove parameter from @hide, @hideAll and @hideChars commands due to issues when the commands are not awaited; use @remove command after hiding the actors instead.
• Normalized power of snow and rain effects to 0.0-1.0 range; default values are now 0.5 for both.
• Removed @startTrans and @stopTrans commands; use @trans instead.
• Scenario scripts are now identified by their local resource paths, instead of just asset names; associated APIs have been changed accordingly.
• Removed legacy (playback spot) auto-voicing mode.
• Dropped "Async" suffix in all the async method names.
• Changed Custom Texture Shader and Custom Sprite Shader properties in the actor metadata to accept materials instead of shaders for more flexibility and compatibility with shader graph.
• Moved Authored Template and Auto Line Breaks from text printer actor metadata to the printer UI.
• Removed @style command; use @format instead.
• Removed @br command; use <br> tag instead.

Fixed

Most fixes associated with bugs found during the pre-release stage are backported to the previous stable release and are not listed here; find them at the "Patches" section of the previous release changelog.

• Fixed chat printer duplicating messages on locale change.
• Fixed chat printer not updating printed text on locale change until restart.
• Fixed some managed text records associated with static fields having full type name as keys instead of short type name.
• Fixed leading and trailing white space lost when importing localization CSV sheets that were edited with Microsoft Excel.
• Fixed visual editor adding extra space after command identifier when nameless parameter is not specified.
• Fixed VS Code maximizing and stealing focus when highlighting played lines.
• Fixed VS Code missing metadata associated with class-level attributes.
• Fixed VS Code mixing appearances of actors with same ID, but of different types.
• Fixed VS Code inserting script name when typing . to skip script in @goto and @gosub commands.
• Fixed VS Code extension failing to properly process file names with non-ASCII characters.

Patches

• 2024-11-18 Fixed expression parsing of double numbers affected by the culture.
• 2024-11-18 Fixed VS Code false-positive diagnostic of dynamic expression assignment.
• 2024-11-19 Fixed entry and title script missing in the generated metadata.
• 2024-11-19 Fixed language setting not localized on engine initialization.
• 2024-11-20 Fixed generated data folder created under the default location on library rebuild even when a custom location is specified.