Naninovel

https://naninovel.com/guide
Admin
Naninovel is an extension for Unity featuring authoring tools and a C# framework for creating...
Tokens:58,815
Snippets:795
Trust Score:7.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example of a localized entry

Source: https://naninovel.com/guide/localization

A practical example showing how to format a translation with HTML tags.

```nani
# aj0e5dea
; Aliquam ut <b>ultricies</b> enim, id venenatis.<br>Nullam rhoncus eros tempus.
Оценивая блеск <b>металлического</b> шарика, пространство равноденственно.<br>
Противостояние есть метеорный дождь.
```

--------------------------------

### Use Nameless Parameters

Source: https://naninovel.com/guide/scenario-scripting

Example of a command using a nameless parameter for resource paths.

```nani
@bgm PianoTheme
```

--------------------------------

### Localized Resource Path Example

Source: https://naninovel.com/guide/localization

Example directory structure for replacing a background sprite when the ja-JP locale is active.

```text
Resources/Naninovel/Localization/ja-JP/Backgrounds/MainBackground/City
```

--------------------------------

### Scenario Directory Structure

Source: https://naninovel.com/guide/scenario-scripting

Example of a project directory structure where the scenario root is defined.

```text
Assets
└── Scenario/
    ├── Prologue.nani
    ├── CommonRoute/
    │   ├── Day1/
    │   │   ├── Scene1.nani
    │   │   └── Scene2.nani
    │   └── Day2/
    │       └── Scene1.nani
    └── RouteX/
        └── SceneX.nani
```

--------------------------------

### Install Naninovel via GitHub UPM

Source: https://naninovel.com/guide/getting-started

Use this Git URI format in the Unity Package Manager to install specific versions from the GitHub repository.

```text
https://github.com/naninovel/upm.git#1.21
```

--------------------------------

### Lazy Loading Execution Flow

Source: https://naninovel.com/guide/memory-management

Example demonstrating how resources are loaded and unloaded based on the Lazy Buffer setting during script execution.

```nani
@back Snow
@bgm Ambient
@back Town
@goto Script2
```

```nani
@back Snow

```

--------------------------------

### Test Assembly Setup in manifest.json

Source: https://naninovel.com/guide/automated-testing

Configure your project's manifest.json to make Naninovel testable. This is required when Naninovel is installed as a UPM package.

```json
{
    "dependencies": {
        "com.elringus.naninovel": "...",
        "other-packages": "..."
    },
    "testables": [
        "com.elringus.naninovel"
    ]
}
```

--------------------------------

### Optimistic Policy Script Examples

Source: https://naninovel.com/guide/memory-management

Demonstrates resource management under the Optimistic policy where resources remain loaded unless explicitly released.

```nani
Resources from Script1, Script2, Script3, and ScriptGosub are all loaded here.
Script4 is not loaded because it's navigated to with "@goto release!".

...

Loading screen won't show because gosubs are always preloaded.
@gosub ScriptGosub

...

Loading screen won't show by default unless "release!" is specified.
@goto Script2
```

```nani
Everything except Script4 is still loaded.

...

Loading screen won't show by default unless "release!" is specified.
@goto Script3
```

```nani
Everything except Script4 is still loaded.

...

Loading screen won't show because gosubs are always preloaded.
@gosub ScriptGosub

...

Loading screen will now show because of "release!".
@goto Script4 release!
```

```nani
All resources except Script4 are now unloaded, because we navigated here
with "@goto release!".

...

@stop
```

```nani
Various resources may be loaded here, depending on which script
navigated here.

...

Loading screen won't show, as gosubs are always loaded with the script
that navigates to the gosub and are not unloaded until that script unloads.
@return
```

--------------------------------

### Custom Spawn Command

Source: https://naninovel.com/guide/special-effects

Example of a custom command implementation for spawned effects to improve readability and type-checking.

```nani
@explode Kohaku power:3 smoke!
```

--------------------------------

### Apply Easing to Transition

Source: https://naninovel.com/guide/special-effects

Example of using the easing parameter with a background transition command.

```nani
@back River.DropFade time:1.5 easing:EaseOutBounce
```

--------------------------------

### Canonical Endpoints

Source: https://naninovel.com/guide/scenario-scripting

Full path navigation starting from the scenario root.

```nani
; Navigate to the start of the 'Assets/Scenario/Prologue.nani' script.
@goto Prologue
; Navigate to the 'Action' label in
; 'Assets/Scenario/CommonRoute/Day1/Scene1.nani' script.
@goto CommonRoute/Day1/Scene1#Action
```

--------------------------------

### Shake Effect Examples

Source: https://naninovel.com/guide/special-effects

Examples for shaking the camera or specific actors with custom parameters.

```nani
; Shake the current default text printer
@shake

; Shake "Kohaku" actor with default params
@shake Kohaku

; Shake the main camera horizontally 5 times
@shake Camera count:5 hor!
```

