Suika3 Tag Reference

Index

---

anime

Run Animation

The anime tag loads and executes an animation definition from a file. It allows for complex visual effects, character movements, or looping environmental animations beyond simple transitions.

Basic Usage

# Run a synchronous animation (waits for completion)
[anime file="opening_effect.txt"]

# Run an asynchronous looping animation
[anime file="sparkle.txt" async="true" register="my_loop"]

# Stop a registered asynchronous animation
[anime stop="true" register="my_loop"]

Arguments

Tips

Synchronous vs. Asynchronous:

• Synchronous (async="false"): Great for cutscenes where you want the player to watch the animation before any text or choices appear.
• Asynchronous (async="true"): Perfect for background effects (like falling snow or a flickering light) that should continue while the story progresses.

Managing Instances:

• By using the register argument, you can label a specific animation.
• This is how you tell the engine exactly which animation to stop when you use stop="true".

UI Control:

• Use showmsgbox="false" if your animation is meant to take up the full screen and you want the dialogue window to disappear temporarily for a cleaner look.

---

bg

Change Background

The bg tag changes the background image with a smooth fading effect. It's the primary way to set the scene in your visual novel.

Basic Usage

# Transition to background.png over 1.0 second
[bg file="background.png" time="1.0"]

# Fade to a black screen (removes the background)
[bg file="none" time="1.0"]

Arguments

Transition Methods (method)

You can create different atmospheres by choosing the right transition style:

For rule and melt, the image switches pixel-by-pixel from the darkest to the lightest areas of the rule map.

Tips

Relative Positioning:

• If you want to nudge the background from its current position, use the r prefix.
• For example, x="r50" moves the image 50 pixels to the right of its current X coordinate.

What is a Rule Image?:

• It's a grayscale image where black areas transition first and white areas transition last.
• By creating custom rule images, you can achieve effects like horizontal wipes, circular reveals, or even more artistic patterns!

---

bgm

Play Background Music

The bgm tag plays a background music track. Music is an essential tool for setting the mood of your scene, and it will continue to loop automatically until stopped or changed.

Basic Usage

# Start playing a BGM track
[bgm file="field_theme.ogg"]

# Stop the current BGM (use "none")
[bgm file="none"]

Arguments

Tips

Required Format:

• For compatibility and performance, Suika3 requires BGM files to be in Ogg Vorbis format.
• The sampling rate MUST be 44,100Hz.

Looping:

• Background music is designed to loop by default, so you don't need to worry about the music ending abruptly during a long dialogue scene.

Smooth Transitions:

• If you call [bgm] while another track is already playing, the engine will typically handle the transition.
• To adjust the loudness of the music, you'll want to use the [volume] tag.

Stopping Music:

• When a scene ends or the mood changes to silence, remember to use [bgm file="none"] to give the player's ears a rest!

---

callmacro

Call Macro

The callmacro tag executes a previously defined macro. It allows you to trigger a specific sequence of commands, such as character entrances or UI animations, multiple times throughout your script without rewriting the original code.

Basic Usage

# Call a macro named "kaito_entrance"
[callmacro name="kaito_entrance"]

# Call a macro for a specific scene transition
[callmacro name="fade_to_white"]

Arguments

Tips

Efficiency:

• By using [callmacro], you can keep your main story script focused and readable.
• Instead of seeing 10 lines of animation code, you'll just see one clear command.

Execution Flow:

• When the engine hits [callmacro], it immediately jumps to the defined macro, runs all the tags inside it, and then automatically returns to the very next line after the [callmacro] tag.

Modular Design:

• Think of macros as "custom tags" for your game.
• If you decide to change how a character enters a scene, you only need to update the code once in the [defmacro] block, and every [callmacro] will reflect that change!

---

ch

Character Display

The ch tag shows, hides, or updates character images on various layers. It allows for detailed control over positioning, scaling, and rotations for multiple characters and background at once.

Basic Usage

# Show a character at the center
[ch center="chara001.png" time="1.0"]

# Show multiple characters with specific positions
[ch left="chara002.png" right="chara003.png" time="0.5"]

# Hide a specific character
[ch center="none" time="1.0"]

Arguments

Layer File Arguments

Specify a filename to load an image onto a layer. Set to none to unload (hide) the image.

Layer Parameter Arguments

Each layer above (e.g., center) can be customized using the following suffixes (e.g., center-x, center-rotate).

