Naninovel

Appearance

1.19 Release Notes ​

Release date: Q4 2023

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.

Highlights ​

cover

Compatibility ​

Supported Unity version range: 2019.4 - 2022.3. Only latest patches of the LTS streams in the range are supported; compatibility issues with newer Unity releases (once they reach LTS) will be addressed in the next Naninovel releases. Be aware, that alpha, beta and non-LTS releases (eg 2022.1 or 2022.2) are not supported. They may work, but we won't be able to provide any support for using Naninovel with them.

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

Upgrade Guide ​

WARNING

This release has major breaking changes requiring potentially labor-heavy upgrade procedures, namely:

  • All the custom UIs built with legacy uGUI text have to be upgraded to use TMPro text instead;
  • All the scenario script localizations have to be redone from scratch;
  • All the auto-voicing has to be re-mapped from scratch.

Consider the above when deciding whether to upgrade projects in late development stages and especially shipped projects. Complete upgrade guide can be found below.

When importing the package to a project with Naninovel version 1.17 or older first follow v1.18 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: Live2D ↗, Spine ↗, Inventory ↗, PlayMaker ↗, AdventureCreator ↗. Spreadsheet tool is now embedded to the core package, so if you have it installed, remove the folder with the tool.
  3. Due to removal of the legacy (uGUI) text components and text reveal revamp, you may have to re-setup various UI objects; eg: customized built-in UIs, text printers, font settings, etc.
  4. In case using line breaks via \n in managed text values, replace them with <br>.
  5. In case using expressions for generic line author (eg, {mc}: Hi), use display name instead. (guide)
  6. In case having existing tips managed text documents, either remove Tips from managed text config's Multiline Categories list or format existing documents in multiline (same as script localization documents).
  7. In case having existing script localization documents, delete and re-create them with the new system. (guide ↗)
  8. In case having existing voice mappings via voice map utility, re-map the clips. (guide ↗)
  9. To use new adapt to input mode feature, add Page, Tab, Delete, NavigateX, NavigateY, ScrollY and ToggleConsole bindings in input config with enabled Always Process option (actual action bindings are configured via Unity's input system actions asset); check input example ↗ project for reference setup.
  10. In case using custom Title UI, enable Visible on Awake on the UI prefab to show it after engine is initialized.
  11. In case using bridging (VS Code extension or web editor), install Newtonsoft Json ↗ via Unity's package manager. (the package is only used in editor and is not required by Naninovel runtime in builds)
  12. In case using custom commands and VS Code extension, purge cached metadata in VS Code by pressing Ctrl+Shift+P and selecting Naninovel: Purge cached Metadata.

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 for both the Naninovel package and VS Code itself (only the latest version of VS Code is supported).

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

Added ​

  • Added adapt to input mode feature, which detects current active input mode (mouse and keyboard, gamepad or touch) and adapts the UI look and navigation accordingly. (guide)
  • Default UI has been updated for more consistent look and better UX.
  • Added utilities for automated end-to-end scenario testing and coverage. (guide)
  • Added community localization feature. (guide ↗)
  • Added Stable Identification option to script configuration menu; when enabled, Naninovel will automatically write unique persistent IDs to each localizable text parameter on script import. This allows preserving text association (eg, for localization or auto voicing) while editing text content. (guide ↗)
  • Language is now switching faster and text is updated instantly in all the printers and UIs, including backlog.
  • Added Character Extractor utility allowing to find all the unique text characters ever displayed to the player by Naninovel; useful for optimizing TMPro atlases, especially for CJK languages. (guide)
  • Added Render Camera option to layered actors allowing to render the prefab content with a camera, which lifts all the previous limitations (such as lacking stencil support) and allows rendering non-trivial objects, like particle systems, trails, etc. (guide)
  • Added Render Only and Default Appearance options to layered behavior component allowing to outsource appearance handling to external mechanisms, such as Unity's Animator. (guide ↗)
  • Added Slack Opacity option to revealable text; when below 1 will change opacity of the text that was printed before last append.
  • Added Reveal Paginator component allowing to split the revealed text between virtual pages in case of overflow; enabled by default in Fullscreen printer.
  • Added event tags allowing to execute arbitrary actions when printed text is revealed. (guide)
  • Added dedicated commands for all the built-in effects: @blur ↗, @bokeh ↗, @glitch ↗, @rain ↗, @shake ↗, @snow ↗, @sun ↗.
  • Added Load On Goto option to script player configuration; when enabled (default) will show ILoadingUI when @goto command requires loading another script to mask the loading process with the loading screen.
  • Added ColorContext and VectorContext parameter value context attributes.
  • Added Engine.UseLogger method allowing to inject custom logger to be used by the engine.
  • Added clickable link to the script asset that is missing translation when using localization utility.
  • Added time parameter to initialize engine method allowing to override time service used by Naninovel (eg, to make it use custom time/unscaledTime instead of Unity.Time values).
  • Added Font Sizes asset (created via Create -> Naninovel -> Font Sizes asset context menu) assignable to font configuration of custom UIs and printers; can be used to share common font sizes across multiple UIs.
  • Added Include Children option to font change configuration; when enabled, font changes will affect all the text components of the children game objects.
  • Added Reveal Instantly option to text printer metadata; when enabled, the printer will always show full message instantly, no matter speed settings.
  • Added Languages option to localization configuration menu allowing to change pre-defined language tag -> display name mappings.
  • Added Font Loader option to UI configuration allowing to modify loader behaviour for font assets.
  • Added Debug Only Console option to engine configuration; when enabled, development console will only be available in debug (development) builds.
  • Added concatenate operator for constant expressions of IDE metadata allowing to combine multiple constants; find usage examples in built-in @char and @back commands where the concatenation is used to combine shared with actor-specific poses.
  • Added check for duplicates when grag-dropping script assets to the resources list; the duplicates won't be added and warning will be logged.
  • Added resetAuthor parameter to @resetText command allowing to also reset author of the text printer (disabled by default).
  • Added Modal Group option to custom UI, which allows preventing UI from yielding modal status when another UI with the same group is made modal. When * is assigned, the UI will never yield modal status (useful for debug UIs that should always remain interactable).
  • Added Player Resolve Mode option in player configuration allowing to select how player should handle missing playback spots when loading state: find nearest playable line (next or previous), restart current script or throw an error.
  • IDE metadata for actor poses (both shared and actor-specific) is now generated providing auto-completion for VS Code and standalone editor.
  • It's now possible to omit label when navigating to the currently played script with @goto; the script will be played from the start in this case.
  • Text reveal effect now supports printer rotation.
  • IDE extension now supports go to definition for navigation parameters (eg, @gosub and goto parameter in @choice command); by default, the action is activated with F12 key when editing script or label navigation parameter or by holding Ctrl when hovering over the parameters. (example ↗)
  • IDE extension now reports errors in all the project scripts, not only the opened ones; can be disabled in configuration.
  • IDE extension now allows folding label regions.
  • Text ID auto voice mode (previously Content Hash) now support voice languages.
  • Spreadsheet tool is now embedded to the core package and doesn't modify source scripts on import. (guide ↗)
  • Legacy (old) input backend is no longer required when using new input system.
  • Script import error now contains link to the associated script asset and line.
  • Development console GUI will now scale up when screen resolution is above 1920x1080 for better UX on devices with small screens.
  • Development console now has completion list of registered commands shown when starting typing a known command; shows all available command when input starts with a space. Pressing Tab will complete first command in the list.
  • Development console now support string parameters with whitespace (via wrapping them in double or single quotes).
  • Development console will now persist input buffer (previously entered commands) between editor play sessions.
  • It's now possible to escape author assign (:) symbol in generic text lines, eg: author\: message will print author: message without assigning author id to the printed message.

Changed ​

  • Removed all the components that used legacy (uGUI) text; all the built-in UIs are now using TMPro text. Non-TMPro text printers have been removed; TMPro printers have been renamed, eg: TMProWide is now Wide.
  • Revamped text reveal effect: instead of modifying text shaders the effect is now applied to text mesh via C# API, making it more robust and customizable (doesn't require setting custom material, works with all TMPro features, no font-specific masking issues, etc). (guide ↗)
  • Input indicator object is now expected to be part of the text printer prefab, external assets will no longer be automatically instantiated (use nested prefab instead).
  • Removed Load Start Delay option from state configuration. The related operations will now asynchronously wait for loading UI to appear (in case the UI is available) before starting.
  • Character display names will now be fetched from managed text even when under source locale and will override values set in actor configuration.
  • Font Sizes property of font change configuration property is changed to asset reference to allow sharing font sizes between UIs.
  • Font assets are no longer assigned directly in UI configuration to prevent asset duplication when using addressables; path to font resource is expected instead.
  • Removed Clear On Locale Change option from built-in backlog UI; all the localizable text will now be updated for the target locale when changing language, so it's no longer required to clear it.
  • Default key frame delimiter of @animate command is now , (comma); colon | is still supported for backward compatibility, but refrain from using it in new projects, as it may be removed in future release.
  • Script navigator UI prefab has been moved to default UIs and can be accessed and controlled in the same way as other UIs via IScriptNavigatorUI interface. Enable Navigator and Navigator Order options in scripts configuration have been removed; they can be controlled on the UI prefab directly. Show Navigator On Init option has been renamed to Show Script Navigator and will make the UI show and refresh automatically on initialization (disabled by default).
  • Line breaks in managed text document values should now be inserted with <br> tags (\n is no longer supported).
  • Expressions in generic text line author segment are no longer supported; use display names instead.
  • Default managed text document format for unlockable tips is changed to multiline (same as script localization documents); can be changed back to old inline format by removing Tips from Multiline Categories list in managed text configuration.
  • Script localization system has been revamped: localization documents are now .txt instead of .nani and contain only the localizable text, so it's no longer required to preserve inlined commands, script expressions, author names, etc.
  • Content Hash auto voice mode renamed to Text ID and is now the default; clips are no longer associated with script lines content hash, but with localizable text IDs.
  • Removed MP3 to Unity's audio clip converter and associated third-party lib from the distributed package (was used with local and google drive resource providers only); you can add back the converter by overriding provider manager service. (example ↗)
  • Spreadsheet tool is now exporting sheets in .csv format instead of .xlsx, contain only localizable text and doesn't modify source scripts on import.
  • Audio of video backgrounds is now routed to BGM audio mixer group; audio of video characters is routed to Voice group (previously both were routed to Master group). This can be changed by overriding MixerGroup property of VideoActor class.
  • When using "Apply On Locale" font option, the font will now be changed back to default when changing to locale that doesn't have an associated font.
  • All built-in UIs are now configured to be affected by font changes (font type only, size is still only applicable to text printers); can be changed per-UI via Font Change Configuration option.
  • "Toggle Console Key" option has been removed from engine configuration; it's now controlled via ToggleConsole input binding.
  • Default font changed to Inter.
  • "Show Title UI" option has been removed from engine configuration and instead Title UI now has "Visible On Awake" enabled. Any UI with the option enabled will now be shown after engine initialization.
  • When generic line doesn't contain any text to print (via either plain text or inlined print commands), it will no longer wait for input after all the inlined commands are executed.
  • Bridging (communication with VS Code extension and web editor) now requires Newtonsoft Json ↗ extension installed via Unity's package manager. The package is only used in editor and is not required by Naninovel runtime in builds.

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 VS Code extension not opening played lines of scripts stored in sub-folders.
  • Fixed input events propagated to scene while typing in dev console when new input system is used.

Patches ​

  • 2023-12-10 Fixed error not logged when expression evaluation in if command parameter fails.
  • 2023-12-29 Fixed warning not logged when unknown group is specified in layered expression.
  • 2024-01-25 Fixed warning not logged when playing unknown voice.
  • 2024-02-10 Fixed incorrect month formatting in game save slots.
  • 2024-02-25 Fixed choice button not creating via assets context menu.
  • 2024-03-01 Fixed script graph loosing state when saving and re-entering play mode twice.
  • 2024-03-01 Fixed custom variables with unsupported names accepted w/o warning in the editor.
  • 2024-03-02 Fixed error thrown when character message sound is not preloaded.
  • 2024-03-15 Fixed text shader changed when changing font.
  • 2024-03-19 Fixed built-in variable input UI missing pre-defined value changed handler.
  • 2024-03-21 Fixed tips button on printer control panel incorrectly shown when display aspect ratio is changed.
  • 2024-03-21 Fixed initialization script conflicting with title.
  • 2024-03-22 Fixed title script played before engine is initialized.
  • 2024-03-27 Fixed control panel of dialogue printer affected by font size change.
  • 2024-03-27 Fixed movie played w/o sound after playing a movie which had no sound.
  • 2024-04-01 Fixed UI selectables not cleared when re-enabling associated component.
  • 2024-04-01 Fixed language dropdown UI not updating labels on locale switch.
  • 2024-04-01 Fixed input indicator incorrect position when placed after quotes.
  • 2024-04-08 Fixed backlog UI capacity not enforced correctly.
  • 2024-04-08 Fixed consequent text reveal completed instantly when print requested while revealing.
  • 2024-04-12 Fixed input trigger touches not detected correctly when using new input system.
  • 2024-04-15 Fixed choice not added to backlog when the choice command is followed by stop and other choice command.
  • 2024-04-18 Fixed settings menu bleeding exit input when gamepad scheme is active.
  • 2024-04-22 Fixed voice continue playing on rollback and game load.
  • 2024-04-22 Fixed preview printer ignoring min auto delay setting.
  • 2024-04-28 Fixed CG gallery failing to show previously selected texture after changing page.
  • 2024-04-28 Fixed malformed save files causing nullref on load.
  • 2024-05-01 Fixed button label color tween being affected by time scale.
  • 2024-05-10 Fixed text reveal fade effect with slack setting below 1.0 not cleared on text reset.
  • 2024-05-15 Fixed author pose in generic line prefix recognized as appearance.
  • 2024-06-06 Fixed global save corruption when clicking exit button multiple times.
  • 2024-06-29 Fixed state of chat printer instances not discriminated.
  • 2024-07-14 Fixed generic line serialization regression caused by 2024-05-15 patch.
  • 2024-07-24 Fixed incorrect sprite actor appearance after loading a save while using a localized appearance resource.
  • 2024-08-01 Fixed script preload progress callback not invoked with 1.0 when script has no preloadable commands.
  • 2024-08-10 Fixed package root path not cached on consequent requests.
  • 2024-08-15 Fixed leading inlined @char command interpreted as a prefix when serializing generic script lines.
  • 2024-08-22 Fixed input events associated with continue input triggers propagating to the UIs shown with @showUI commands when using legacy input.
  • 2024-08-24 Fixed @playSfxFast unloads audio resource before it's played when it's the only command in a transient script.
  • 2024-09-22 Fixed voice map utility error when target script has dynamic text values.
  • 2024-09-24 Fixed settings not saved when exiting the menu with a gamepad.
  • 2024-09-24 Fixed voice map utility ignores voiced lines containing dynamic values.
  • 2024-09-29 Fixed inactive modal UIs handling input.