--------------------------------

### Basic New Game Test

Source: https://naninovel.com/guide/automated-testing

A simple test to verify that a new game can be started. It waits for the title UI, clicks the 'NewGameButton', and ensures the script player starts.

```csharp
[UnityTest]
public IEnumerator CanStartGame () => new E2E()
    .Once(() => Engine.GetService<IUIManager>().GetUI<ITitleUI>().Visible)
    .Click("NewGameButton")
    .Ensure(() => Engine.GetService<IScriptPlayer>().Playing);
```

--------------------------------

### Snow Effect Examples

Source: https://naninovel.com/guide/special-effects

Examples for controlling snow intensity and duration.

```nani
; Start intensive snow over 10 seconds
@snow power:1 time:10

; Stop the snow over 30 seconds
@snow power:0 time:30
```

--------------------------------

### Rain Effect Examples

Source: https://naninovel.com/guide/special-effects

Examples for controlling rain intensity and duration.

```nani
; Start intensive rain over 10 seconds
@rain power:1 time:10

; Stop the rain over 30 seconds
@rain power:0 time:30
```

--------------------------------

### Scenario Script File Structure

Source: https://naninovel.com/guide/scenario-scripting

Example of the directory structure for organizing scenario scripts in a Naninovel project.

```text
  * `Episode 1/Scene 1.nani`
  * `Episode 1/Scene 2.nani`
  * `Episode 2/Scene 1.nani`
```

--------------------------------

### Install SpriteDicing via Git URL

Source: https://naninovel.com/guide/characters

Use this URL in the Unity Package Manager to add the SpriteDicing package to your project.

```text
https://github.com/elringus/sprite-dicing.git?path=/plugins/unity/Assets/SpriteDicing
```

--------------------------------

### Define a Title Script

Source: https://naninovel.com/guide/scenario-scripting

Configures the initial scene, background music, and event handlers for menu interactions like starting a new game or loading a save.

```nani
; Set up the title menu look.
@back MainMenuBackground
@bgm MainMenuMusic
@spawn Rain
@showUI TitleUI
@stop

# OnNewGame
; Following commands will be executed when player clicks "NEW GAME".
; Notice that the "stopBgm" command is awaited, so that the music
; is fully stopped before the new game begins to load.
@sfx NewGameSoundEffect
@stopBgm wait!
@stop

# OnLoad
; Below commands will be executed when player loads a saved game.
@sfx LoadGameEffect
@wait 0.5
@stop

# OnExit
; Below commands will be executed when player clicks "EXIT".
@sfx ExitGameEffect
@wait 1.5
@stop
```

--------------------------------

### Conservative Policy Script Examples

Source: https://naninovel.com/guide/memory-management

Demonstrates resource management under the Conservative policy where resources are preloaded and unloaded based on script navigation.

```nani
Resources from Script1, Script2, and ScriptGosub are loaded here.
Script2 is loaded because it's navigated to with "@goto hold!".
ScriptGosub is loaded because "@gosub" scripts are always preloaded.

...

Loading screen won't show because gosubs are always preloaded.
@gosub ScriptGosub

...

Loading screen won't show because we're using "hold!".
@goto Script2 hold!
```

```nani
Resources from Script1, Script2, and ScriptGosub are all still loaded,
because this script was navigated to with "@goto hold!",
hence it's considered a dependency of Script1.

...

Loading screen will show because we're not using "hold!".
@goto Script3
```

```nani
Resources from Script1 and Script2 are now unloaded, while resources
from Script3 (this script) are loaded.
Resources from ScriptGosub are still loaded because we're using it here.

...

Loading screen won't show because gosubs are always preloaded.
@gosub ScriptGosub

...

Loading screen will show because we're not using "hold!".
@goto Script4
```

```nani
All previous resources are now unloaded (including ScriptGosub), and only
resources from Script4 (this script) are loaded.

...

@stop
```

```nani
Various resources may be loaded here, depending on which script
navigated to this one.

...

Loading screen won't show, as gosubs are always loaded with the script
that navigates to the gosub and are not unloaded until that script unloads.
@return
```

--------------------------------

### Glitch Effect Examples

Source: https://naninovel.com/guide/special-effects

Examples for applying digital distortion to the camera.

```nani
; Apply the glitch effect with default parameters
@glitch

; Apply the effect over 3.33 seconds with a low intensity
@glitch power:0.1 time:3.33
```

--------------------------------

### Executing Transient Commands via C#

Source: https://naninovel.com/guide/integration-options

Provides an example of triggering a Naninovel script from a Unity trigger event using the IScriptPlayer service.

```csharp
private void OnTriggerEnter (Collider other)
{
	var track = Engine.GetService<IScriptPlayer>().MainTrack;
	track.ExecuteTransientCommand("novel scriptPath:Script001").Forget();
}
```