Tips

Batch Updates:

• You can update multiple characters and the background simultaneously in a single [ch] tag to ensure they animate together perfectly.

Relative Transformation:

• Like the bg tag, all numeric parameters support the r prefix.
• For example, center-y="r-50" will hop the center character 50 pixels upward from its current position.

---

chapter

Set Chapter Name

The chapter tag sets the name of the current chapter. This name is typically used by the game system to display progress in the save/load menu or on the game screen, helping players keep track of their journey.

Basic Usage

# Set the chapter name at the beginning of a story segment
[chapter name="Chapter 01: The Beginning"]

# Update the chapter name as the story progresses
[chapter name="Intermission: A Quiet Night"]

Arguments

Tips

Save Data Visibility:

• In many Suika3 configurations, the string you set here is what appears on the "Save" and "Load" slots.
• Choose a name that helps the player remember exactly where they were in the story!

Consistency:

• It's a good practice to call the [chapter] tag immediately after a [label] that starts a new major scene or chapter.

Updating Names:

• You can call [chapter] as many times as you like.
• Every time you do, the old chapter name is overwritten by the new one.

---

choose

Display Selection Options

The choose tag displays up to 8 interactive buttons for the player. It stores the text of the chosen item in a variable.

Basic Usage

# Store selection in a variable
[choose
    text1="Red Pill"
    text2="Green Pill"
    text3="Blue Pill"
    name="user_choice"
    value1="red"
    value2="green"
    value3="blue"
]

Arguments

Localization

For example, if the user OS environment is set to Japanese, text1-ja is preferred instead of text1.

For English OS locales including all regions, -en is used as the default fallback. If a more specific variant such as -en-gb is specified in a tag and best matches with the user region, it will be preferred. The same mechanism is applied to Spanish and French. Note that there is no fallback from Traditional Chinese to Simplified Chinese.

For example, if the user locale is en-AU, the following priority is applied:

• 1. text1-en-au
• 1. text1-en
• 1. text1

The following are currently not supported but planned to be supported.

Tips

Branching Logic:

• You can use the [if] tag to check the stored value and create complex branches.

[choose
  name="var1"
  text1="Go to school"
  text2="Go to hospital"
  value1="1"
  value2="2"]

[if lhs="${var1}" op="=" rhs="1"]
  # School.
[else]
  # Hospital.
[endif]

Variable Persistence:

• Since everything is a string, remember that even numbers like "100" are stored as text.
• Suika3's logic tags (like if) can handle these strings for comparisons.

---

set

Set Variable

The set tag assigns a value to a variable name. In Suika3, all variables are treated as text strings, but they can be compared numerically in other tags like [if].

Basic Usage

# Assign a simple string to a variable
[set name="player_name" value="Kaito"]

# Set a numeric-like value (stored as a string)
[set name="health" value="100"]

# Clear a variable by setting it to an empty string
[set name="flag_event_01" value=""]

# Add 1 to var1.
[set name="var1" value1="${var1}" op="+" value2="1"]

Arguments

Tips

String Handling:

• Since Suika3 treats everything as text, value="100" and value="May" are handled the same way internally.
• You can reference these variables in other tags (like text or if) using the ${variable_name} syntax.

Flag Management:

• For game flags (like "has met the hero"), it's a common practice to use "true" and "false" or "1" and "0".
• Consistency is key! If you start using "1", stick with it so your [if] checks don't get confused.

Variable Naming:

• Avoid using spaces or special symbols in your variable names. my_variable is much safer than my variable!.

---

click

Wait for Click

The click tag pauses the script execution and waits for the player to click the mouse or press a key. It is commonly used to create pauses between visual changes or before a major transition.

Basic Usage

# Change the background, then wait for the player to click
[bg file="sunset.png" time="1.0"]
[click]

# After the click, show the character
[ch center="chara01.png" time="1.0"]

Arguments

This tag does not take any arguments.

Tips

Timing and Pacing:

• Use [click] when you want to give the player a moment to look at a new background or a specific character expression before the dialogue continues.
• Unlike the [text] tag, which waits for a click automatically after displaying a message, [click] is used for manual flow control during non-dialogue sequences.

Visual Feedback:

• When the script hits a [click] tag, the game will remain still. Ensure that any preceding animations (like [bg] or [ch]) have a time set, or the screen might feel static too abruptly.

