1.18 Release Notes

Release date: Q4 2022

CAUTION

This release is out of support and won't receive any new features or bug fixes. Consider upgrading to the latest stable or preview release as soon as possible.

Compatibility

Supported Unity versions: 2019.4.40, 2020.3, 2021.3. Previous and non-LTS (tech) versions are not supported; compatibility issues with newer versions will be addressed in the next Naninovel releases.

Recommended Unity version: 2019.4.40 ↗. It's not uncommon for Unity to introduce regressions even in LTS patches (let alone minor and major releases), so we highly recommend using this version to minimize production risks.

Upgrade Guide

When importing the package to a project with Naninovel version 1.16 or older first follow v1.17 release ↗ upgrade guide, then continue with the following instructions:

1. Remove Naninovel folder from the project before importing the updated package.
2. In case using extension packages, update them: Spreadsheet ↗, Live2D ↗, Spine ↗, Inventory ↗, PlayMaker ↗, AdventureCreator ↗.
3. To use the newly added chat reply choice handler, add ChatReply actor in resources manager; built-in prefab is stored at Naninovel/Prefabs/ChoiceHandlers.
4. It's no longer required to double-escape quotes inside script expressions, so remove the additional escape symbols in case you've used them in scenario scripts; eg @set var="lorem \\"ipsum\\"" should be changed to @set var="lorem \"ipsum\"".

Remember to keep NaninovelData folder when updating the engine to preserve project configuration and asset references. If an error about failing to load an asset is logged after the upgrade, restart Unity editor.

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

In case using VS Code IDE extension, check for updates.

Don't forget to backup the project before upgrading or use a VCS ↗.

Added

• Added Fountain converter tool allowing to convert .fountain screenplay documents into .nani scripts.
• Added shared poses allowing to re-use a pose between actors. (guide ↗)
• Added an option to inject custom metadata providers. (guide ↗)
• Added an option to specify constant expressions to be evaluated by the IDE extension. (guide ↗)
• Added script labels auto-completion for @goto and @gosub commands; can be disabled via Generate Label Metadata option in engine configuration.
• Added @despawnAll command allowing to de-spawn (destroy) all the currently spawned objects.
• Added an option to filter and auto-asign items in voice map utility. (example ↗)
• Added Wait Hide On Choice option to choice handlers. When enabled, choice handler will wait until the UI is completely hidden before proceeding when a choice is picked. (example ↗)
• Added Hide In Thumbnail option to Custom UI component allowing to prevent specific UIs from appearing in save-load slot thumbnail. (example ↗)
• Added support for UI camera under URP.
• Added Font Changer component allowing to sync font with game settings on arbitrary game objects (eg, choice handler button prefabs).
• Added support for blur FX for scene backgrounds.
• Added spine background actor implementation (via spine extension).
• Added Wait Visibility Before Print option to text printers; when enabled, full Change Visibility Duration will be awaited before starting to print the text. (example ↗)
• Added XML documentation files for the pre-compiled engine libraries.
• Added an option to auto-apply a font when a specific locale (language) is selected; set in UI configuration via font options. (example ↗)
• Added Default Slant Angle to revealable tmpro text component allowing to set slant angle of the reveal rect outside of italic text.
• Added CSV format option for voiceover document generation utility.
• Added Wait After Reveal Skip option to printer metadata (enabled by default); if disabled, wait for input won't be activated when text reveal is skipped. (example ↗)
• Added an option to inject custom voiceover document generator. (guide ↗)
• Added an option to inject custom spreadsheet processor. (guide ↗)
• Added Link Template property and On Link Clicked event to Naninovel TMPro Text component allowing to stylize the <link>-tagged content and attach Unity event handlers when the links are clicked.
• Added ChatReply built-in choice handler and updated Chat and TMProChat printers to support embedded choices. (guide ↗)
• Added a prompt to confirm directory clean when generating voiceover documents while the target directory is not empty.
• Added parameter to "LineReveal" transition effect allowing to reverse the effect.
• Added an option for a video actor appearance to not loop by appending NoLoop (not case sensitive) to the appearance name.
• Exposed transitional renderer materials to allow setting properties of custom actor shaders.
• Expression functions now accept arguments of assignable types, even when they're not equal (eg, int to double).
• Making multiple UIs modal is now supported.
• Most members of the built-in resource providers can now be overridden.
• Bridging transport will now automatically scan port range starting with the preferred port specified in the engine configuration; no warnings will be logged when multiple editor instances are opened.
• VS Code IDE extension can now work in web browsers via vscode.dev ↗.
• .NET runtime is no longer required by the VS Code IDE extension.
• It's now possible to localize UI resources (prefabs) in the same way as the other resource types.
• It's now possible to specify parameter context for the parameter fields declared in parent classes and override them; consult the updated IDE docs ↗ for examples.
• It's now possible to use layered expressions in generic text line author prefix, eg Miho.Costume>Uniform: Hello!.
• A managed text document for locales (language tags) is now automatically generated and is used when displaying available languages in the settings menu allowing to change and/or localize them.
• Backgrounds of different sizes are now matched during transitions when match mode is set to crop.
• Shake printer FX implementation is no longer coupled with specific content object name.
• Script parse errors detected on asset import will now contain full file path.
• Spreadsheet extension will now specify associated file paths when processing exception occurs.
• Voiceover documents will now also contain voiced line hash.
• Improved package path resolving performance in editor.