--------------------------------

### @sfx

Source: https://naninovel.com/guide/audio

Starts or modifies sound effect playback.

```APIDOC
## @sfx

### Description
Starts playing a sound effect or modifies the parameters of currently playing sound effects.

### Parameters
- **clip name** (string) - Optional - The name of the audio resource to play.
- **loop** (flag) - Optional - Whether to loop the track (default is false).
- **!loop** (flag) - Optional - Disables looping.
- **volume** (float) - Optional - Target volume level (0.0 to 1.0).
- **time** (float) - Optional - Duration in seconds to apply volume changes.
- **group** (string) - Optional - The mixer group path to route the audio through.
```

--------------------------------

### Hide Actors Command

Source: https://naninovel.com/guide/scenario-scripting

Examples of hiding actors with and without a fade duration.

```nani
@hideAll
```

```nani
@hideAll time:5.5
```

--------------------------------

### Example path for ejected localization resources

Source: https://naninovel.com/guide/localization

The path where localization resources are stored on Windows after ejection.

```text
C:/Users/User/AppData/LocalLow/Foo/Bar/Localization
```

--------------------------------

### Verify WebView2 Runtime Version

Source: https://naninovel.com/guide/editor

Use this PowerShell command to check the installed version of the WebView2 Runtime on Windows to ensure compatibility with the Story Editor.

```powershell
(Get-ItemProperty 'HKLM:\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}','HKCU:\SOFTWARE\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}' -ErrorAction Ignore).pv
```

--------------------------------

### Persistent Effect Control

Source: https://naninovel.com/guide/special-effects

Shows how to start and stop persistent effects like rain.

```nani
; Start the rain
@rain
; Stop the rain
@rain power:0
```

--------------------------------

### Control Background Music Playback

Source: https://naninovel.com/guide/audio

Use the @bgm command to start, loop, fade, or adjust volume for background music tracks.

```nani
; Starts playing a music track with the name "Sanctuary" in a loop.
@bgm Sanctuary

; Same as above, but fades-in the volume over 10 seconds and plays only once.
@bgm Sanctuary fade:10 !loop

; Changes volume of all the played music tracks to 50% over 2.5 seconds
; and makes them play in a loop.
@bgm volume:0.5 loop! time:2.5
```

--------------------------------

### Get and Use Engine Service

Source: https://naninovel.com/guide/engine-architecture

Retrieve an engine service instance to interact with specific engine functionalities, such as the script player. Ensure the service interface is correctly specified.

```csharp
var player = Engine.GetService<IScriptPlayer>();
player.Stop();
```

--------------------------------

### Initialize Engine with Custom Provider

Source: https://naninovel.com/guide/custom-configuration

Use the RuntimeInitializer to register a custom configuration provider during application startup.

```csharp
public class CustomInitializer
{
    [RuntimeInitializeOnLoadMethod]
    private static void InitializeWithCustomProvider ()
    {
        var customProvider = new CustomConfigurationProvider();
        RuntimeInitializer.Initialize(customProvider).Forget();
    }
}
```

--------------------------------

### Implement Custom Engine Service in C#

Source: https://naninovel.com/guide/engine-services

Implement the `IEngineService` interface and use the `InitializeAtRuntime` attribute to automatically instantiate your service during engine initialization. Perform initialization logic in `InitializeService` and state resetting in `ResetService`.

```csharp
using Naninovel;
using UnityEngine;

[InitializeAtRuntime]
public class CustomService : IEngineService
{
    private readonly InputManager inputManager;
    private readonly ScriptPlayer scriptPlayer;

    public CustomService (InputManager inputManager, ScriptPlayer scriptPlayer)
    {
        // The services are potentially not yet initialized here,
        // refrain from using them.
        this.inputManager = inputManager;
        this.scriptPlayer = scriptPlayer;
    }

    public Awaitable InitializeService ()
    {
        // Initialize the service here.
        // It's now safe to use services requested in the constructor.
        Debug.Log(inputManager.ProcessInput);
        Debug.Log(scriptPlayer.PlayedScript);
        return Async.Completed;
    }

    public void ResetService ()
    {
        // Reset service state here.
    }

    public void DestroyService ()
    {
        // Stop the service and release any used resources here.
    }
}
```

--------------------------------

### Basic Shake Command Usage

Source: https://naninovel.com/guide/special-effects

Demonstrates basic actor shaking and parameter updates.

```nani
; Shake 'Kohaku' actor
@shake Kohaku
```

```nani
; Shake 'Kohaku' once (instead of the default 3)
@shake Kohaku count:1
```

```nani
; Start slowly shaking `Kohaku` actor in a loop
@shake Kohaku loop! power:0.1
Kohaku: It's rumbling!
; Shake 3 more times with an increased amplitude
@shake Kohaku count:3 power:0.8
```

--------------------------------

