1.22 Release Notes

Release date: Q4 2026

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: 6.7 LTS release (with the latest patches).

Non-LTS (tech, beta and alpha) releases are not supported. Any issues with future Unity releases will be addressed in the next Naninovel versions. Compatible Unity releases for past Naninovel versions are listed in the release notes ↗.

Upgrade Guide

When upgrading a project with Naninovel version 1.20 or older, first follow the v1.21 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. If using the 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 the Naninovel -> Upgrade -> v1.21 to v1.22 Unity Editor menu.
5. If using the following attributes in custom C# extensions, rename them:
   • [ExpressionFunction] -> [ExpressionQuery]
   • [ConstantContext] -> [EnumContext]
   • [Alias(NamelessParameterAlias)] -> [PrimaryParameter]
6. The BGM and SFX resources are now separated, and the Audio resource prefix is no longer used. The upgrade script automatically assigns existing Audio resources as SFX. You will need to reassign the music clip assets as BGM. You can do that in batch by selecting multiple clip assets and choosing BGM in the Inspector header. ^[demo] ↗
7. If initializing custom meta (previously "global") variables with the @set command, add the meta! flag (the g_ prefix no longer has any significance and can be removed).
8. If using decimal or integer parameters in custom commands, change the type to NumberParameter.
9. If using variable APIs in C#, update the names: what was "CustomVariable" before is now just "Variable"; for example, ICustomVariableManager is now IVariableManager.
10. If using custom choice handlers, assign the Content property on the root prefab and revise the layout: the Content object is now the target of @choiceHandler transformations; any prebaked transformations should be applied to the descendants.

WARNING

Compatibility of save data between Naninovel releases is not guaranteed. When patching a shipped project with a new Naninovel version, make sure that existing saves work as expected.

Added

• Added a scene recording feature that allows capturing the state of scene objects into scenario scripts. ^[doc]
• Added support for inline comments in scenario scripts. ^[doc]
• Added support for whitespace in command parameter values, eg @set a=1, b=2.
• Added line and command decorations to the VS Code extension. ^[doc]
• Added support for nesting with tabs. ^[doc]
• Added expression operator aliases. ^[doc]
• Added @or command, which works as a shortcut to @else if:....
• Added the universal actor implementation, which uses native URP rendering and supports most built-in renderers out of the box. ^[doc]
• Added Volumes to the camera configuration and fx parameter to the @camera command for applying post-processing effects in URP. ^[doc]
• Added options to control URP camera stacking to the camera configuration.
• Added ruby support to the default choice buttons.
• Added Clear Save Data utility to the Naninovel editor menu for quickly purging saved games and global state, such as unlocked tips.
• Added support for partial localization documents; ie Naninovel no longer throws when a scenario or managed text localization document is missing (a warning is still logged).
• Added support for spaces in labels, eg # My Label and @goto # My Label.
• Added support for case-insensitivity across all the user-facing identifiers: actor IDs, commands and queries, variable names, resource paths, script paths and labels, etc.
• Added an option to control the indent type (tab or four spaces) to the VS Code extension.
• Added a played line indicator to the VS Code extension instead of selecting the played line text.
• Actor order is now always stable, making features like auto arrange produce consistent results between runs.
• Added fuzzy search and advanced grouping to the dropdowns throughout the editor menus. ^[demo] ↗
• Added Instant Reveal On Continue option to the revealable text printers (enabled by default). When disabled, the Continue input won't instantly complete the gradual text reveal effect. ^[demo] ↗
• Added script text constants to the expression auto-completion list in the VS Code extension.
• Added to parameter to the @set command for specifying a shared value to be assigned to the variables.
• Added meta! and const! flags to the @set command for designating the variable kind without using special name prefixes.
• Added scenario variable scopes and local scope. ^[doc]
• Added rename refactoring, auto-completion filtering, go to definition and find declarations features for scenario variables in the VS Code extension.
• Added input rebinding APIs to the input manager and a dedicated input settings tab for rebinding the input.
• Added auto trimming for layer composition expressions, which prevents accidental whitespace or new lines from breaking them.
• Added error reporting when an exception occurs while waiting for a queued add actor task.
• Added public APIs to BridgingService for communicating with the attached bridging servers, such as the VS Code extension and Story Editor.
• Added binary load progress to the Story Editor appearing when loading takes more than 3 seconds.
• Added an auto reload feature to the Story Editor, which automatically reloads the embedded editor to install the update after it's downloaded.
• Updated the Arabic support script to the latest version, which now correctly handles TMPro tags and various edge cases.
• Added pos and wpos parameters to the audio commands for controlling the audio source position in scene and world space, aka "3D audio". ^[doc]
• Added Aspect Ratios option to the camera configuration for enforcing specific aspect ratios on the managed cameras. ^[doc]
• Added a rename field to the resource header editor for renaming compatible resources without using dedicated editor menus. ^[demo] ↗
• Added waitFade parameter to the @bgm and @sfx commands that allows waiting for the fade-in/out, while the wait parameter now allows waiting until the played audio ends.
• Added pitch parameter to the @bgm, @sfx and @voice commands that allows changing the perceived frequency (speed) of the played audio.
• Added easing parameter to the @bgm, @sfx and @voice commands that allows animating the audio properties with a tween.
• Added @linkPrinter and @unlinkPrinter commands for overriding linked printers at runtime.
• Added nesting capability to the @printer command, which will auto-link the printer while the nested context is executing and unlink on exit.
• Added [PrimaryParameter] attribute that can be used as a shortcut for [Alias(PrimaryParameterAlias)].
• Added auto trimming for the values submitted by VariableInputUI.
• Added Clear Color option to the camera configuration for changing the color used to clear the screen when rendering with the default camera without setting up a custom camera prefab.
• Added support for the latest Live2D Cubism SDK based on the URP renderer.
• Added a customizable notification when state recovery occurs.
• Added system font fallback in the editor when rendering glyphs unsupported by the game fonts.
• Added auto registration of the generated localization documents with Addressables when installed.
• Added Import Source option to the Spreadsheet utility. When enabled, the source scenario scripts will be rewritten with the source locale column in spreadsheets. Useful for proofreading the scenario content along with translations.
• Improved @choice: it can now be used without restrictions, including in conditional and non-deterministic contexts.
• Added cut/copy/paste operations for lines in the Story Editor.
• Added an option to paste from the clipboard directly into the Story Editor, allowing you to paste, for example, scenario scripts from the docs or VS Code directly into the editor.
• Added an option to select and drag-and-drop multiple lines in the Story Editor.
• Added context commands for tabs in the Story Editor: close, close all, close other, close to left/right.
• Added support for spaces after the script path in navigation endpoints, allowing them to be formatted as @goto Script # Label.
• Added Push Rollback Snapshot method to the State Events component for pushing snapshots from Unity events.
• Added @pushRollback command allowing the player to roll back to a specific point in the scenario script.
• Added support for Spine SDK version 4.3.
• Added an option to specify animation tracks for Spine actors in scenario scripts. ^[doc]
• Added Control Animation parameter to the Spine actor controller; when enabled, the appearances will map automatically to animations and respect the transition duration parameter.
• Added Default Track parameter to the Spine actor controller for changing the animation track index used when it's not specified in scenario script commands.
• Added syntax highlighting for managed text documents (including localization documents) to the VS Code extension.
• Added wpos alias to the position parameter in supported commands and made it mutually exclusive with pos where applicable for clarity.
• Added roll parameter to actor and spawn commands as a shorthand for Z-axis rotation.
• Added transient parameter to the @spawn command; when enabled, the spawned object won't serialize with the game state and won't require @despawn later — useful for one-shot short-lived effects.
• Added automatic unloading of audio resources once their associated clips stop playing.
• Added Main Renderer and UI Renderer to the camera configuration for selecting custom URP renderers for the main and UI cameras respectively without having to assign custom camera prefabs.
• Added automatic UI focus fallback when the focused object is not interactable.
• Added Linux support for the embedded Story Editor.
• Added an explicit player-facing error message when a save fails; it's possible to customize the behaviour by overriding the new HandleSaveFailed method of the StateManager service.