Changed

• Minimum supported Unity version changed to 2019.4.35 due to #119.
• Invisible UIs with Canvas Group component will now be set as non-interactable to improve keyboard and gamepad navigation.
• Game objects under "Naninovel" root object are now grouped based on their type (UI, characters, backgrounds, etc).
• Default Naninovel addressable group will now have bundle mode set to Pack Separately to allow asset unloading.
• Naninovel will now throw Naninovel.Error exception instead of System.Exception.
• Changed some of the script parsing models and semantic tokens used to highlight the script in VS Code; refer to the IDE guide ↗ for the updated info.
• Type of all the pixels per unit (PPU) related properties has been changed from int to float for flexibility and better compatibility with Unity internals.
• It's no longer required to double-escape quotes inside script expressions.
• Command values in visual script editor are now displayed identical to the text in the inspected script. It's now expected for user to apply the same rules when specifying the values in visual editor, including wrapping the value in quotes in case they contain white space and escaping the quotes that are meant to be printed.
• Occlusion culling is now disabled by default for both main and UI cameras; the cameras can be overridden in camera config.
• Wait for input mode (eg, activated by @wait i) will now wait for the currently played voice to finish before proceeding in auto play mode.

Fixed

• Fixed DepthOfField FX not working correctly in ortho mode on Android devices.
• Fixed scene backgrounds loading duplicate scenes on script preload.
• Fixed "continue" button in built-in title menu not updating state when all save slots are deleted.
• Fixed spawned FX state not reapplied in sync when loading a saved game.
• Fixed line reveal transition effect not completing correctly.
• Fixed out of range exception when using custom audio mixer without any channels.
• Fixed positioning via animate command not working correctly with printer actors.
• Fixed back command not preloaded when appearance is specified outside of nameless parameter.
• Fixed un-escaped quotes in generic text script lines not preserved in the printed text.
• Fixed .mp3 files not found with local resource provider.
• Fixed reveal effect not updating in the same frame after UI layout is changed.
• Fixed multiple modal UIs being interactable at the same time.
• Fixed nullref when event system is not found; a meaningful error will be logged instead.
• Fixed create custom toast UI menu item is missing.
• Fixed input indicator position not updated when changing font.
• Fixed language dropdown list in settings menu not updating when changing locale via other methods.
• Fixed incorrect actor appearance applied when changing the appearances concurrently while under non-source locale and the appearance has a localized variant.
• Fixed IO sharing exception when multiple built-in settings UI are spawned concurrently.
• Fixed text reveal effect affecting previously revealed characters after appending printed text.
• Fixed unlockable records not registered until @unlock command is executed; @unlock * will now correctly unlock all the records specified in unlockable resources.
• Fixed voiceover utility not generating documents until entering play mode.
• Fixed default scrollwheel binding not working properly with input system v1.2 and newer.
• Fixed auto voices being played while in skip mode.
• Fixed video actors incorrectly disposed when loading another script.
• Fixed compatibility issues with Unity 2022.2.
• Fixed @animate command ignoring default actor easing.
• Fixed on choice script playback not handling state rollback correctly.
• Fixed Default Fade Duration option in audio config not affecting @stopBgm and @stopSfx commands.
• Fixed auto voices not played after loading a saved game and rolling back.
• Fixed last played spot not serialized in rollback stack when saved while waiting for input or choice.
• Fixed messages in backlog added without player input loosing rollback option after save-load.
• Fixed script graph fails to load when navigation parameter value contain a script expression.
• Fixed last choice button focused instead of the first one when Focus Choice Buttons enabled on choice handler.
• Fixed OS-unsupported window options available in game settings.
• Fixed incorrect error description when failing to load a spawn resource.
• Fixed tips UI not updating translated records after changing locale.
• Fixed resource logger causing exception when engine's root object is destroyed.
• Fixed default appearance of sprite actors not unloaded.
• Fixed sprite actor resources not released by modify command when using remove:true in @hide commands.
• Fixed swipes not registered when using Unity Remote.
• Fixed background actors missing pose attribute enable/disable toggle.
• Fixed @wait command with wait:false being awaited.
• Fixed dynamic parameter values evaluation outside of playmode.
• Fixed auto arrange triggered when adding character rendered to texture.