### Play Intro and Loop for BGM

Source: https://naninovel.com/guide/audio

Use the intro parameter to play a specific clip before transitioning to a looped main track.

```nani
; Plays "BattleThemeIntro" once and then "BattleThemeMain" in a loop.
@bgm BattleThemeMain intro:BattleThemeIntro
```

--------------------------------

### @bgm

Source: https://naninovel.com/guide/audio

Starts or modifies background music playback.

```APIDOC
## @bgm

### Description
Starts playing a music track or modifies the parameters of currently playing tracks.

### Parameters
- **clip name** (string) - Optional - The name of the audio resource to play.
- **fade** (float) - Optional - Duration in seconds to fade the volume.
- **loop** (flag) - Optional - Whether to loop the track (default is true).
- **!loop** (flag) - Optional - Disables looping.
- **volume** (float) - Optional - Target volume level (0.0 to 1.0).
- **time** (float) - Optional - Duration in seconds to apply volume changes.
- **intro** (string) - Optional - Name of an intro clip to play before the main loop.
```

--------------------------------

### Navigate to a Label

Source: https://naninovel.com/guide/scenario-scripting

Use the @goto command to jump to specific labels, optionally specifying the script path.

```nani
@goto ScriptPath#Epilogue
```

```nani
@goto #Epilogue
```

--------------------------------

### Display Background in Naninovel Script

Source: https://naninovel.com/guide/samples

Demonstrates how to display a background image using the @back command in a scenario script.

```naninovel
@back Snow
```

--------------------------------

### Initialize Engine with Transient State

Source: https://naninovel.com/guide/automated-testing

Sets up a clean engine state and initializes specific global variables for a test run.

```csharp
[UnityTest]
public IEnumerator WhenTrueCompleteTitleBackChanges () => new E2E()
    .WithTransientState(GlobalStateMap.With(
        new CustomVariableManager.GlobalState {
            GlobalVariables = new[] {
                new CustomVariable("g_completedX", CustomVariableScope.Global, new CustomVariableValue(true)),
                new CustomVariable("g_completedY", CustomVariableScope.Global, new CustomVariableValue(true))
            }
        }))
```

--------------------------------

### Navigate to Another Script

Source: https://naninovel.com/guide/getting-started

Uses the @goto command to redirect playback to a different scenario script.

```nani
@goto Test
```

--------------------------------

### Implementing a Custom Configuration Provider

Source: https://naninovel.com/guide/custom-configuration

Implement the IConfigurationProvider interface to define custom logic for how configuration objects are retrieved at runtime.

```csharp
public class CustomConfigurationProvider : IConfigurationProvider
{
    public Configuration GetConfiguration (System.Type type)
    {
        var defaultAsset = ScriptableObject.CreateInstance(type);
        return defaultAsset as Configuration;
    }
}
```

```csharp
public class CustomConfigurationProvider : ProjectConfigurationProvider
{
    public override Configuration GetConfiguration (System.Type type)
    {
        // Return project configs as-is for everything but characters.
        if (type != typeof(CharactersConfiguration))
            return base.GetConfiguration(type);
```

--------------------------------

### Prevent Asset Unloading with MonoBehaviour

Source: https://naninovel.com/guide/memory-management

A component example that holds an object indefinitely to prevent Naninovel from unloading it.

```csharp
using Naninovel;
using UnityEngine;

public class HoldObject : MonoBehaviour
{
    public Object ObjectToHold;

    private async void Start()
    {
        while (!Engine.Initialized) await Async.NextFrame();
        Engine.GetService<IResourceProviderManager>().Hold(ObjectToHold, this);
    }
}
```

--------------------------------

### Nested Command Blocks

Source: https://naninovel.com/guide/scenario-scripting

Demonstrates associating commands and text with a host command using 4-space indentation.

```nani
@if score>10
    @bgm Victory
    Good job, you've passed the test!
```

```nani
@if score>10
    Good job, you've passed the test!
    @bgm Victory
    @spawn Fireworks
@else if:attempts>100
    You're hopeless... Need help?
    @choice "Yeah, please!"
        @set score+=10
        @goto #BeginTest
    @choice "I'll keep trying."
        @goto #BeginTest
@else
    You've failed. Try again!
    @goto #BeginTest
```

--------------------------------

### Controlling Async Command Execution

Source: https://naninovel.com/guide/scenario-scripting

Demonstrates the default concurrent behavior of commands versus using the wait parameter to force sequential execution.

```nani
@hide Kohaku
@show Yuko
```

```nani
@hide Kohaku wait!
@show Yuko
```

--------------------------------

### Invoke BroadcastBoltEvent in Naninovel Script

Source: https://naninovel.com/guide/samples

Usage example for the custom bolt command within a Naninovel scenario script.

```nani
; Send "MyEvent" to "ExampleEvent" game object with the provided args
@bolt object:ExampleEvent name:MyEvent args:ExampleMessage,Script002
```

