Commands

Script commands API reference. Use the side bar to quickly navigate between available commands.

Strikethrough indicates a nameless parameter, and bold stands for required parameter; other parameters should be considered optional. Consult naninovel scripts guide in case you have no idea what's this all about.

The following parameters are supported by most script commands:

Parameter	Type	Description
if	string	A boolean script expression, controlling whether the command should execute.
wait	boolean	Whether the script player should wait for the async command to finish execution before executing the next one.

animate

Animate properties of the actors with the specified IDs via key frames. Key frames for the animated parameters are delimited with commas.

NOTE

It's not recommended to use this command for complex animations. Naniscript is a scenario scripting DSL and not suited for complex automation or specification such as animation. Consider using dedicated animation tools instead, such as Unity's Animator ↗.

Be aware, that this command searches for actors with the specified IDs over all the actor managers, and in case multiple actors with the same ID exist (eg, a character and a text printer), this will affect only the first found one.

When running the animate commands in parallel (wait is set to false) the affected actors state can mutate unpredictably. This could cause unexpected results when rolling back or performing other commands that affect state of the actor. Make sure to reset affected properties of the animated actors (position, tint, appearance, etc) after the command finishes or use @animate CharacterId (without any args) to stop the animation prematurely.

Parameter	Type	Description
actorIds	string list	IDs of the actors to animate.
loop	boolean	Whether to loop the animation; make sure to set wait to false when loop is enabled, otherwise script playback will loop indefinitely.
appearance	string	Appearances to set for the animated actors.
transition	string	Type of the transition effect to use when animating appearance change (crossfade is used by default).
visibility	string	Visibility status to set for the animated actors.
posX	string	Position values over X-axis (in 0 to 100 range, in percents from the left border of the scene) to set for the animated actors.
posY	string	Position values over Y-axis (in 0 to 100 range, in percents from the bottom border of the scene) to set for the animated actors.
posZ	string	Position values over Z-axis (in world space) to set for the animated actors; while in ortho mode, can only be used for sorting.
rotation	string	Rotation values (over Z-axis) to set for the animated actors.
scale	string	Scale (x,y,z or a single uniform value) to set for the animated actors.
tint	string	The tint color to apply. Strings that begin with # will be parsed as hexadecimal in the following way: #RGB (becomes RRGGBB), #RRGGBB, #RGBA (becomes RRGGBBAA), #RRGGBBAA; when alpha is not specified will default to FF. Strings that do not begin with # will be parsed as literal colors, with the following supported: red, cyan, blue, darkblue, lightblue, purple, yellow, lime, fuchsia, white, silver, grey, black, orange, brown, maroon, green, olive, navy, teal, aqua, magenta.
easing	string	Name of the easing function to apply. When not specified, will use a default function set in the configuration.
time	string	Duration of the animations per key, in seconds. When a key value is missing, will use one from a previous key. Default is 0.35s for all keys.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Animate 'Kohaku' actor over three animation steps (key frames),
; changing positions: first step will take 1, second — 0.5 and third — 3 seconds.
@animate Kohaku posX:50,0,85 time:1,0.5,3 wait!

; Start loop animations of 'Yuko' and 'Kohaku' actors; notice, that you can skip
; key values indicating that the parameter shouldn't change during the animation step.
@animate Kohaku,Yuko loop! appearance:Surprise,Sad,Default,Angry transition:DropFade,Ripple,Pixelate posX:15,85,50 posY:0,-25,-85 scale:1,1.25,1.85 tint:#25f1f8,lightblue,#ffffff,olive easing:EaseInBounce,EaseInQuad time:3,2,1,0.5
...
; Stop the animations.
@animate Yuko,Kohaku !loop

; Start a long background animation for 'Kohaku'.
@animate Kohaku posX:90,0,90 scale:1,2,1 time:10
; Do something else while the animation is running.
...
; Here we're going to set a specific position for the character,
; but the animation could still be running in background, so reset it first.
@animate Kohaku
; Now it's safe to modify previously animated properties.
@char Kohaku pos:50 scale:1

append

Appends specified text to a text printer.

NOTE

The entire text is appended instantly, without triggering the reveal effect.

Parameter	Type	Description
text	string	The text to append.
printer	string	ID of the printer actor to use. Will use a default one when not specified.
author	string	ID of the actor, which should be associated with the appended text.

; Print first part of the sentence as usual (with gradual reveal),
; then append the end of the sentence at once.
Lorem ipsum
@append " dolor sit amet."

arrange

Arranges specified characters by X-axis. When no parameters specified, will execute an auto-arrange evenly distributing visible characters by X-axis.

Parameter	Type	Description
characterPositions	named decimal list	A collection of character ID to scene X-axis position (relative to the left scene border, in percents) named values. Position 0 relates to the left border and 100 to the right border of the scene; 50 is the center.
look	boolean	When performing auto-arrange, controls whether to also make the characters look at the scene origin (enabled by default).
time	decimal	Duration of the animation initiated by the command, in seconds.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Evenly distribute all the visible characters.
@arrange

; Place character with ID 'Jenna' 15%, 'Felix' 50% and 'Mia' 85% away
; from the left border of the scene.
@arrange Jenna.15,Felix.50,Mia.85

await

Holds script execution until all the nested async commands finished execution. Useful for grouping multiple async commands to wait until they all finish before proceeding with the script playback.

NOTE

The nested block is expected to always finish; don't nest any commands that could navigate outside the nested block, as this may cause undefined behaviour.

; Run nested lines in parallel and wait until they all are finished.
@await
    @back RainyScene
    @bgm RainAmbient
    @camera zoom:0.5 time:3
    @print "It starts Raining..." !waitInput
; Following line will execute after all the above is finished.
...

back

Modifies a background actor.

NOTE

Backgrounds are handled a bit differently from characters to better accommodate traditional VN game flow. Most of the time you'll probably have a single background actor on scene, which will constantly transition to different appearances. To remove the hassle of repeating same actor ID in scripts, it's possible to provide only the background appearance and transition type (optional) as a nameless parameter assuming MainBackground actor should be affected. When this is not the case, ID of the background actor can be explicitly specified via the id parameter.

Parameter	Type	Description
appearanceAndTransition	named string	Appearance (or pose) to set for the modified background and type of a transition effect to use. When transition is not specified, a cross-fade effect will be used by default.
pos	decimal list	Position (relative to the scene borders, in percents) to set for the modified actor. Position is described as follows: 0,0 is the bottom left, 50,50 is the center and 100,100 is the top right corner of the scene. Use Z-component (third member, eg ,,10) to move (sort) by depth while in ortho mode.
id	string	ID of the actor to modify; specify * to affect all visible actors.
appearance	string	Appearance to set for the modified actor.
pose	string	Pose to set for the modified actor.
transition	string	Type of the transition effect to use (crossfade is used by default).
params	decimal list	Parameters of the transition effect.
dissolve	string	Path to the custom dissolve texture (path should be relative to a Resources folder). Has effect only when the transition is set to Custom mode.
visible	boolean	Visibility status to set for the modified actor.
position	decimal list	Position (in world space) to set for the modified actor. Use Z-component (third member) to move (sort) by depth while in ortho mode.
rotation	decimal list	Rotation to set for the modified actor.
scale	decimal list	Scale to set for the modified actor.
tint	string	The tint color to apply. Strings that begin with # will be parsed as hexadecimal in the following way: #RGB (becomes RRGGBB), #RRGGBB, #RGBA (becomes RRGGBBAA), #RRGGBBAA; when alpha is not specified will default to FF. Strings that do not begin with # will be parsed as literal colors, with the following supported: red, cyan, blue, darkblue, lightblue, purple, yellow, lime, fuchsia, white, silver, grey, black, orange, brown, maroon, green, olive, navy, teal, aqua, magenta.
easing	string	Name of the easing function to apply. When not specified, will use a default function set in the configuration.
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Set 'River' as the appearance of the main background.
@back River

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

