Naninovel

Appearance

1.21 Release Notes ​

Release date: Q4 2025 (ETA)

NOTE

This is a preview work-in-progress release, which may have breaking changes introduced at any time. Choose it if you're in the early development stages or need a specific feature unavailable in the stable release. Note that preview releases are not published on Unity's Asset Store and have to be installed from GitHub.

Compatibility ​

Supported Unity versions range: 6000.0.50 - 6000.2

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 the v1.19 release upgrade guide, then continue with the following instructions:

  1. Back up the project or use a VCS ↗ to be able to roll back in case something goes wrong.
  2. In case using VS Code extension, update both the extension and VS Code itself to the latest versions.
  3. Install the new release. [doc]
  4. Run the upgrade script via Naninovel/Upgrade/v1.20 to v1.21 Unity editor menu.
  5. If you've customized the built-in save-load UI, revisit the prefab, as it now has an additional "AUTO" tab.
  6. Choice buttons are now always loaded via the Choice Button Loader specified in the choice handler configuration menu, and should be stored in the Resources/Naninovel/ChoiceButtons folder. Alternatively, you can configure a different resource provider in the loader settings.
  7. In case using custom commands, update the Execute signature to accept ExecutionContext instead of AsyncToken.
  8. In case using script playback APIs of IScriptPlayer service, use IScriptPlayer.MainTrack to get IScriptTrack, which now hosts most of the playback-related APIs. In custom commands, use ExecutionContext.Track to get the track associated with the command execution.
  9. In case using @animate or @delay commands, replace them with @async.

Added ​

  • Added full support for concurrent scenario playback through the updated IScriptPlayer APIs and the new @async command. [doc]
  • Transient scripts, such as those played via the PlayScript component, are now serialized with the game state, support rollback, and no longer have any limitations compared to regular script assets.
  • Added relative and wildcard endpoint syntaxes allowing to simplify navigation paths. [doc]
  • Added lazy resource policy mode. [doc]
  • Added @unless command and unless parameter for all commands, which work as the logical inverse to @if command and if parameter respectively.
  • Added default assignment operator ?= allowing to declare and assign variable only in case it's not already assigned. [doc]
  • Added [-] alias for the wait input command ([wait i])) and[>] alias for the parameterize generic command with skip parameter ([< skip!]).
  • Eased control flow exit requirements: @stop commands are no longer required to gracefully terminate control flow; also, it is now allowed for nested blocks to not have exit lines.
  • Added a dedicated "Keyboard" input mode with the associated control legend for better accessibility.
  • Added select tag. [doc]
  • Added wait input tag. [doc]
  • Printer character commands (Char Commands property of the Revealable Text Printer Panel component found on the printer prefabs) are now awaited allowing to use @wait commands to control the reveal process.
  • Added "AUTO" save-load tab; @save now uses the auto tab instead of the quick-save tab.
  • Added Auto Save On Quit option to state configuration (enabled by default); when enabled, then game will auto-save to the newly added "AUTO" tab before exiting to title or when the application is quit.
  • Text of Toast UI (@toast command) is now updated on locale change.
  • Added Expose Source Locale option to the localization configuration (enabled by default). When disabled, the source locale won't be available for the end-users (players). [doc]
  • Added loop parameter to @shake command allowing to enable/disable continuous shake effect instead of using count:0 and count:-1.
  • Added at parameter to @save command allowing to redirect the player position after the saved game is loaded.
  • Added script reference helper, which simplifies referencing script assets in a stable manner. [doc]
  • Added LastGameState property to state manager providing access to the last de-/serialized game state.
  • Added filtering for locale-specific fonts so that they're not included in the font selection in game settings.
  • Improved nesting diagnostic in VS Code – it know indicates the extra indentation in the affected line and clearly states the reason for the warning.
  • Added an option to refresh script resource paths. [demo] ↗
  • Improved error when missing a localization document – it now points to the specific missing resource and locale.
  • Added VirtualResourceProvider option to the resource loaders configuration allowing to add resources at runtime.
  • Added [Command.Group] attribute allowing to assign a category to script command; used by standalone editor to group the commands and associate them with icons.
  • Improved hot reload stability and fixed several edge cases which caused inconsistent behavior.
  • Hot reload is now available at runtime via reload console command and IHotReload engine service.
  • Made most built-in UIs pixel-perfect to prevent pixel alignment issues when running outside the native resolution.
  • @input command will now automatically pull predefined value in case the assigned variable already has a value.
  • @choice and @input commands no longer require adding @stop to halt script playback until the user interaction is committed. In case a playback halt is not required, use the added skip parameter.
  • Added condition context to lock parameter of @choice allowing to assign expression without wrapping the value in curly braces.
  • It's now possible to use boolean flags with parameters of the expression context.
  • Spreadsheet tool is no longer limited by 32KB CSV line size when importing the localization.
  • Added ExpressionEvaluator.Context property allowing to access the context of the evaluated expressions in the associated C# methods.
  • Added IScriptManager.Add/RemoveTransient APIs to register transient (generated at runtime) scripts, allowing them to function as actual script assets.
  • Added nowait! flag to the parametrize generic ([<]) command allowing to disable waiting for the text reveal to finish before proceeding with the playback.
  • Added Author Filter to the voice-over utility allowing to filter the generated voice lines by a specific author or exclude un-authored lines.
  • Added an option to move the "Naninovel" editor menu under the "Tools" submenu.
  • Added toggles in the editor menu for enabling/disabling Live2D and Spine integrations.
  • Added an option to the voice map utility to use addressable when it's installed.
  • Added a "Show Played Line" command to the VS Code extension allowing to navigate to the currently played scenario line.
  • Added default key bindings to the VS Code commands.
  • Added a VS Code diagnostic for dynamic endpoints.
  • Added Skip Print Delay option to printer configuration allowing to slow down the print command execution while in skip mode.
  • Added expression, command, and formatting tags highlighting, diagnostic, and auto-completion to the VS Code extension.
  • Optimized IAudioManager interface to not require anything from the Unity's default audio backend for easier overrides with custom audio solutions.
  • Improved interoperability with Unity's new input system; optimized IInputManager and IInputSampler interfaces for easier overrides with custom input solutions.