--------------------------------

### Using the Fullscreen Printer

Source: https://naninovel.com/guide/text-printers

Demonstrates activating the fullscreen printer, appending text, and manually resetting the printer content.

```nani
; Activate fullscreen printer.
@printer Fullscreen

; Following lines will be printed in the same window, separated by 2 breaks.
Lorem ipsum dolor sit amet. Proin ultricies in leo id scelerisque.
Praesent vel orci luctus, tincidunt nisi et, fringilla arcu. In a metus orci.
Maecenas congue nunc quis lectus porttitor, eget commodo massa congue.

; Clear contents of the printer.
@resetText

; Print more lines.
Morbi ultrices dictum diam, in gravida neque vulputate in.
...
```

--------------------------------

### New Game Test with Shortcuts

Source: https://naninovel.com/guide/automated-testing

A more concise version of the new game test using static imports from Naninovel.E2E.Shortcuts for improved readability.

```csharp
[UnityTest]
public IEnumerator CanStartGame () => new E2E().StartNew().Ensure(Playing);
```

--------------------------------

### Switching Cameras and Enabling Character Control

Source: https://naninovel.com/guide/integration-options

Demonstrates how to toggle between Naninovel and adventure cameras and restore character input control via C#.

```csharp
// 4. Switch cameras.
var advCamera = GameObject.Find("AdvCamera").GetComponent<Camera>();
advCamera.enabled = true;
var naniCamera = Engine.GetService<ICameraManager>().Camera;
naniCamera.enabled = false;

// 5. Enable character control.
var controller = Object.FindAnyObjectByType<CharacterController3D>();
controller.IsInputBlocked = false;
}
}
```

--------------------------------

### Define Command Parameters

Source: https://naninovel.com/guide/scenario-scripting

Syntax for providing key-value pairs to a command.

```nani
@commandId paramId:paramValue
```

--------------------------------

### Apply LineReveal Transition

Source: https://naninovel.com/guide/special-effects

Demonstrates applying the LineReveal transition with default, vertical slide, and reverse parameters.

```nani
; Apply the transition with default parameters
@back Appearance.LineReveal

; Apply the transition with a vertical line slide
@back Appearance.LineReveal params:,0,1

; Apply the transition in reverse (right to left)
@back Appearance.LineReveal params:,,,1
```

--------------------------------

### Defining a Custom Configuration Class

Source: https://naninovel.com/guide/custom-configuration

Create a new configuration by inheriting from the Configuration class and adding serializable fields.

```csharp
[EditInProjectSettings]
public class MyCustomConfiguration : Configuration
{
    [Header("My Custom Header 1")]
    [Tooltip("Tooltip for my custom string.")]
    public string MyCustomString = "Default value";
    [Range(0, 100), Tooltip("Tooltip for my custom float.")]
    public float MyCustomFloat = 10;

    [Header("My Custom Header 2")]
    public int[] MyCustomArray;
}
```

--------------------------------

### Accessing Configuration via Project Provider

Source: https://naninovel.com/guide/custom-configuration

Use ProjectConfigurationProvider.LoadOrDefault<T>() to access configuration assets directly, even before the engine is initialized.

```csharp
var config = ProjectConfigurationProvider.LoadOrDefault<AudioConfiguration>();
```

--------------------------------

### Safely Getting and Setting Custom Variables in C#

Source: https://naninovel.com/guide/custom-variables.html

Utilize the TryGetVariableValue and TrySetVariableValue methods for safer interaction with custom variables in C#. These methods handle type conversions and return success/failure status.

```csharp
var vars = Engine.GetService<ICustomVariableManager>();

vars.TryGetVariableValue<float>("MyFloatVarName", out var floatValue);
Debug.Log($
```

```csharp
My float variable value: {floatValue}

vars.TryGetVariableValue<int>("MyIntVarName", out var intValue);
Debug.Log($"My integer variable value: {intValue}")

vars.TryGetVariableValue<bool>("MyBoolVarName", out var boolValue);
Debug.Log($"My boolean variable value: {boolValue}")

floatValue += 10.5f;
vars.TrySetVariableValue("MyFloatVarName", floatValue);

intValue = -55;
vars.TrySetVariableValue("MyIntVarName", intValue);

boolValue = !boolValue;
vars.TrySetVariableValue("MyBoolVarName", boolValue);
```

--------------------------------

### Accessing Custom Variables in C#

Source: https://naninovel.com/guide/custom-variables.html

Use the ICustomVariableManager service to get and set custom variable values in C#. Remember to access the actual value using properties like .String, .Number, or .Boolean.

```csharp
var vars = Engine.GetService<ICustomVariableManager>();
var value = vars.GetVariableValue("MyVarName").String;
value += "Hello!";
vars.SetVariableValue("MyVarName", new(value));
```