; Position 'Smoke' background at the center of the screen
; and scale it 50% of the original size.
@back id:Smoke pos:50,50 scale:0.5

; Tint all visible backgrounds on scene.
@back id:* tint:#ffdc22

bgm

Plays or modifies currently played BGM (background music) track with the specified name.

NOTE

Music tracks are looped by default. When music track name (BgmPath) is not specified, will affect all the currently played tracks. When invoked for a track that is already playing, the playback won't be affected (track won't start playing from the start), but the specified parameters (volume and whether the track is looped) will be applied.

Parameter	Type	Description
bgmPath	string	Path to the music track to play.
intro	string	Path to the intro music track to play once before the main track (not affected by the loop parameter).
volume	decimal	Volume of the music track.
loop	boolean	Whether to play the track from beginning when it finishes.
fade	decimal	Duration of the volume fade-in when starting playback, in seconds (0.0 by default); doesn't have effect when modifying a playing track.
group	string	Audio mixer group path ↗ that should be used when playing the audio.
time	decimal	Duration (in seconds) of the modification.
wait	boolean	Whether to wait for the BGM fade animation to finish before playing next command.

; 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 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

; Plays 'BattleThemeIntro' once, then loops 'BattleThemeMain'.
@bgm BattleThemeMain intro:BattleThemeIntro

blur

Applies blur effect to supported actor: backgrounds and characters of sprite, layered, diced, Live2D, Spine, video and scene implementations.

NOTE

The actor should have IBlurable interface implemented in order to support the effect.

Parameter	Type	Description
actorId	string	ID of the actor to apply the effect for; in case multiple actors with the same ID found (eg, a character and a printer), will affect only the first found one. When not specified, applies to the main background.
power	decimal	Intensity of the effect, in 0.0 to 1.0 range. Defaults to 0.5. Set to 0 to disable (de-spawn) the effect.
time	decimal	How long it will take the parameters to reach the target values, in seconds. Defaults to 1.0.
wait	boolean	Whether to wait for the effect warm-up animation before playing next command.

; Blur main background with default parameters.
@blur
; Remove blur from the main background.
@blur power:0

; Blur 'Kohaku' actor with max power over 5 seconds.
@blur Kohaku power:1 time:5
; Remove blur from 'Kohaku' over 3.1 seconds.
@blur Kohaku power:0 time:3.1

bokeh

Simulates depth of field (aka DOF, bokeh) effect, when only the object in focus stays sharp, while others are blurred.

Parameter	Type	Description
focus	string	Name of the game object to set focus for (optional). When set, the focus will always stay on the game object, while dist parameter will be ignored.
dist	decimal	Distance (in units) from Naninovel camera to the focus point. Ignored when focus parameter is specified. Defaults to 10.
power	decimal	Amount of blur to apply for the de-focused areas; also determines focus sensitivity. Defaults to 3.75. Set to 0 to disable (de-spawn) the effect.
time	decimal	How long it will take the parameters to reach the target values, in seconds. Defaults to 1.0.
wait	boolean	Whether to wait for the effect warm-up animation before playing next command.

; Enable the effect with defaults and lock focus on 'Kohaku' game object.
@bokeh focus:Kohaku
; Fade-off (disable) the effect over 10 seconds.
@bokeh power:0 time:10
; Set focus point 10 units away from the camera,
; focal distance to 0.95 and apply it over 3 seconds.
@bokeh dist:10 power:0.95 time:3

camera

Modifies the main camera, changing offset, zoom level and rotation over time. Check this video ↗ for a quick demonstration of the command effect.

Parameter	Type	Description
offset	decimal list	Local camera position offset in units by X,Y,Z axes.
roll	decimal	Local camera rotation by Z-axis in angle degrees (0.0 to 360.0 or -180.0 to 180.0). The same as third component of rotation parameter; ignored when rotation is specified.
rotation	decimal list	Local camera rotation over X,Y,Z-axes in angle degrees (0.0 to 360.0 or -180.0 to 180.0).
zoom	decimal	Relative camera zoom (orthographic size or field of view, depending on the render mode), in 0.0 (no zoom) to 1.0 (full zoom) range.
ortho	boolean	Whether the camera should render in orthographic (true) or perspective (false) mode.
toggle	string list	Names of the components to toggle (enable if disabled and vice-versa). The components should be attached to the same game object as the camera. This can be used to toggle custom post-processing effects. Use * to affect all the components attached to the camera object.
set	named boolean list	Names of the components to enable or disable. The components should be attached to the same game object as the camera. This can be used to explicitly enable or disable custom post-processing effects. Specified components enabled state will override effect of toggle parameter. Use * to affect all the components attached to the camera object.
easing	string	Name of the easing function to apply. When not specified, will use a default function set in the configuration.
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Offset the camera by -3 units over X-axis and by 1.5 units Y-axis.
@camera offset:-3,1.5

; Set camera in perspective mode, zoom-in by 50% and move back by 5 units.
@camera !ortho offset:,,-5 zoom:0.5

; Set camera in orthographic mode and roll by 10 degrees clock-wise.
@camera ortho! roll:10

; Offset, zoom and roll simultaneously animated over 5 seconds.
@camera offset:-3,1.5 zoom:0.5 roll:10 time:5

; Instantly reset camera to the default state.
@camera offset:0,0 zoom:0 rotation:0,0,0 time:0

; Toggle 'FancyCameraFilter' and 'Bloom' components attached to the camera.
@camera toggle:FancyCameraFilter,Bloom

; Set 'FancyCameraFilter' component enabled and 'Bloom' disabled.
@camera set:FancyCameraFilter.true,Bloom.false

; Disable all components attached to the camera object.
@camera set:*.false

char

Modifies a character actor.

Parameter	Type	Description
idAndAppearance	named string	ID of the character to modify (specify * to affect all visible characters) and an appearance (or pose) to set. When appearance is not specified, will use either a Default (is exists) or a random one.
look	string	Look direction of the actor; supported values: left, right, center.
avatar	string	Name (path) of the avatar texture to assign for the character. Use none to remove (un-assign) avatar texture from the character.
pos	decimal list	Position (relative to the scene borders, in percents) to set for the modified actor. Position is described as follows: 0,0 is the bottom left, 50,50 is the center and 100,100 is the top right corner of the scene. Use Z-component (third member, eg ,,10) to move (sort) by depth while in ortho mode.
id	string	ID of the actor to modify; specify * to affect all visible actors.
appearance	string	Appearance to set for the modified actor.
pose	string	Pose to set for the modified actor.
transition	string	Type of the transition effect to use (crossfade is used by default).
params	decimal list	Parameters of the transition effect.
dissolve	string	Path to the custom dissolve texture (path should be relative to a Resources folder). Has effect only when the transition is set to Custom mode.
visible	boolean	Visibility status to set for the modified actor.
position	decimal list	Position (in world space) to set for the modified actor. Use Z-component (third member) to move (sort) by depth while in ortho mode.
rotation	decimal list	Rotation to set for the modified actor.
scale	decimal list	Scale to set for the modified actor.
tint	string	The tint color to apply. Strings that begin with # will be parsed as hexadecimal in the following way: #RGB (becomes RRGGBB), #RRGGBB, #RGBA (becomes RRGGBBAA), #RRGGBBAA; when alpha is not specified will default to FF. Strings that do not begin with # will be parsed as literal colors, with the following supported: red, cyan, blue, darkblue, lightblue, purple, yellow, lime, fuchsia, white, silver, grey, black, orange, brown, maroon, green, olive, navy, teal, aqua, magenta.
easing	string	Name of the easing function to apply. When not specified, will use a default function set in the configuration.
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Shows character with ID 'Sora' with a default appearance.
@char Sora

; Same as above, but sets appearance to 'Happy'.
@char Sora.Happy