Patches

• [1] Fixed wrong video actor appearance unloaded causing nullref after loading a saved game and performing rollback.
• [1] Fixed character message audio clip not preloaded after rollback to another script.
• [1] Fixed error in script graph when using choice command with dynamic if parameter.
• [1] Fixed exceptions in WebGL builds caused by the lack of threading support on the platform.
• [1] Fixed Font Changer component not changing font back to default.
• [1] Fixed text printer disappear on display aspect ratio change.
• [1] Fixed return button in External Scripts UI not working due to modal state.
• [2] Fixed tooltip missing on properties with [ResourcePopup] and [ActorPopup] attributes.
• [2] Fixed input processing being active before the engine is completely initialized.
• [2] Fixed interaction not blocked properly while loading title and initialization scripts.
• [2] Fixed text reveal broken in TMPro printers when using char reveal SFX.
• [2] Fixed transition effects broken when camera is in perspective mode and background matching is enabled.
• [2] Fixed ncalc failing to resolve function names under some locales.
• [2] Fixed build failing when using Unity's AR/XR features.
• [2] Fixed hot-reload causing commands to execute twice when modifying lines before the currently played one.
• [2] Fixed error when importing google drive extension package.
• [2] Fixed @unlock * not unlocking tips unless they were previously unlocked.
• [2] Fixed auto voice not awaited when wait for input is disabled for the associated print command.
• [2] Fixed interaction with UI object triggers not being processed in consistent order.
• [2] Fixed error when loading a game saved at deleted script line followed by non-playable line.
• [2] Fixed Submit On Input option of variable input UI not working by default due to missing Submit input in the allowed samplers list.
• [2] Fixed "Exit" button in title UI and @openURL command opening new tab instead of re-using current tab when executed under WebGL (target param has been also added allowing to request a new tab when required).
• [2] Fixed RTL text reveal effect clipping last character.
• [2] Fixed UI not visible in save slot thumbnails when using URP.
• [2] Fixed scene background automatically unloaded on goto and gosub even when "Unload On Goto" is disabled.
• [2] Fixed Arabic text processed twice on Naninovel TMPro Text component initialization.
• [2] Fixed default appearance of sprite actors not loaded when appearance parameter is not specified in scripts.
• [2] Fixed IClockThroughPanel UI not being hidden, which caused input sampling not working correctly in some cases.
• [2] Fixed unintended choice activation after continuing input via submit button while choice handler has Visibility focus mode and Focus Choice Button enabled.
• [2] Fixed currently played line skipped when activating skip input while in "Read Only" skip mode and next line hasn't been played.
• [3] Fixed @wait command in timer mode preventing save from finishing.
• [3] Fixed Custom match mode of background actors not working correctly.
• [3] Fixed resource provider fails to locate available resources when invoking the method concurrently.
• [3] Fixed "Empty" label of save-load slot UI not updated when changing language at runtime.
• [3] Fixed variable name evaluation in script expression with compound assignment and whitespace after variable.
• [3] Fixed input indicator ignoring initial z-position when placed over printed text.
• [3] Fixed @despawnAll not working with shake and animate FX when they're not running in loop.
• [3] Fixed movie UI stuck when constantly activating cancel input while the movie is preparing for playback.
• [3] Fixed out of bounds exception when specifying empty nameless parameter.
• [3] Fixed non-global custom variables not initialized after engine initialization.
• [3] Fixed ruby tag incorrect offset when using TMPro margins.
• [3] Fixed scene background render texture missing depth buffer resulting in incorrect sorting.