--------------------------------

### Auto-complete Resources with ResourceContext

Source: https://naninovel.com/guide/ide-extension

Use the `ResourceContext` attribute with a path prefix to enable auto-completion for resources. Specify the resource type, such as audio, by providing the relevant configuration path prefix.

```csharp
[ResourceContext(AudioConfiguration.DefaultAudioPathPrefix)]
public StringParameter Audio;
```

--------------------------------

### Extend Choice Handler State in C#

Source: https://naninovel.com/guide/custom-actor-implementations

This example shows how to extend the `ChoiceHandlerState` to include custom serializable data like `LastChoiceTime`. It overrides `OverwriteFromActor` and `ApplyToActor` to manage the custom state during game saving and loading.

```csharp
// Our extended state that serializes the last choice time.
public class MyChoiceHandlerState : ChoiceHandlerState
{
    // This field is serializable and persists through game save-loads.
    public string LastChoiceTime;

    // This method is invoked when saving the game; get the required data
    // from the actor and store it with serializable fields.
    public override void OverwriteFromActor (IChoiceHandlerActor actor)
    {
        base.OverwriteFromActor(actor);
        if (actor is MyCustomChoiceHandler myCustomChoiceHandler)
            LastChoiceTime = myCustomChoiceHandler.LastChoiceTime;
    }

    // This method is invoked when loading the game;
    // get the serialized data back and apply it to the actor.
    public override void ApplyToActor (IChoiceHandlerActor actor)
    {
        base.ApplyToActor(actor);
        if (actor is MyCustomChoiceHandler myCustomChoiceHandler)
            myCustomChoiceHandler.LastChoiceTime = LastChoiceTime;
    }
}
```

--------------------------------

### Override Choice Handler Manager in C#

Source: https://naninovel.com/guide/custom-actor-implementations

This example demonstrates overriding the built-in `ChoiceHandlerManager` to use the custom `MyChoiceHandlerState`. The `[InitializeAtRuntime(@override: typeof(ChoiceHandlerManager))]` attribute ensures this manager replaces the default one. It also overrides `AddActor` to accept the custom state type.

```csharp
// Overriding built-in choice handler manager to make it use our extended state.
// The important step is to specify `MyChoiceHandlerState` in the generic types;
// other modifications are just to fulfill the interface requirements.
[InitializeAtRuntime(@override: typeof(ChoiceHandlerManager))]
public class MyChoiceHandlerManager : ActorManager<IChoiceHandlerActor, 
    MyChoiceHandlerState, ChoiceHandlerMetadata, 
    ChoiceHandlersConfiguration>, IChoiceHandlerManager
{
    public MyChoiceHandlerManager (ChoiceHandlersConfiguration config)
        : base(config) { }

    public Awaitable<IChoiceHandlerActor> AddActor (string actorId,
        ChoiceHandlerState state)
    {
        return base.AddActor(actorId, state as MyChoiceHandlerState);
    }

    ChoiceHandlerState IActorManager<IChoiceHandlerActor,
        ChoiceHandlerState, ChoiceHandlerMetadata,
        ChoiceHandlersConfiguration>.GetActorState (string actorId)
    {
        return base.GetActorState(actorId);
    }
}
```

--------------------------------

### Configure Info.txt for community localization

Source: https://naninovel.com/guide/localization

Specify the author and font name in the Info.txt file within the Localization directory.

```text
Awesome Author
Noto.ttf
```

--------------------------------

### Use Fast Forward Extension

Source: https://naninovel.com/guide/automated-testing

Applies common configuration settings for faster test execution using the WithFastForward extension.

```csharp
[UnityTest]
public IEnumerator Test () => new E2E().WithFastForward()
```

--------------------------------

### Modifying Configuration at Runtime

Source: https://naninovel.com/guide/custom-configuration

Demonstrates modifying a configuration property after engine initialization. Note that these changes affect runtime instances, not the original assets.

```csharp
using Naninovel;
using UnityEngine;

public static class ModifyConfigAtRuntime
{
    [RuntimeInitializeOnLoadMethod]
    private static void ModifyConfig ()
    {
        if (Engine.Initialized) OnInitializationFinished();
        else Engine.OnInitializationFinished += OnInitializationFinished;

        void OnInitializationFinished ()
        {
            Engine.OnInitializationFinished -= OnInitializationFinished;

            var cameraConfig = Engine.GetConfiguration<CameraConfiguration>();
            cameraConfig.ReferenceResolution = new Vector2Int(3840, 2160);
        }
    }
}
```

--------------------------------

### Control backgrounds with @back

Source: https://naninovel.com/guide/backgrounds

Use the @back command to set the appearance of the main background, optionally including a transition effect.

```nani
; Set "River" as the appearance of the main background
@back River

; Same as above, but also use a "RadialBlur" transition effect
@back River.RadialBlur
```