Changed

• The minimum supported Unity version changed to 6.7.
• Removed the legacy script graph and visual scenario editor (use the Story Editor instead).
• Removed the legacy @animate command (use @async instead).
• Changed the assignment expression separator from ; to , (semicolon is now used by inline comments); use the upgrade script to automatically upgrade scripts.
• Expression functions have been renamed to queries; all the associated APIs and features have to be updated accordingly.
• Renamed [ConstantContext] metadata attribute to [EnumContext] to prevent confusion with the newly introduced expression constants.
• The g_ and t_ custom variable prefixes no longer have any significance. To initialize meta (previously "global") variables with the @set command, use the meta! and const! flags for metas and constants respectively.
• The concept of "Nameless Parameter" is renamed to "Primary Parameter" for clarity.
• Replaced IntegerParameter and DecimalParameter with a single NumberParameter.
• Renamed APIs related to variables from "CustomVariable" to "Variable"; for example, ICustomVariableManager is now IVariableManager.
• Separated BGM and SFX audio resources: they now each have their own resource loader and category.
• Changed the effect of the wait parameter on the @bgm and @sfx commands: it now waits until the played clip ends instead of waiting for the fade-in/out to finish; added waitFade parameter to do that instead.
• The layered actor implementation is deprecated and will be removed in the next release. Use the new universal actor implementation with the Layered Actor Controller component instead. ^[doc]

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 in the "Patches" section of the previous release changelog.

• Fixed printer resources not being unloaded from memory when the actor is removed from the scene.
• Fixed choice handlers ignoring transform parameters of the @choiceHandler command.
• Fixed @sun, @rain and @snow ignoring initial pos and wpos parameters.
• Fixed UI focus and navigation issues when the target object is disabled in the hierarchy or not interactable.
• Fixed first-time setup skipped in projects sharing a name with a previously opened one.