For timed waits:

• Use [wait] for timed waits.

---

goto

Jump to Label

The goto tag immediately moves the NovelML execution to a specified label. It is useful tool for controlling the flow of your story, allowing you to skip sections or loop back to previous parts.

Please note that small branches should be realized by [if].

Basic Usage

# Jump to the beginning of the morning scene
[goto name="morning_start"]

# ... this part of the script will be skipped ...

[label name="morning_start"]
[text text="The sun rises over the horizon."]

Arguments

Tips

Unconditional Jump:

• Unlike [if], [goto] always jumps to the target label as soon as the engine hits the tag.

Flow Management:

• Use [goto] at the end of a branching path to bring the story back to a "common" route.
• It's also great for creating loops (like a "Return to Title" sequence) when combined with other logic.

Across Files?:

• Remember that [goto] typically works within the current script file.
• If you want to jump to a different file entirely, you'll want to look at the [load] tag!

---

defmacro

Define Macro

The defmacro tag starts the definition of a macro. A macro allows you to group multiple tags and commands into a single named block, which can be reused throughout your script using the [callmacro] tag.

Basic Usage

# Define a macro for a specific character's entrance
[defmacro name="enter_kaito"]
    [ch center="kaito_smile.png" time="0.5"]
    [text name="Kaito" text="Hey! Did I keep you waiting?"]
[endmacro]

# Later in your script, call it with a single line
[callmacro name="enter_kaito"]

Arguments

Tips

Closing the Definition:

• Every [defmacro] must be paired with an [endmacro] tag to mark the end of the definition.

Code Reusability:

• Macros are perfect for repetitive sequences, such as specific UI transitions, character-specific visual setups, or complex sound and visual combinations.

Organization:

• It is a common practice to define all your macros at the very beginning of your main script file or in a separate file that you load at the start.

Nesting and Logic:

• You can include almost any other tag inside a macro, including [if] statements and even [returnmacro] to exit the macro early based on certain conditions.

---

gui

Show GUI

The gui tag loads and displays a Graphical User Interface (GUI) definition from a specified file. It is used to display menus, title screens, or custom interaction panels.

Basic Usage

# Display the main menu GUI
[gui file="main_menu.txt"]

# Show a custom save/load screen
[gui file="save_screen.txt"]

Arguments

Tips

GUI Definitions:

• The file argument points to a text file that defines the layout, buttons, and actions of your interface.
• These files specify where images are placed and what happens (like jumping to a label or quitting) when a user interacts with them.

Usage in Flow:

• Typically, a [gui] tag is used for a graphical menu such as title screen.

Customization:

• Since the GUI is defined in an external file, you can create multiple looks for your game and switch between them just by calling different files with this tag.

---

label

Define Label

The label tag defines a specific point in the script that can be targeted by jump commands like [goto] or [load]. It acts as a bookmark for navigation within your story.

Basic Usage

# Define a label for the start of a new chapter
[label name="chapter_01_start"]

# Use a jump command to reach this label
[goto name="chapter_01_start"]

Arguments

Tips

Navigation Control:

• Labels are useful for creating branching paths.
• For example, you can put a label at the begining of the section of your story for a long jump.

Unique Naming:

• Every label name within a single script file must be unique.
• If you have two labels with the same name, the engine might not know where to jump, and that's no fun for anyone!

Organization:

• It's a good habit to use descriptive names like label_evening_park instead of label1.
• It makes it much easier for you (and me!) to read the script later and understand what's happening.

---

text

Display Text

The text tag displays a message in the message box. It can show the main dialogue or narration, and optionally display a character's name in the name box.

Basic Usage

# Narration style (no name displayed)
[text text="The wind was howling through the trees."]

# Character dialogue
[text name="Keith" text="I've been waiting for you here in the small room."]

Arguments

Localization

For example, if the user OS environment is set to Japanese, text-ja is preferred instead of text.

For English OS locales including all regions, -en is used as the default fallback. If a more specific variant such as -en-gb is specified in a tag and best matches with the user region, it will be preferred. The same mechanism is applied to Spanish and French. Note that there is no fallback from Traditional Chinese to Simplified Chinese.

For example, if the user locale is en-GB, the following priority is applied:

• 1. text-en-gb
• 1. text-en
• 1. text

The following are currently not supported but planned to be supported.

Actions

You can use special parameters in the text tag.