--------------------------------

### Spawn Object with Transform Parameters

Source: https://naninovel.com/guide/special-effects

Spawns an object at a specific position, scale, and rotation using the @spawn command.

```nani
; Spawn Explosion 15% from the left border of the screen
; with x10 scale and rotated by 15 degrees over z-axis.
@spawn Explosion pos:15 scale:10 rotation:,,15
```

--------------------------------

### Define basic choices

Source: https://naninovel.com/guide/choices

Use the @choice command to present options that continue the script or jump to specific labels or scripts.

```nani
; Print the text, then immediately show choices.
Continue executing this script or load another?[>]
@choice "Continue from the next line"
@choice "Continue from the specified label" goto:#Labelname
@choice "Load another from start" goto:AnotherScript
@choice "Load another from label" goto:AnotherScript#LabelName
```

--------------------------------

### List of Supported Easing Options

Source: https://naninovel.com/guide/special-effects

A list of available easing functions for commands that support time-based transitions.

```text
Linear
SmoothStep
Spring
EaseInQuad
EaseOutQuad
EaseInOutQuad
EaseInCubic
EaseOutCubic
EaseInOutCubic
EaseInQuart
EaseOutQuart
EaseInOutQuart
EaseInQuint
EaseOutQuint
EaseInOutQuint
EaseInSine
EaseOutSine
EaseInOutSine
EaseInExpo
EaseOutExpo
EaseInOutExpo
EaseInCirc
EaseOutCirc
EaseInOutCirc
EaseInBounce
EaseOutBounce
EaseInOutBounce
EaseInBack
EaseOutBack
EaseInOutBack
EaseInElastic
EaseOutElastic
EaseInOutElastic
```

--------------------------------

### Unlock Tips via Script

Source: https://naninovel.com/guide/unlockable-items

Use the @unlock command in a Naninovel script to make a tip record available to the player.

```nani
@unlock Tips/Tip1ID
```

--------------------------------

### Apply Background Poses

Source: https://naninovel.com/guide/backgrounds

Use named poses to apply multiple background parameters at once via the @back command.

```nani
; Given "Day" pose is defined for main background,
; applies all the selected parameters specified in the pose.
@back Day

; Same as above, but for a background actor with "City" ID
; and using "DropFade" transition over 3 seconds.
@back Day.DropFade id:City time:3
```

```nani
; Given "Day" pose is defined for main background,
; applies all the parameters specified in the pose state,
; except tint, which is overridden in the command.
@back Day tint:#ff45cb
```

--------------------------------

### Define a Label

Source: https://naninovel.com/guide/scenario-scripting

Use the # symbol to create an anchor point within a scenario script.

```nani
# Epilogue
```

--------------------------------

### Navigate with Wildcard Endpoints

Source: https://naninovel.com/guide/scenario-scripting

Use wildcard paths to reference script files without specifying full directory paths, provided the script name is unique.

```nani
; Navigate to the 'Prologue.nani' script, wherever it is located.
@goto */Prologue
; This will result in an error because there are multiple 'Scene1.nani' files.
@goto */Scene1
; This works because there is only one 'Scene1.nani' file under 'Day1' folder.
@goto */Day1/Scene1
```

--------------------------------

### Using ChatReply Choice Handler

Source: https://naninovel.com/guide/choices

Demonstrates how to use the ChatReply handler within a Naninovel script to present dialogue choices.

```nani
@printer Chat
Kohaku: Where're you right now?
@choice "Play dumb" handler:ChatReply
    Yuko: ¯\_(ツ)_/¯
@choice "Answer" handler:ChatReply
    Yuko: school. prepping for the festival
```

--------------------------------

### Manually Initialize Naninovel

Source: https://naninovel.com/guide/integration-options

Use this approach to initialize the engine from a MonoBehaviour script when automatic initialization is disabled.

```csharp
using Naninovel;
using UnityEngine;

public class MyScript : MonoBehaviour
{
    private async void Start ()
    {
        await RuntimeInitializer.Initialize();
    }
}
```

--------------------------------

### Access Engine API Safely

Source: https://naninovel.com/guide/integration-options

Check the initialization status or subscribe to the initialization event to ensure engine services are ready before use.

```csharp
public class MyScript : MonoBehaviour
{
    private void Awake ()
    {
        // Engine may not be initialized here, so check first.
        if (Engine.Initialized) DoMyCustomWork();
        else Engine.OnInitializationFinished += DoMyCustomWork;
    }

    private void DoMyCustomWork ()
    {
        // Engine is initialized here, it's safe to use the APIs.
        var scriptPlayer = Engine.GetService<IScriptPlayer>();
        ...
    }
}
```

--------------------------------

### Manage Inventory via Naninovel Script

Source: https://naninovel.com/guide/samples

Demonstrates using conditional logic, item checks, and inventory modification commands within a Naninovel script.