Changed ​

  • The minimum-supported Unity version changed to 6.0.50.
  • Unity's legacy input manager is no longer supported.
  • Changed label delimiter from . to # to support the new relative endpoint syntax; use Naninovel/Upgrade/v1.20 to v1.21 tool in the Unity editor menu to automatically upgrade the scripts.
  • IScriptPlayer API has been changed to support async script execution; most playback-related APIs have been moved to IScriptTrack, which can be accessed from the script player.
  • Command.Execute method signature changed from (AsyncToken) to (ExecutionContext).
  • Layered actors no longer attempt to align an underlying game object with the render texture, as that was causing rendering issues. Perfect alignment is not possible anyway due to render effects, such as look direction flipping. When the alignment is required, use generic or custom implementations.
  • Command attribute [Command.CommandAlias] renamed to [Command.Alias], parameter attribute [Command.PrameterAlias] removed—use [Command.Alias] instead.
  • Removed Google Drive resource provider; use Local Provider pointing to a directory synced with Google Drive (or other similar services) instead.
  • @input and @choice commands will now auto-halt the playback, so you no longer have to add @stop after them. Upgrade script automatically changes @choice to @addChoice which works same as the @choice before.
  • Changed the type of lock parameter of @choice to string with condition context to allow assigning expression without wrapping the value in curly braces.
  • @save command now writes to the newly added "AUTO" tab instead of the quick-save tab.
  • Choice buttons are now always load via the Choice Button Loader specified in the choice handler configuration menu (previously they'd fall back to Resources.Load method when loading failed).
  • Removed @delay command; use @async followed by @wait 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 ICustomVariableManager.OnVariableUpdated event not invoked on game load and rollback.
  • Fixed parameter value without whitespace has wrapping quotes removed when formatting with VS Code or with stable identifier in Unity.
  • Fixed layered actors clipping when scaled, and the local position is not balanced.
  • Fixed warnings on hot reload after editing a line before the currently played one.
  • Fixed video resources failing to load in WebGL build when the addressable is not installed.
  • Fixed video resources duplicated in the WebGL build when the addressable is installed.
  • Fixed @await command waiting for all the currently played commands instead of only the nested ones.
  • Fixed @trans command completing all the currently played commands instead of only the nested ones.
  • Fixed custom @choice buttons failing to load when the path is dynamic (specified with an expression).
  • Fixed a false-positive VS Code warning when nested lines are separated by an empty line.