# Clear the message box.
[text action="clear"]

# Clear the message box and show it.
[text action="new"]

# Show the message box.
[text action="show"]

# Hide the message box.
[text action="hide"]

NVL Mode

You can enter the NVL mode by setting some config.

[text action="hide"]
[wait time="0.3"] # Wait for the message box to hide.
[config name="game.novel" value="true"]
[config name="msgbox.image" value="system/message/msgbox-nvl.png"]
[config name="msgbox.x" value="0"]
[config name="msgbox.y" value="0"]
[config name="msgbox.margin.line" value="60"]
[config name="namebox.enable" value="false"]
[config name="choose.box1.idle" value="system/choose/nvl.png"]
[config name="choose.box1.hover" value="system/choose/nvl.png"]
[config name="choose.box1.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box1.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="choose.box2.idle" value="system/choose/nvl.png"]
[config name="choose.box2.hover" value="system/choose/nvl.png"]
[config name="choose.box2.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box2.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="choose.box3.idle" value="system/choose/nvl.png"]
[config name="choose.box3.hover" value="system/choose/nvl.png"]
[config name="choose.box3.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box3.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="click.move" value="true"]
[text action="clear"]

You can go back to ADV mode by resetting the config.

[text action="hide"]
[wait time="0.3"] # Wait for the message box to hide.
[config name="game.novel" value="false"]
[config name="msgbox.image" value="system/message/msgbox.png"]
[config name="msgbox.x" value="0"]
[config name="msgbox.y" value="520"]
[config name="msgbox.margin.line" value="40"]
[config name="namebox.enable" value="true"]
[config name="choose.box1.idle" value="system/choose/idle.png"]
[config name="choose.box1.hover" value="system/choose/hover.png"]
[config name="choose.box1.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box1.hover_anime" value="system/choose/hover.anime"]
[config name="choose.box2.idle" value="system/choose/idle.png"]
[config name="choose.box2.hover" value="system/choose/hover.png"]
[config name="choose.box2.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box2.hover_anime" value="system/choose/hover.anime"]
[config name="choose.box3.idle" value="system/choose/idle.png"]
[config name="choose.box3.hover" value="system/choose/hover.png"]
[config name="choose.box3.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box3.hover_anime" value="system/choose/hover.anime"]
[config name="click.move" value="false"]

In NVM mode, you can control text messages like this:

# New page.
[text action="clear"]
[text text="Hello, this is NVL mode test."]
[text text="NVL mode has a fullscreen-styled message box."]
[text text="By default, each text tag will do a line feed."]
[text text="To continue a paragraph,"]
[text text="specify the space parameter." space=" "]

# New page.
[text action="clear"]
[text text="Please clear the message box explicitly."]

Voice

If the current language is en-us, a voice file will resolved in the following order:

1. voice-en-us parameter
2. voice/en-us/ + voice parameter
3. voice-en parameter
4. voice/en/ + voice parameter
5. voice parameter

If the current language is ja, a voice file will resolved in the following order:

1. voice-ja parameter
2. voice/ja/ + voice parameter
3. voice parameter

Tips

Automatic Waiting:

• Unlike other tags, the text tag automatically waits for a player's click after the message is fully displayed.
• You don't need to add a [click] tag after every line of dialogue!

Using Variables:

• You can include variables within your text by using the ${variable_name} syntax.
• Example: [text text="Hello, ${player_name}!"] will greet the player using whatever name is stored in that variable.

Line Breaks:

• Check your project's configuration for how long a single line can be.
• If your text is too long, it might overflow the message box, so keep an eye on the length of your text argument!

---

if

Conditional Branching

The if tag allows the NovelML to branch based on a specific condition. By comparing variables or values, you can create unique story paths or react to previous player choices.

Basic Usage

# Check if a variable equals a certain value
[if lhs="${points}" op="==" rhs="100"]
    [text text="Perfect score! You're amazing."]
[elseif lhs="${points}" op=">=" rhs="80"]
    [text text="Great job! You passed."]
[else]
    [text text="Better luck next time."]
[endif]

Arguments

Comparison Operators (op)

You can use these operators to define how the two sides are compared:

Tips

Closing the Block:

• Every [if] block MUST end with an [endif] tag.
• If you forget it, the engine might get confused about where the condition ends!

Variable Syntax:

• When using a variable as the lhs, always wrap it in ${}.
• For example, use lhs="${flag_01}" instead of just lhs="flag_01".

Handling Strings vs. Numbers:

• Suika3 treats variable values as strings, but these operators allow you to perform numeric-style comparisons.
• Just be consistent with your values (e.g., using "1" for true and "0" for false).

Multiple Branches:

• You can use as many [elseif] tags as you need between [if] and [endif] to check for multiple specific conditions.

---

elseif

Additional Conditional Branching

The elseif tag specifies an additional condition within an [if] block. It is only evaluated if the preceding [if] and any previous [elseif] conditions were false.

Basic Usage

[if lhs="${rank}" op="==" rhs="A"]
    [text text="Excellent! You're a pro."]
[elseif lhs="${rank}" op="==" rhs="B"]
    [text text="Good job! Keep it up."]
[elseif lhs="${rank}" op="==" rhs="C"]
    [text text="Not bad, but you can do better."]
[else]
    [text text="Don't give up! Try again."]
[endif]

Arguments

Same as [if]. See also if.

Tips

Sequential Evaluation:

• The engine checks conditions from top to bottom.
• As soon as one [if] or [elseif] condition is met, its block is executed, and the rest of the branch (including other [elseif]s and the [else]) is skipped.

Placement:

• [elseif] must always be placed between an [if] tag and an [else] or [endif] tag.
• You can use as many [elseif] tags as you need to cover all your bases!

Efficiency:

• If you have a lot of conditions that check the same variable, using multiple [elseif] tags is much cleaner and more efficient than nesting multiple [if] blocks inside each other.

---

else

Default Conditional Branch

The else tag defines a block of code to be executed if none of the preceding [if] or [elseif] conditions were met. It acts as the "default" path for your branching logic.

Basic Usage

[if lhs="${weather}" op="==" rhs="sunny"]
    [text text="It's a beautiful day!"]
[elseif lhs="${weather}" op="==" rhs="rainy"]
    [text text="I should bring an umbrella."]
[else]
    # This runs if it's not sunny OR rainy (e.g., cloudy or snowy)
    [text text="The sky looks interesting today."]
[endif]

Arguments

This tag does not take any arguments.

Tips

Final Catch-all:

• Use [else] to handle any scenarios you didn't explicitly cover in your [if] or [elseif] checks.
• It ensures the game always has a valid path to follow.

Placement:

• [else] must be placed after all [elseif] tags (if any) and immediately before the [endif] tag.
• You can only have one [else] per [if] block.

Optional Nature:

• You don't have to include an [else] block.
• If no conditions are met and there is no [else], the engine will simply skip everything and continue after the [endif].

---

endif

End Conditional Branch

The endif tag marks the end of a conditional block started by an [if] tag. It tells the engine to resume normal script execution after the branching logic is complete.

Basic Usage

[if lhs="${love_points}" op=">=" rhs="50"]
    [text text="She gives you a warm smile."]
[else]
    [text text="She greets you politely."]
[endif]

# Script execution continues here regardless of the outcome above
[text text="The day continues..."]

Arguments

This tag does not take any arguments.

Tips

Mandatory Closing:

• Every single [if] tag must have a corresponding [endif].
• Think of them like a pair of brackets that keep your story's logic organized.

Placement:

• Always place [endif] at the very end of your conditional sequence, following any [elseif] or [else] blocks.

Nesting:

• If you put an [if] inside another [if], make sure each one has its own [endif].
• Proper nesting is the secret to complex, bug-free story flags!

---

load

Load Script File

The load tag switches the current script to a different NovelML file. It is primarily used to organize large stories into multiple chapters or to transition between different game parts like a title screen and the main story.

Basic Usage

# Load and start from the beginning of scene02.novel
[load file="scene02.novel"]

# Load scene02.novel and jump directly to a specific label
[load file="scene02.novel" label="chapter2_start"]

Arguments

Tips

Project Organization:

• Instead of writing your entire game in one giant file, use [load] to break it down into manageable chunks like chapter1.novel, chapter2.novel, and so on.

Immediate Transition:

• When the engine hits a [load] tag, it stops executing the current NovelML file immediately and switches to the new one.
• Any commands placed after [load] in the original file will not be executed.

Global Flags:

• Don't worry about your variables — any values you've set with the [set] tag will persist even after you load a new script file!

---

se

Play Sound Effect

The se tag plays a sound effect (SE). Sound effects are used for short audio cues like door knocks, footsteps, or UI feedback, adding a layer of immersion and realism to your scenes.

Basic Usage

# Play a sound effect once
[se file="door_open.ogg"]

# Stop all currently playing sound effects
[se file="none"]

Arguments

Tips

Required Format:

• Like BGM, Suika3 requires SE files to be in Ogg Vorbis format.
• The sampling rate MUST be 44,100Hz to ensure high fidelity and compatibility.

Layering Sounds:

• Sound effects can usually be played while BGM is running.
• They occupy their own audio track so they won't interrupt your music.

Volume Control:

• To adjust the loudness of your sound effects without changing the BGM volume, use the [volume] tag with track="se".

Usage for Ambience:

• While SE is often used for short sounds, you can also use it for looping ambient sounds (like wind or rain).
• A looped SE is restored when a save data file is loaded.

---

volume

Set Audio Volume

The volume tag sets the sound volume for a specific audio track. It's perfect for ensuring that your background music doesn't drown out important sound effects or character voices.

Basic Usage

# Set BGM volume to 50%
[volume track="bgm" volume="0.5"]

# Set SE volume to maximum
[volume track="se" volume="1.0"]

# Mute voices
[volume track="voice" volume="0.0"]

Arguments

Track Types (track)

Suika3 categorizes audio into three main tracks:

Tips

Immediate Change:

• The volume change happens gradually when time is greater than 0.
• time="0" means an immediate change.

Default Levels:

• It's a good idea to set your preferred volume levels at the start of your game (e.g., in a start label) so the player has a consistent experience from the beginning.

---

skip

Set Skip Status

The skip tag enables or disables the skipping function within the game. It is useful for preventing players from skipping through important cinematic sequences or ensuring that certain scenes are experienced at the intended pace.

Basic Usage

# Enable the skip function
[skip enable="true"]

# Disable the skip function during a critical scene
[skip enable="false"]

Arguments

Tips

Cinematic Control:

• Skip feature is typically disabled before the title logo at startup.

Restoring Settings:

• Don't forget to set [skip enable="true"] once the critical scene is over.
• Players usually appreciate having the freedom to skip through text they've already seen.

System Behavior:

• This tag controls the overall "Skip" state of the engine.
• Even if the player presses a skip hotkey, the engine will ignore it if enable is set to false.

---

config

Set Configuration Value

The config tag allows you to modify the game system's configuration settings directly from the markup. It is essential for dynamically adjusting the game's UI, such as moving the message box or changing system-level parameters on the fly.

Basic Usage

# Change the position of the message box
[config name="msgbox.x" value="100"]
[config name="msgbox.y" value="200"]

# Update a specific system setting
[config name="msgbox.font.size" value="24"]

Arguments

Tips

UI Customization:

• You can use [config] to reposition the message box during specific scenes to create a more cinematic feel.

Dynamic Adjustments:

• Since this tag can be called anywhere in your script, you can change the game's "look and feel" as the story progresses.
• For example, shifting the UI for a "flashback" sequence.

Parameter Names:

• Be careful with the name argument!
• It must exactly match the internal configuration keys defined in your Suika3 project settings.
• See also the complete list of the configurations

---

layer

Direct Layer Manipulation

The layer tag allows for direct control over specific image and text layers. While tags like [bg] and [ch] are easier for standard scenes, [layer] gives you the precision to modify any individual layer's position, scale, and rotation independently.

Basic Usage

# Load an image directly onto the center character layer (chc)
[layer name="chc" file="heroine_smile.png"]

# Adjust only the position and opacity of the background (bg)
[layer name="bg" x="100" y="100" alpha="128"]

# Rotate the face layer
[layer name="chf" rotate="45.0" center-x="100" center-y="100"]

Arguments

Common Layer Names (name)

Suika3 has a rich set of predefined layers.

Here are the complete list of the layers:

Tips

Precision Control:

• Use [layer] when you want to load an image to a layer manually when you're working with custom effect layers (eff1 etc.) that don't have dedicated tags.

Instant Updates:

• Unlike [ch] or [bg], the layer tag usually updates the screen instantly.
• If you want to animate these changes over time, you should use the [move] tag instead!

Layer Hierarchy:

• Remember that layers are stacked.
• For example, chf (Face Character) is always rendered in front of chc (Center Character).
• Understanding this "Z-order" is key to complex visual compositions.

---

move

Animate Layer

The move tag animates specific layers over a set duration. It is perfect for creating sliding effects, zooming in on characters, or rotating screen elements to add dynamic energy to your scenes.

Basic Usage

# Move the center character to a new position over 2.0 seconds
[move time="2.0" center-x="150" center-y="100"]

# Relative movement: Nudge the background 50px to the right
[move time="1.0" bg-x="r50"]

# Gradually fade out a layer while rotating it
[move time="3.0" face-alpha="0" face-rotate="r360"]

Arguments

Common:

(layer):

(suffix):

Tips

Non-blocking Animation (async="true"):

• The script continues to the next command immediately after starting a [move].
• If you want the script to wait until the animation finishes, follow it with a [wait] tag using the same time value.

Relative Transformations:

• Using the r prefix (e.g., x="r100") is incredibly useful for repetitive motions, like making a character "jump" or "shake" without calculating absolute coordinates.

Visual Polish:

• Combine scale-x and scale-y with move to create "zoom-in" effects on a character's face for dramatic close-ups!

---

pencil

Pencil

Draw a text on a layer.

Basic Usage

[pencil layer="bg" font-size="30" text="Hello, World!"]

Arguments

Supported Layer Name

---

returnmacro

Return from Macro

The returnmacro tag immediately exits the current macro and returns the script execution to the line following the original [callmacro] tag. It is particularly useful for stopping a macro early based on specific conditions within an [if] block.

Basic Usage

[defmacro name="check_item"]
    [if lhs="${has_key}" op="==" rhs="false"]
        [text text="The door is locked."]
        [returnmacro]
    [endif]

    # This part only runs if has_key is true
    [text text="You unlocked the door with the key!"]
[endmacro]

Arguments

This tag does not take any arguments.

Tips

Early Exit:

• Use [returnmacro] inside an [if] block to skip the rest of a macro's commands if a certain condition is met.
• This keeps your macros flexible and powerful!

Implicit Return:

• You don't actually need to put [returnmacro] at the very end of every macro.
• Once the engine hits the [endmacro] tag, it will return to the main script automatically.

Flow Control:

• Remember that this tag only exits the current macro. It doesn't stop the whole game or jump to a different label—it just sends you back to where the macro was called from.

---

video

Play Video

The video tag plays a movie file on the screen. It is ideal for opening cinematics, transitional cutscenes, or high-impact visual effects that are best rendered as full-motion video.

Basic Usage

# Play an opening movie (cannot be skipped)
[video file="opening.mp4"]

# Play a short cutscene that the player can skip with a click.
[video file="cutscene01.mp4" skippable="true"]

Arguments

Tips

File Support:

• Ensure your video file is .mp4 (H.264 + AAC) format.
• If you want to support 32-bit Windows, prepare .wmv file alongside .mp4 file, then remove extension e.g., [video file="opening"].

Transitioning:

• Once the video finishes playing (or is skipped), the engine automatically proceeds to the next command in your script.
• It's often a good idea to follow a [video] tag with a [bg] tag to ensure the screen looks exactly how you want it after the movie ends.

Audio in Video:

• Most video files include their own audio track.
• Keep in mind that this audio will play alongside any [bgm] you have running.
• You might want to stop the music with [bgm file="none"] before starting a video with sound!

---

wait

Wait for Time

The wait tag pauses the NovelML execution for a specified duration. It is essential for controlling the pacing of visual transitions, creating dramatic pauses, or timing effects without requiring player input.

Basic Usage

# Pause for 1.5 seconds before the next command
[wait time="1.5"]

# Create a brief pause between character changes
[ch center="chara01_surprised.png" time="0.5"]
[wait time="1.0"]
[text text="She couldn't believe her eyes."]

Arguments

Tips

Non-interactive Pause:

• Unlike [click], which waits for the player to act, [wait] continues automatically once the time is up.
• This is perfect for "auto-playing" segments or timed visual sequences.

Combining with Animations:

• If you use a [ch] or [bg] tag with a time argument, the engine moves to the next command immediately while the animation plays.
• Use [wait] after an animation if you want the script to stop until the animation is finished (or even longer for dramatic effect).

User Experience:

• Be careful not to make [wait] times too long (like more than 3 seconds) without a visual reason, or the player might think the game has frozen!