```naninovel
# Start

Select an action.[>]

@choice "Pick up sword" lock:itemExist("Sword")
    @addItem Sword
@choice "Pick up armor" lock:itemExist("Armor")
    @addItem Armor
@choice "Adventure awaits, venture forth!"

# Adventure

@if itemExist("Sword")
	@set monstersSlayed={ itemExist("Armor") ? random(3,5) : 2 }
	@addItem Food amount:{monstersSlayed}
	You've encountered and slayed {monstersSlayed} monsters with your sword.
	@goto #Start
@else
	But you don't have a weapon! You've been beaten by the monsters.
	@goto #Start
```

--------------------------------

### Encapsulating Tasks with Gosub

Source: https://naninovel.com/guide/scenario-scripting

Reuses complex animation logic by defining tasks in separate scripts and invoking them with @gosub.

```nani
@gosub FX#Quake
...
@stop Quake

@gosub FX#CameraPan
...
@await CameraPan
```

```nani
# Quake
@async Quake loop!
    @spawn Pebbles
    @shake Camera
    @wait { random(3, 10) }
@return

# CameraPan
@async CameraPan
    @bgm volume:0.7 fade:10
    @camera offset:4,1 zoom:0.5 time:3 wait!
    @bgm volume:0.3 fade:5
    @camera offset:,-2 zoom:0.4 time:2 wait!
    @stopBgm fade:10
    @camera offset:0,0 zoom:0 time:3 wait!
@return
```

--------------------------------

### Accessing Custom Configuration

Source: https://naninovel.com/guide/custom-configuration

Use the Engine.GetConfiguration method to retrieve a custom configuration asset at runtime.

```csharp
var myConfig = Engine.GetConfiguration<MyCustomConfiguration>();
```

--------------------------------

### Use custom choice button prefab

Source: https://naninovel.com/guide/choices

Specify a custom prefab for the choice button using the button parameter, which points to a path relative to a Resources folder.

```nani
@choice handler:ButtonArea button:Home pos:-300,-300 goto:#HomeScene
```

--------------------------------

### Implement localizable command

Source: https://naninovel.com/guide/custom-commands

Implement ILocalizable and use LocalizableTextParameter to support script localization.

```csharp
public class PrintText : Command, Command.ILocalizable
{
    public LocalizableTextParameter Text;
}
```

--------------------------------

### Spawn Effect with Parameters

Source: https://naninovel.com/guide/special-effects

Spawning a custom effect with additional parameters passed via the params argument.

```nani
@spawn Explosion params:Kohaku,3,true
```

--------------------------------

### Using math functions in commands

Source: https://naninovel.com/guide/script-expressions

Expressions can utilize UnityEngine.Mathf functions and operators within command parameters.

```nani
@char Kohaku scale:{pow(cos(33.5), 3) % log(0.5)}
```

--------------------------------

### Default Metadata Provider Implementation

Source: https://naninovel.com/guide/ide-extension

This C# code provides a reference implementation for the IMetadataProvider interface. Use it to understand how to fill or override default project metadata. Ensure the class has a parameterless constructor.

```csharp
public class DefaultMetadataProvider : IMetadataProvider
{
    public Project GetMetadata () 
    {
        var meta = new Project();
        var cfg = ProjectConfigurationProvider.LoadOrDefault<ScriptsConfiguration>();
        meta.EntryScript = cfg.StartGameScript;
        meta.TitleScript = cfg.TitleScript;
        Notify("Processing commands...", 0);
        meta.Commands = MetadataGenerator.GenerateCommandsMetadata();
        Notify("Processing resources...", .25f);
        meta.Resources = MetadataGenerator.GenerateResourcesMetadata();
        Notify("Processing actors...", .50f);
        meta.Actors = MetadataGenerator.GenerateActorsMetadata();
        Notify("Processing variables...", .75f);
        meta.Variables = MetadataGenerator.GenerateVariablesMetadata();
        Notify("Processing functions...", .95f);
        meta.Functions = MetadataGenerator.GenerateFunctionsMetadata();
        Notify("Processing constants...", .99f);
        meta.Constants = MetadataGenerator.GenerateConstantsMetadata();
        meta.Syntax = Compiler.Syntax;
        return meta;
    }

    private static void Notify (string info, float progress)
    {
        if (EditorUtility.DisplayCancelableProgressBar("Generating Metadata", info, progress))
            throw new OperationCanceledException("Metadata generation cancelled by the user.");
    }
}
```

--------------------------------

### Using Custom Select Functions in Scenarios

Source: https://naninovel.com/guide/text-printers

Shows how to invoke the custom select function within Naninovel scripts using different parameters.

```naninovel
; Select based on pronoun.
</p/his/her/their>

; Select based on temper.
</t/smiling/frowning/poker face>

; Select random.
<//green/red>
```
Tokens:
Raw