; Same as above, but additionally positions the character 45% away 
; from the left border of the scene and 10% away from the bottom border; 
; also makes it look to the left.
@char Sora.Happy look:left pos:45,10

; Make Sora appear at the bottom-center and in front of Felix.
@char Sora pos:50,0,-1
@char Felix pos:,,0

; Tint all visible characters on scene.
@char * tint:#ffdc22

choice

Adds a choice option to a choice handler with the specified ID (or default one).

NOTE

When nesting commands under the choice, goto, gosub, set and play parameters are ignored.

Parameter	Type	Description
choiceSummary	string	Text to show for the choice. When the text contain spaces, wrap it in double quotes ("). In case you wish to include the double quotes in the text itself, escape them.
lock	boolean	Whether the choice should be disabled or otherwise not accessible for player to pick; see choice docs for more info. Disabled by default.
button	string	Path (relative to a Resources folder) to a button prefab representing the choice. The prefab should have a ChoiceHandlerButton component attached to the root object. Will use a default button when not specified.
pos	decimal list	Local position of the choice button inside the choice handler (if supported by the handler implementation).
handler	string	ID of the choice handler to add choice for. Will use a default handler if not specified.
goto	named string	Path to go when the choice is selected by user; see @goto command for the path format. Ignored when nesting commands under the choice.
gosub	named string	Path to a subroutine to go when the choice is selected by user; see @gosub command for the path format. When goto is assigned this parameter will be ignored. Ignored when nesting commands under the choice.
set	string	Set expression to execute when the choice is selected by user; see @set command for syntax reference. Ignored when nesting commands under the choice.
play	boolean	Whether to automatically continue playing script from the next line, when neither goto nor gosub parameters are specified. Has no effect in case the script is already playing when the choice is processed. Ignored when nesting commands under the choice.
show	boolean	Whether to also show choice handler the choice is added for; enabled by default.
time	decimal	Duration (in seconds) of the fade-in (reveal) animation.

; Print the text, then immediately show choices and stop script execution.
Continue executing this script or ...?[< skip!]
@choice "Continue"
@choice "Load another script from start" goto:Another
@choice "Load another script from \"Label\" label" goto:Another.Label
@choice "Goto to \"Sub\" subroutine in another script" gosub:Another.Sub
@stop

; You can also set custom variables based on choices.
@choice "I'm humble, one is enough..." set:score++
@choice "Two, please." set:score=score+2
@choice "I'll take the entire stock!" set:karma--;score=999

; Play a sound effect and arrange characters when choice is picked.
@choice Arrange
    @sfx Click
    @arrange k.10,y.55

; Print a text line corresponding to the picked choice.
@choice "Ask about color"
    What's your favorite color?
@choice "Ask about age"
    How old are you?
@choice "Keep silent"
    ...
@stop

; Make choice disabled/locked when 'score' variable is below 10.
@choice "Secret option" lock:{score<10}

clearBacklog

Removes all the messages from printer backlog.

; Printed text will be removed from the backlog.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
@clearBacklog

clearChoice

Removes all the choice options in the choice handler with the specified ID (or in default one, when ID is not specified; or in all the existing handlers, when * is specified as ID) and (optionally) hides it (them).

Parameter	Type	Description
handlerId	string	ID of the choice handler to clear. Will use a default handler if not specified. Specify * to clear all the existing handlers.
hide	boolean	Whether to also hide the affected choice handlers.

; Give the player 2 seconds to pick a choice.
# Start
You have 2 seconds to respond![< skip!]
@choice Cats goto:.PickedChoice
@choice Dogs goto:.PickedChoice
@wait 2
@clearChoice
Too late!
@stop
# PickedChoice
Good!

delay

Delays execution of the nested commands for specified time interval.

NOTE

Be aware, that the delayed execution won't happen if game gets saved/loaded or rolled-back. It's fine to use delayed execution for "cosmetic" events, such as one-shot visual or audio effects, but don't delay commands, which could affect persistent game state, as this could lead to undefined behaviour.

Parameter	Type	Description
seconds	decimal	Delay time, in seconds.

; The text is printed without delay, as the '@delay' command is not awaited.
; The Thunder effects are played after a random delay of 3 to 8 seconds.
@delay {random(3,8)}
    @sfx Thunder
    @shake Camera
The Thunder might go off any second...

despawn

Destroys an object spawned with @spawn command.

NOTE

If prefab has a MonoBehaviour component attached the root object, and the component implements a IParameterized interface, will pass the specified params values before destroying the object; if the component implements IAwaitable interface, command execution will wait for the async completion task returned by the implementation before destroying the object.

Parameter	Type	Description
path	string	Name (path) of the prefab resource to destroy. A @spawn command with the same parameter is expected to be executed before.
params	string list	Parameters to set before destroying the prefab. Requires the prefab to have a IParameterized component attached the root object.
wait	boolean	Whether to wait while the spawn is destroying over time in case it implements IAwaitable interface.

; Given '@spawn Rainbow' command was executed before, de-spawn (destroy) it.
@despawn Rainbow

despawnAll

Destroys all the objects spawned with @spawn command. Equal to invoking @despawn for all the currently spawned objects.

Parameter	Type	Description
wait	boolean	Whether to wait while the spawns are destroying over time in case they implements IAwaitable interface.

@spawn Rainbow
@spawn SunShafts
; Will de-spawn (destroy) both Rainbow and SunShafts.
@despawnAll

else

Marks a branch of a conditional execution block, which is executed in case condition of the opening @if and preceding @else (if any) commands are not met. For usage examples see conditional execution guide.

endIf

Alternative to using indentation in conditional blocks: marks end of the block opened with previous @if command, no matter the indentation. For usage examples see conditional execution guide.

format

Assigns formatting templates to be applied for printed messages.

NOTE

You can also format printed text with style tags.

Parameter	Type	Description
templates	named string list	The templates to apply, in Template.AuthorFilter format; see the formatting templates guide for more info.
printer	string	ID of the printer actor to assign templates for. Will use a default one when not specified.

; Print first two sentences in bold red text with 45px size,
; then reset the style and print the last sentence using default style.
@format <color=#ff0000><b><size=45>%TEXT%</size></b></color>
Lorem ipsum dolor sit amet.
Cras ut nisi eget ex viverra egestas in nec magna.
@format default
Consectetur adipiscing elit.

; Instead of using the @format command, it's possible to apply the styles
; to the printed text directly.
Lorem ipsum sit amet. <b>Consectetur adipiscing elit.</b>

glitch

Applies digital glitch post-processing effect to the main camera simulating digital video distortion and artifacts.

Parameter	Type	Description
time	decimal	The duration of the effect, in seconds; default is 1.
power	decimal	The intensity of the effect, in 0.0 to 10.0 range; default is 1.
wait	boolean	Whether to wait for the effect warm-up animation before playing next command.

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

gosub

Navigates naninovel script playback to the specified path and saves that path to global state; @return commands use this info to redirect to command after the last invoked gosub command.

NOTE

While this command can be used as a function (subroutine) to invoke a common set of script lines, remember that NaniScript is a scenario scripting DSL and is not suited for general programming. It's strongly recommended to use custom commands instead.

Parameter	Type	Description
path	named string	Path to navigate into in the following format: ScriptPath.Label. When label is omitted, will play specified script from the start. When script path is omitted, will attempt to find a label in the currently played script.
reset	string list	When specified, will reset the engine services state before loading a script (in case the path is leading to another script). Specify * to reset all the services, or specify service names to exclude from reset. By default, the state does not reset.

; Navigate to 'VictoryScene' label in the currently played script, then
; execute the commands and navigate back to the command after the 'gosub'.
@gosub .VictoryScene
...
@stop
# VictoryScene
@back Victory
@sfx Fireworks
@bgm Fanfares
You are victorious!
@return

; Another example with some branching inside the subroutine.
@set time=10
; Here we get one result.
@gosub .Room
...
@set time=3
; And here we get another.
@gosub .Room
@stop
# Room
@print "It's too early, I should visit after sunset." if:time<21&time>6
@print "I can sense an ominous presence!" if:time>21|time<6
@return

goto

Navigates naninovel script playback to the specified path.

Parameter	Type	Description
path	named string	Path to navigate into in the following format: ScriptPath.Label. When label is omitted, will play specified script from the start. When script path is omitted, will attempt to find a label in the currently played script.
reset	string list	When specified, will control whether to reset the engine services state before loading a script (in case the path is leading to another script): - Specify * to reset all the services, except the ones with Goto.DontReset attribute. - Specify service type names (separated by comma) to exclude from reset; all the other services will be reset, including the ones with Goto.DontReset attribute. - Specify - to force no reset (even if it's enabled by default in the configuration). Notice, that while some services have Goto.DontReset attribute applied and are not reset by default, they should still be specified when excluding specific services from reset.
hold	boolean	Whether to hold resources in the target script, which make them preload together with the script this command specified in. Has no effect outside Conservative resource policy. Refer to memory management guide for more info.
release	boolean	Whether to release resources before navigating to the target script to free the memory. Has no effect outside Optimistic resource policy. Refer to memory management guide for more info.

; Loads and starts playing 'Script001' script from the start.
@goto Script001

; Save as above, but start playing from the label 'AfterStorm'.
@goto Script001.AfterStorm

; Navigates to 'Epilogue' label in the currently played script.
@goto .Epilogue
...
# Epilogue
...

group

Allows grouping commands inside nested block.

; Random command chooses one of the nested lines, but ignores children
; of its nested lines. Group command used here to group multiple lines,
; so that random command will actually execute multiple lines.
@random
    @group
        @back tint:red
        Paint it red.
    @group
        @back tint:black
        Paint it black.

hide

Hides actors (character, background, text printer, choice handler) with the specified IDs. In case multiple actors with the same ID found (eg, a character and a printer), will affect only the first found one.

Parameter	Type	Description
actorIds	string list	IDs of the actors to hide.
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Given an actor with ID 'Smoke' is visible, hide it over 3 seconds.
@hide Smoke time:3

; Hide 'Kohaku' and 'Yuko' actors.
@hide Kohaku,Yuko

hideAll

Hides all the actors (characters, backgrounds, text printers, choice handlers) on scene.

Parameter	Type	Description
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Hide all the visible actors (chars, backs, printers, etc) on scene.
@hideAll

hideChars

Hides all the visible characters on scene.

Parameter	Type	Description
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Hide all the visible character actors on scene.
@hideChars

hidePrinter

Hides a text printer.

Parameter	Type	Description
printerId	string	ID of the printer actor to use. Will use a default one when not specified.
time	decimal	Duration of the animation initiated by the command, in seconds.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Hide a default printer.
@hidePrinter

; Hide printer with ID 'Wide'.
@hidePrinter Wide

hideUI

Makes UI elements with the specified names invisible. When no names are specified, will stop rendering (hide) the entire UI (including all the built-in UIs).

NOTE

When hiding the entire UI with this command and allowToggle parameter is false (default), user won't be able to re-show the UI back with hotkeys or by clicking anywhere on the screen; use @showUI command to make the UI visible again.

Parameter	Type	Description
uINames	string list	Name of the UI elements to hide.
allowToggle	boolean	When hiding the entire UI, controls whether to allow the user to re-show the UI with hotkeys or by clicking anywhere on the screen (false by default). Has no effect when hiding a particular UI.
time	decimal	Duration (in seconds) of the hide animation. When not specified, will use UI-specific duration.
wait	boolean	Whether to wait for the UI fade-out animation before playing next command.

; Given a custom 'Calendar' UI, the following command will hide it.
@hideUI Calendar

; Hide the entire UI, won't allow user to re-show it.
@hideUI
...
; Make the UI visible again.
@showUI

; Hide the entire UI, but allow the user to toggle it back.
@hideUI allowToggle!

; Simultaneously hide built-in 'TipsUI' and custom 'Calendar' UIs.
@hideUI TipsUI,Calendar

i

Holds script execution until user activates a continue input. Shortcut for @wait i.

; User will have to activate a 'continue' input after the first sentence
; for the printer to continue printing out the following text.
Lorem ipsum dolor sit amet.[i] Consectetur adipiscing elit.

if

Marks the beginning of a conditional execution block. Nested lines are considered body of the block and will be executed only in case the conditional nameless parameter is evaluated to true. See conditional execution guide for more info.

Parameter	Type	Description
expression	string	A script expression, which should return a boolean value determining whether the associated nested block will be executed.

; Print text line(s) depending on "score" variable:
;   "You've failed. Try again!" - when score is below 6.
;   "You've passed the test." and "Brilliant!" - when score is above 8.
;   "You've passed the test." and "Impressive!" - when score is above 7.
;   "You've passed the test." and "Good job!" - otherwise.
@if score>6
    You've passed the test.
    @if score>8
        Brilliant!
    @else if:score>7
        Impressive!
    @else
        Good job!
@else
    You've failed. Try again!

; Print text line depending on "score" variable:
;   "Test result: Failed." - when score is below 6.
;   "Test result: Perfect!" - when score is above above 8.
;   "Test result: Passed." - otherwise.
Test result:[if score>8] Perfect![else if:score>6] Passed.[else] Failed.[endif]

input

Shows an input field UI where user can enter an arbitrary text. Upon submit the entered text will be assigned to the specified custom variable.

NOTE

To assign a display name for a character using this command consider binding the name to a custom variable.

Parameter	Type	Description
variableName	string	Name of a custom variable to which the entered text will be assigned.
type	string	Type of the input content; defaults to the specified variable type.
summary	string	An optional summary text to show along with input field.When the text contain spaces, wrap it in double quotes ("). In case you wish to include the double quotes in the text itself, escape them.
value	string	A predefined value to set for the input field.
play	boolean	Whether to automatically resume script playback when user submits the input form.

; Prompt to enter an arbitrary text and assign it to 'name' custom variable.
@input name summary:"Choose your name."
; Halt the playback until player submits the input.
@stop

; You can then inject the assigned 'name' variable in naninovel scripts.
Archibald: Greetings, {name}!

; ...or use it inside set and conditional expressions.
@set score=score+1 if:name=="Felix"

lipSync

Allows to force-stop the lip sync mouth animation for a character with the specified ID; when stopped, the animation won't start again, until this command is used again to allow it. The character should be able to receive the lip sync events (currently generic, layered and Live2D implementations only). See characters guide for more information on lip sync feature.

Parameter	Type	Description
charIdAndAllow	named boolean	Character ID followed by a boolean (true or false) on whether to halt or allow the lip sync animation.

; Given auto voicing is disabled and lip sync is driven by text messages,
; exclude punctuation from the mouth animation.
Kohaku: Lorem ipsum dolor sit amet[lipSync Kohaku.false]... [lipSync Kohaku.true]Consectetur adipiscing elit.

loadScene

Loads a Unity scene ↗ with the specified name. Don't forget to add the required scenes to the build settings ↗ to make them available for loading.

Parameter	Type	Description
sceneName	string	Name of the scene to load.
additive	boolean	Whether to load the scene additively, or unload any currently loaded scenes before loading the new one (default). See the load scene documentation ↗ for more information.

; Load scene 'TestScene1' in single mode.
@loadScene TestScene1

; Load scene 'TestScene2' in additive mode.
@loadScene TestScene2 additive!

lock

Sets an unlockable item with the specified ID to locked state.

NOTE

The unlocked state of the items is stored in global scope.
In case item with the specified ID is not registered in the global state map, the corresponding record will automatically be added.

Parameter	Type	Description
id	string	ID of the unlockable item. Use * to lock all the registered unlockable items.

; Lock an unlockable CG record with ID 'FightScene1'.
@lock CG/FightScene1

look

Activates/disables camera look mode, when player can offset the main camera with input devices (eg, by moving a mouse or using gamepad analog stick). Check this video ↗ for a quick demonstration of the command.

Parameter	Type	Description
enable	boolean	Whether to enable or disable the camera look mode. Default: true.
zone	decimal list	A bound box with X,Y sizes in units from the initial camera position, describing how far the camera can be moved. Default: 5,3.
speed	decimal list	Camera movement speed (sensitivity) by X,Y axes. Default: 1.5,1.
gravity	boolean	Whether to automatically move camera to the initial position when the look input is not active (eg, mouse is not moving or analog stick is in default position). Default: false.

; Activate camera look mode with default parameters.
@look

; Activate camera look mode with custom parameters.
@look zone:6.5,4 speed:3,2.5 gravity!

; Disable look mode and instantly reset the offset.
@look false

; Disable look, but reset gradually, with 0.25 speed.
@look false gravity! speed:0.25

movie

Plays a movie with the specified name (path).

NOTE

Will fade-out the screen before playing the movie and fade back in after the play. Playback can be canceled by activating a cancel input (Esc key by default).

Parameter	Type	Description
movieName	string	Name of the movie resource to play.
time	decimal	Duration (in seconds) of the fade animation. When not specified, will use fade duration set in the movie configuration.
block	boolean	Whether to block interaction with the game while the movie is playing, preventing the player from skipping it.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Given an 'Opening' video clip is added to the movie resources, plays it.
@movie Opening

openURL

Opens specified URL (web address) with default web browser.

NOTE

When outside of WebGL or in editor, Unity's Application.OpenURL method is used to handle the command; consult the documentation ↗ for behaviour details and limitations. Under WebGL native window.open() JS function is invoked: https://developer.mozilla.org/en-US/docs/Web/API/Window/open ↗.

Parameter	Type	Description
uRL	string	URL to open.
target	string	Browsing context: _self (current tab), _blank (new tab), _parent, _top.

; Open blank page in the current tab.
@openURL "about:blank"

; Open Naninovel website in new tab.
@openURL "https://naninovel.com" target:_blank

print

Prints (reveals over time) specified text message using a text printer actor.

NOTE

This command is used under the hood when processing generic text lines, eg generic line Kohaku: Hello World! will be automatically transformed into @print "Hello World!" author:Kohaku when parsing the naninovel scripts.
Will reset (clear) the printer before printing the new message by default; set reset parameter to false or disable Auto Reset in the printer actor configuration to prevent that and append the text instead.
Will make the printer default and hide other printers by default; set default parameter to false or disable Auto Default in the printer actor configuration to prevent that.
Will wait for user input before finishing the task by default; set waitInput parameter to false or disable Auto Wait in the printer actor configuration to return as soon as the text is fully revealed.

Parameter	Type	Description
text	string	Text of the message to print. When the text contain spaces, wrap it in double quotes ("). In case you wish to include the double quotes in the text itself, escape them.
printer	string	ID of the printer actor to use. Will use a default one when not specified.
author	string	ID of the actor, which should be associated with the printed message. Ignored when appending. Specify * or use , to delimit multiple actor IDs to make all/selected characters authors of the text; useful when coupled with as parameter to represent multiple characters speaking at the same time.
as	string	When specified, will use the label instead of author ID (or associated display name) to represent author name in the text printer while printing the message. Useful to override default name for a few messages or represent multiple authors speaking at the same time without triggering author-specific behaviour of the text printer, such as message color or avatar.
speed	decimal	Text reveal speed multiplier; should be positive or zero. Setting to one will yield the default speed.
reset	boolean	Whether to reset text of the printer before executing the printing task. Default value is controlled via Auto Reset property in the printer actor configuration menu.
default	boolean	Whether to make the printer default and hide other printers before executing the printing task. Default value is controlled via Auto Default property in the printer actor configuration menu.
waitInput	boolean	Whether to wait for user input after finishing the printing task. Default value is controlled via Auto Wait property in the printer actor configuration menu.
append	boolean	Whether to append the printed text to the last printer message.
fadeTime	decimal	Controls duration (in seconds) of the printers show and hide animations associated with this command. Default value for each printer is set in the actor configuration.
wait	boolean	Whether to await the text reveal and prompt for completion (wait for input) before playing next command.

; Will print the phrase with a default printer.
@print "Lorem ipsum dolor sit amet."

; To include quotes in the text itself, escape them.
@print "Shouting \"Stop the car!\" was a mistake."

; Reveal message with half of the normal speed and
; don't wait for user input to continue.
@print "Lorem ipsum dolor sit amet." speed:0.5 !waitInput

; Print the line with "Together" displayed as author name and
; make all visible characters author of the printed text.
@print "Hello World!" author:* as:"Together"

; Similar, but make only "Kohaku" and "Yuko" the authors.
@print "Hello World!" author:Kohaku,Yuko as:"Kohaku and Yuko"

printer

Modifies a text printer actor.

Parameter	Type	Description
idAndAppearance	named string	ID of the printer to modify and the appearance to set. When ID or appearance are not specified, will use default ones.
default	boolean	Whether to make the printer the default one. Default printer will be subject of all the printer-related commands when printer parameter is not specified.
hideOther	boolean	Whether to hide all the other printers.
pos	decimal list	Position (relative to the scene borders, in percents) to set for the modified actor. Position is described as follows: 0,0 is the bottom left, 50,50 is the center and 100,100 is the top right corner of the scene. Use Z-component (third member, eg ,,10) to move (sort) by depth while in ortho mode.
id	string	ID of the actor to modify; specify * to affect all visible actors.
appearance	string	Appearance to set for the modified actor.
pose	string	Pose to set for the modified actor.
transition	string	Type of the transition effect to use (crossfade is used by default).
params	decimal list	Parameters of the transition effect.
dissolve	string	Path to the custom dissolve texture (path should be relative to a Resources folder). Has effect only when the transition is set to Custom mode.
visible	boolean	Visibility status to set for the modified actor.
position	decimal list	Position (in world space) to set for the modified actor. Use Z-component (third member) to move (sort) by depth while in ortho mode.
rotation	decimal list	Rotation to set for the modified actor.
scale	decimal list	Scale to set for the modified actor.
tint	string	The tint color to apply. Strings that begin with # will be parsed as hexadecimal in the following way: #RGB (becomes RRGGBB), #RRGGBB, #RGBA (becomes RRGGBBAA), #RRGGBBAA; when alpha is not specified will default to FF. Strings that do not begin with # will be parsed as literal colors, with the following supported: red, cyan, blue, darkblue, lightblue, purple, yellow, lime, fuchsia, white, silver, grey, black, orange, brown, maroon, green, olive, navy, teal, aqua, magenta.
easing	string	Name of the easing function to apply. When not specified, will use a default function set in the configuration.
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Will make 'Wide' printer default and hide any other visible printers.
@printer Wide

; Will assign 'Right' appearance to 'Bubble' printer, make is default,
; position at the center of the scene and won't hide other printers.
@printer Bubble.Right pos:50,50 !hideOther

processInput

Allows halting and resuming user input processing (eg, reacting to pressing keyboard keys). The effect of the action is persistent and saved with the game.

Parameter	Type	Description
inputEnabled	boolean	Whether to enable input processing of all the samplers.
set	named boolean list	Allows muting and un-muting individual input samplers.

; Halt input processing of all the samplers.
@processInput false

; Resume input processing of all the samplers.
@processInput true

; Mute 'Rollback' and 'Pause' inputs and un-mute 'Continue' input.
@processInput set:Rollback.false,Pause.false,Continue.true

purgeRollback

Prevents player from rolling back to the previous state snapshots.

; Prevent player from rolling back to try picking another choice.

Pick a choice. You won't be able to rollback.
@choice One goto:.One
@choice Two goto:.Two
@stop

# One
@purgeRollback
You've picked one.
@stop

# Two
@purgeRollback
You've picked two.
@stop

rain

Spawns particle system simulating rain.

Parameter	Type	Description
power	decimal	The intensity of the rain (particles spawn rate per second); defaults to 500. Set to 0 to disable (de-spawn) the effect.
time	decimal	The particle system will gradually grow the spawn rate to the target level over the specified time, in seconds.
xSpeed	decimal	Multiplier to the horizontal speed of the particles. Use to change angle of the rain drops.
ySpeed	decimal	Multiplier to the vertical speed of the particles.
pos	decimal list	Position (relative to the scene borders, in percents) to set for the spawned effect game object. Position is described as follows: 0,0 is the bottom left, 50,50 is the center and 100,100 is the top right corner of the scene. Use Z-component (third member, eg ,,10) to move (sort) by depth while in ortho mode.
position	decimal list	Position (in world space) to set for the spawned effect game object.
rotation	decimal list	Rotation to set for the spawned effect game object.
scale	decimal list	Scale to set for the spawned effect game object.
wait	boolean	Whether to wait for the effect warm-up animation before playing next command.

; Start intensive Rain over 10 seconds.
@Rain power:1500 time:10
; Stop the Rain over 30 seconds.
@Rain power:0 time:30

random

Executes one of the nested commands, picked randomly.

Parameter	Type	Description
weight	decimal list	Customized probability for the nested commands, in 0.0 to 1.0 range. By default all the commands have equal probability of being picked.

; Play one of 3 sounds with equal probability.
@random
    @sfx Sound1
    @sfx Sound2
    @sfx Sound3

; Play 2nd sound with 80% probability or 1st/3rd with 10% each.
@random weight:0.1,0.8,0.1
    @sfx Sound1
    @sfx Sound2
    @sfx Sound3

; Add a choice to shake camera, tint Kohaku actor or play 'SoundX' SFX,
; all with 33% probability. However, SFX playback will only be considered
; in case score is above 10.
@random
    @choice "Shake camera!"
        You've asked for it!
        @shake Camera
    @group
        Going to tint Kohaku!
        @char Kohaku tint:red
    @sfx SoundX if:score>10
@stop

remove

Removes (disposes) actors (character, background, text printer, choice handler) with the specified IDs. In case multiple actors with the same ID found (eg, a character and a printer), will affect only the first found one.

NOTE

By default, Naninovel automatically removes unused actors when unloading script resources; only use this command when Remove Actors is disabled in resource provider configuration or when you need to force-dispose an actor at specific moment. Consult memory management guide for more info.

Parameter	Type	Description
actorIds	string list	IDs of the actors to remove or * to remove all actors.

; Fade-off and then dispose Kohaku and Yuko actors.
@hide Kohaku,Yuko wait!
@remove Kohaku,Yuko

; Fade-off and remove all actors.
@hideAll wait!
@remove *

resetState

Resets state of the engine services and unloads (disposes) all the resources loaded by Naninovel (textures, audio, video, etc); will basically revert to an empty initial engine state.

NOTE

Be aware, that this command can not be undone (rewound back).

Parameter	Type	Description
exclude	string list	Names of the engine services (interfaces) to exclude from reset. Consider adding ICustomVariableManager to preserve the local variables.
only	string list	Names of the engine services (interfaces) to reset; other services won't be affected. Doesn't have effect when the nameless (exclude) parameter is assigned.

; Reset all the services (script will stop playing).
@resetState

; Reset all the services except script player, custom variable and
; audio managers, allowing current script and audio tracks
; continue playing and preserving values of the custom variables.
@resetState IScriptPlayer,ICustomVariableManager,IAudioManager

; Reset only 'ICharacterManager' and 'IBackgroundManager' services
; removing all the character and background actors from scene
; and unloading associated resources from memory.
@resetState only:ICharacterManager,IBackgroundManager

resetText

Resets (clears) the contents of a text printer.

Parameter	Type	Description
printerId	string	ID of the printer actor to use. Will use a default one when not specified.

; Print and then clear contents of the default printer.
This line will disappear.
@resetText

; Same as above, but with 'Wide' printer.
@print "This line will disappear." printer:Wide
@resetText Wide

return

Attempts to navigate naninovel script playback to a command after the last used @gosub. See @gosub command summary for more info and usage examples.

Parameter	Type	Description
reset	string list	When specified, will reset the engine services state before returning to the initial script from which the gosub was entered (in case it's not the currently played script). Specify * to reset all the services, or specify service names to exclude from reset. By default, the state does not reset.

save

Automatically save the game to a quick save slot.

set

Assigns result of a script expression to a custom variable.

NOTE

If a variable with the specified name doesn't exist, it will be automatically created.

Specify multiple set expressions by separating them with ;. The expressions will be executed in sequence in the order of declaration.

In case variable name starts with t_ it's considered a reference to a value stored in 'Script' managed text document. Such variables can't be assigned and are intended for referencing localizable text values.

Parameter	Type	Description
expression	string	Assignment expression. The expression should be in the following format: var=expression, where var is the name of the custom variable to assign and expression is a script expression, the result of which should be assigned to the variable. It's possible to use increment and decrement unary operators (@set foo++, @set foo--) and compound assignment (@set foo+=10, @set foo-=3, @set foo*=0.1, @set foo/=2).

; Assign 'foo' variable a 'bar' string value.
@set foo="bar"

; Assign 'foo' variable a 1 number value.
@set foo=1

; Assign 'foo' variable a 'true' boolean value.
@set foo=true

; If 'foo' is a number, add 0.5 to its value.
@set foo+=0.5

; If 'angle' is a number, assign its cosine to 'foo' variable.
@set foo=cos(angle)

; Get random number between -100 and 100, then raise to power of 4 
; and assign to 'foo' variable. Quotes are required when whitespace 
; is present inside the expression.
@set "foo = pow(random(-100, 100), 4)"

; If 'foo' is a number, add 1 to its value (increment).
@set foo++

; If 'foo' is a number, subtract 1 from its value (decrement).
@set foo--

; Assign 'foo' variable value of the 'bar' variable, 
; which is 'Hello World!' string.
@set bar="Hello World!"
@set foo=bar

; Defining multiple set expressions in one line; 
; the result will be the same as above.
@set bar="Hello World!";foo=bar

; It's possible to inject variables to naninovel script command parameters.
@set scale=0
# EnlargeLoop
@char Kohaku.Default scale:{scale}
@set scale+=0.1
@goto .EnlargeLoop if:scale<1

; ...and generic text lines.
@set drink="Dr. Pepper"
My favourite drink is {drink}!

; When using double quotes inside text expression value, escape them.
@set remark="Shouting \"Stop the car!\" was a mistake."

; Use global variable ('g_' prefix) to persist the value across sessions.
; The variable will remain true even when the game is restarted.
@set g_Ending001Reached=true

; Increment the global variable only once, even when re-played.
@set g_GlobalCounter++ if:!hasPlayed()

sfx

Plays or modifies currently played SFX (sound effect) track with the specified name.

NOTE

Sound effect tracks are not looped by default. When sfx track name (SfxPath) is not specified, will affect all the currently played tracks. When invoked for a track that is already playing, the playback won't be affected (track won't start playing from the start), but the specified parameters (volume and whether the track is looped) will be applied.

Parameter	Type	Description
sfxPath	string	Path to the sound effect asset to play.
volume	decimal	Volume of the sound effect.
loop	boolean	Whether to play the sound effect in a loop.
fade	decimal	Duration of the volume fade-in when starting playback, in seconds (0.0 by default); doesn't have effect when modifying a playing track.
group	string	Audio mixer group path ↗ that should be used when playing the audio.
time	decimal	Duration (in seconds) of the modification.
wait	boolean	Whether to wait for the SFX fade animation to finish before playing next command.

; Plays an SFX with the name 'Explosion' once.
@sfx Explosion

; Plays an SFX with the name 'Rain' in a loop and fades-in over 30 seconds.
@sfx Rain loop! fade:30

; Changes volume of all the played SFX tracks to 75% over 2.5 seconds
; and disables looping for all of them.
@sfx volume:0.75 !loop time:2.5

sfxFast

Plays an SFX (sound effect) track with the specified name. Unlike @sfx command, the clip is played with minimum delay and is not serialized with the game state (won't be played after loading a game, even if it was played when saved). The command can be used to play various transient audio clips, such as UI-related sounds (eg, on button click with Play Script component).

Parameter	Type	Description
sfxPath	string	Path to the sound effect asset to play.
volume	decimal	Volume of the sound effect.
restart	boolean	Whether to start playing the audio from start in case it's already playing.
additive	boolean	Whether to allow playing multiple instances of the same clip; has no effect when restart is enabled.
group	string	Audio mixer group path ↗ that should be used when playing the audio.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Plays an SFX with the name 'Click' once.
@sfxFast Click

; Same as above, but allow concurrent playbacks of the same clip.
@sfxFast Click !restart

shake

Applies shake effect for the actor with the specified ID or main camera.

Parameter	Type	Description
actorId	string	ID of the actor to shake. In case multiple actors with the same ID found (eg, a character and a printer), will affect only the first found one. When not specified, will shake the default text printer. To shake main camera, use Camera keyword.
count	integer	The number of shake iterations. When set to 0, will loop until stopped with -1.
time	decimal	The base duration of each shake iteration, in seconds.
deltaTime	decimal	The randomizer modifier applied to the base duration of the effect.
power	decimal	The base displacement amplitude of each shake iteration, in units.
deltaPower	decimal	The randomized modifier applied to the base displacement amplitude.
hor	boolean	Whether to displace the actor horizontally (by x-axis).
ver	boolean	Whether to displace the actor vertically (by y-axis).
wait	boolean	Whether to wait for the effect warm-up animation before playing next command.

; Shake 'Dialogue' text printer with default params.
@shake Dialogue

; Start shaking 'Kohaku' character, show choice to stop and act accordingly.
@shake Kohaku count:0
@choice "Continue shaking" goto:.Continue
@choice "Stop shaking" goto:.Stop
@stop
# Stop
@shake Kohaku count:-1
# Continue
...

; Shake main Naninovel camera horizontally 5 times.
@shake Camera count:5 hor! !ver

show

Shows (makes visible) actors (character, background, text printer, choice handler, etc) with the specified IDs. In case multiple actors with the same ID found (eg, a character and a printer), will affect only the first found one.

Parameter	Type	Description
actorIds	string list	IDs of the actors to show.
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Given an actor with ID 'Smoke' is hidden, reveal it over 3 seconds.
@show Smoke time:3

; Show 'Kohaku' and 'Yuko' actors.
@show Kohaku,Yuko

showPrinter

Shows a text printer.

Parameter	Type	Description
printerId	string	ID of the printer actor to use. Will use a default one when not specified.
time	decimal	Duration of the animation initiated by the command, in seconds.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Show a default printer.
@showPrinter

; Show printer with ID 'Wide'.
@showPrinter Wide

showUI

Makes UI elements with the specified resource names visible. When no names are specified, will reveal the entire UI (in case it was hidden with @hideUI).

Parameter	Type	Description
uINames	string list	Name of the UI resource to make visible.
time	decimal	Duration (in seconds) of the show animation. When not specified, will use UI-specific duration.
wait	boolean	Whether to wait for the UI fade-in animation before playing next command.

; Given you've added a custom UI with 'Calendar' name,
; the following will make it visible on the scene.
@showUI Calendar

; Given you've hidden the entire UI with @hideUI, show it back.
@showUI

; Simultaneously reveal built-in 'TipsUI' and custom 'Calendar' UIs.
@showUI TipsUI,Calendar

skip

Allows to enable or disable script player "skip" mode.

Parameter	Type	Description
enable	boolean	Whether to enable (default) or disable the skip mode.

; Enable skip mode.
@skip

; Disable skip mode.
@skip false

slide

Slides (moves between two positions) an actor (character, background, text printer or choice handler) with the specified ID and optionally changes actor visibility and appearance. Can be used instead of multiple @char or @back commands to reveal or hide an actor with a slide animation.

NOTE

Be aware, that this command searches for an existing actor with the specified ID over all the actor managers, and in case multiple actors with the same ID exist (eg, a character and a text printer), this will affect only the first found one. Make sure the actor exist on scene before referencing it with this command; eg, if it's a character, you can add it on scene imperceptibly to player with @char CharID visible:false time:0.

Parameter	Type	Description
idAndAppearance	named string	ID of the actor to slide and (optionally) appearance to set.
from	decimal list	Position in scene space to slide the actor from (slide start position). Described as follows: 0,0 is the bottom left, 50,50 is the center and 100,100 is the top right corner of the scene; Z-component (depth) is in world space. When not specified, will use current actor position in case it's visible and a random off-scene position otherwise (could slide-in from left or right borders).
to	decimal list	Position in scene space to slide the actor to (slide finish position).
visible	boolean	Change visibility status of the actor (show or hide). When not set and target actor is hidden, will still automatically show it.
easing	string	Name of the easing function to apply. When not specified, will use a default function set in the configuration.
time	decimal	Duration of the animation initiated by the command, in seconds.
lazy	boolean	When the animation initiated by the command is already running, enabling lazy will continue the animation to the new target from the current state. When lazy is not enabled (default behaviour), currently running animation will instantly complete before starting animating to the new target.
wait	boolean	Whether to wait for the command to finish before starting executing next command in the scenario script. Default behaviour is controlled by Wait By Default option in the script player configuration.

; Given 'Jenna' actor is not visible, reveal it with an 'Angry' appearance
; and slide to the center from either left or right border of the scene.
@slide Jenna.Angry to:50

; Given 'Sheba' actor is currently visible,
; hide and slide it out of the scene over the left border.
@slide Sheba to:-10 !visible

; Slide 'Mia' actor from left-center side of the scene to the right-bottom
; over 5 seconds using 'EaseOutBounce' animation easing.
@slide Sheba from:15,50 to:85,0 time:5 easing:EaseOutBounce

snow

Spawns particle system simulating snow.

Parameter	Type	Description
power	decimal	The intensity of the snow (particles spawn rate per second); defaults to 100. Set to 0 to disable (de-spawn) the effect.
time	decimal	The particle system will gradually grow the spawn rate to the target level over the specified time, in seconds.
pos	decimal list	Position (relative to the scene borders, in percents) to set for the spawned effect game object. Position is described as follows: 0,0 is the bottom left, 50,50 is the center and 100,100 is the top right corner of the scene. Use Z-component (third member, eg ,,10) to move (sort) by depth while in ortho mode.
position	decimal list	Position (in world space) to set for the spawned effect game object.
rotation	decimal list	Rotation to set for the spawned effect game object.
scale	decimal list	Scale to set for the spawned effect game object.
wait	boolean	Whether to wait for the effect warm-up animation before playing next command.

; Start intensive snow over 10 seconds.
@snow power:300 time:10
; Stop the snow over 30 seconds.
@snow power:0 time:30

spawn

Instantiates a prefab or a special effect; when performed over an already spawned object, will update the spawn parameters instead.

NOTE

If prefab has a MonoBehaviour component attached the root object, and the component implements a IParameterized interface, will pass the specified params values after the spawn; if the component implements IAwaitable interface, command execution will be able to wait for the async completion task returned by the implementation.

Parameter	Type	Description
path	string	Name (path) of the prefab resource to spawn.
params	string list	Parameters to set when spawning the prefab. Requires the prefab to have a IParameterized component attached the root object.
pos	decimal list	Position (relative to the scene borders, in percents) to set for the spawned object. Position is described as follows: 0,0 is the bottom left, 50,50 is the center and 100,100 is the top right corner of the scene. Use Z-component (third member, eg ,,10) to move (sort) by depth while in ortho mode.
position	decimal list	Position (in world space) to set for the spawned object.
rotation	decimal list	Rotation to set for the spawned object.
scale	decimal list	Scale to set for the spawned object.
wait	boolean	Whether to wait for the spawn to warm-up in case it implements IAwaitable interface.

; Given a 'Rainbow' prefab is assigned in spawn resources, instantiate it.
@spawn Rainbow

stop

Stops the naninovel script execution.

Show the choices and halt script execution until the player picks one.
@choice "Choice 1"
@choice "Choice 2"
@stop
We'll get here after player will make a choice.

stopBgm

Stops playing a BGM (background music) track with the specified name.

NOTE

When music track name (BgmPath) is not specified, will stop all the currently played tracks.

Parameter	Type	Description
bgmPath	string	Path to the music track to stop.
fade	decimal	Duration of the volume fade-out before stopping playback, in seconds (0.35 by default).
wait	boolean	Whether to wait for the BGM fade-out animation to finish before playing next command.

; Fades-out 'Sanctuary' bgm track over 10 seconds and stops the playback.
@stopBgm Sanctuary fade:10

; Stops all the currently played music tracks.
@stopBgm

stopSfx

Stops playing an SFX (sound effect) track with the specified name.

NOTE

When sound effect track name (SfxPath) is not specified, will stop all the currently played tracks.

Parameter	Type	Description
sfxPath	string	Path to the sound effect to stop.
fade	decimal	Duration of the volume fade-out before stopping playback, in seconds (0.35 by default).
wait	boolean	Whether to wait for the SFX fade-out animation to finish before playing next command.

; Stop playing an SFX with the name 'Rain', fading-out for 15 seconds.
@stopSfx Rain fade:15

; Stops all the currently played sound effect tracks.
@stopSfx

stopVoice

Stops playback of the currently played voice clip.

; Given a voice is being played, stop it.
@stopVoice

sun

Spawns particle system simulating sun shafts aka god rays.

Parameter	Type	Description
power	decimal	The intensity of the rays (opacity), in 0.0 to 1.0 range; default is 0.85. Set to 0 to disable (de-spawn) the effect.
time	decimal	The particle system will gradually grow the spawn rate to the target level over the specified time, in seconds.
pos	decimal list	Position (relative to the scene borders, in percents) to set for the spawned effect game object. Position is described as follows: 0,0 is the bottom left, 50,50 is the center and 100,100 is the top right corner of the scene. Use Z-component (third member, eg ,,10) to move (sort) by depth while in ortho mode.
position	decimal list	Position (in world space) to set for the spawned effect game object.
rotation	decimal list	Rotation to set for the spawned effect game object.
scale	decimal list	Scale to set for the spawned effect game object.
wait	boolean	Whether to wait for the effect warm-up animation before playing next command.

; Start intensive sunshine over 10 seconds.
@sun power:1 time:10
; Stop the sunshine over 30 seconds.
@sun power:0 time:30

title

Resets engine state and shows ITitleUI UI (main menu).

; Exit to title UI, no matter which script is playing.
@title

toast

Shows a UI for general-purpose self-hiding popup notification (aka "toast") with the specified text and (optionally) appearance and duration. The UI is automatically hidden after the specified (or default) duration.

NOTE

Appearance name is the name of a game object with Toast Appearance component inside the ToastUI UI prefab (case-insensitive).

Parameter	Type	Description
text	string	The text content to set for the toast.
appearance	string	Appearance variant (game object name) of the toast. When not specified, will use default appearance set in Toast UI prefab.
time	decimal	Seconds to wait before hiding the toast. When not specified, will use duration set by default in Toast UI prefab.

; Shows a default toast with 'Hello World!' content.
@toast "Hello World!"

; Shows a toast with a 'warning' appearance.
@toast "You're in danger!" appearance:warning

; The toast will disappear in one second.
@toast "I'll disappear in 1 second." time:1

trans

Performs scene transition masking the real scene content with anything that is visible at the moment the command starts execution (except the UI), executing nested commands to change the scene and finishing with specified transition effect.

The command works similar to actor appearance transitions, but covers the whole scene. Use it to change multiple actors and other visible entities to a new state in a single batch with a transition effect.

NOTE

The UI will be hidden and user input blocked while the transition is in progress (nested commands are running). You can change that by overriding the ISceneTransitionUI, which handles the transition process.

Async nested commands will execute immediately, w/o the need to specify time:0 for each.

The nested block is expected to always finish; don't nest any commands that could navigate outside the nested block, as this may cause undefined behaviour.

Parameter	Type	Description
transition	string	Type of the transition effect to use (crossfade is used by default).
params	decimal list	Parameters of the transition effect.
dissolve	string	Path to the custom dissolve texture (path should be relative to a Resources folder). Has effect only when the transition is set to Custom mode.
easing	string	Name of the easing function to use for the transition.
time	decimal	Duration (in seconds) of the transition.

; Set up initial scene with 'Felix' character and sunny vibe.
@char Felix
@back SunnyDay
@sun power:1
Felix: What a nice day!

; Transition to new scene with 'Jenna' character and rainy vibe
; via 'DropFade' transition effect over 3 seconds.
@trans DropFade time:3
    @hide Felix
    @char Jenna
    @back RainyDay
    @sun power:0
    @rain power:1
Jenna: When will the damn rain stop?

unloadScene

Unloads a Unity scene ↗ with the specified name. Don't forget to add the required scenes to the build settings ↗ to make them available for loading. Be aware, that only scenes loaded additively can be then unloaded (at least one scene should always remain loaded).

Parameter	Type	Description
sceneName	string	Name of the scene to unload.

; Load scene 'TestScene2' in additive mode and then unload it.
@loadScene TestScene2 additive!
@unloadScene TestScene2

unlock

Sets an unlockable item with the specified ID to unlocked state.

NOTE

The unlocked state of the items is stored in global scope.
In case item with the specified ID is not registered in the global state map, the corresponding record will automatically be added.

Parameter	Type	Description
id	string	ID of the unlockable item. Use * to unlock all the registered unlockable items.

; Unlocks an unlockable CG record with ID 'FightScene1'.
@unlock CG/FightScene1

voice

Plays a voice clip at the specified path.

Parameter	Type	Description
voicePath	string	Path to the voice clip to play.
volume	decimal	Volume of the playback.
group	string	Audio mixer group path ↗ that should be used when playing the audio.
authorId	string	ID of the character actor this voice belongs to. When specified and per-author volume is used, volume will be adjusted accordingly.

; Given a 'Rawr' voice resource is available, play it.
@voice Rawr

wait

Holds script execution until the specified wait condition.

Parameter	Type	Description
waitMode	string	Wait conditions: - i user press continue or skip input key; - 0.0 timer (seconds); - i0.0 timer, that is skip-able by continue or skip input keys.

; Thunder SFX will play 0.5 seconds after shake background effect finishes.
@spawn ShakeBackground
@wait 0.5
@sfx Thunder

; Print first 2 words, then wait for input before printing the rest.
Lorem ipsum[wait i] dolor sit amet.
; You can also use the following shortcut (@i command) for this wait mode.
Lorem ipsum[i] dolor sit amet.

; Start looped SFX, print message and wait for a skippable 5 seconds delay,
; then stop the SFX.
@sfx Noise loop!
Jeez, what a disgusting Noise. Shut it down![wait i5][< skip!]
@stopSfx Noise

while

Executes nested lines in a loop, as long as specified conditional expression resolves to true.

Parameter	Type	Description
expression	string	A script expression, which should return a boolean value determining whether the associated nested block should continue executing in loop.

; Guess the number game.
@set number=random(1,100);answer=0
@while answer!=number
    @input answer summary:"Guess a number between 1 and 100"
    @stop
    @if answer<number
        Wrong, too low.
    @else if:answer>number
        Wrong, too high.
    @else
        Correct!