Suika2 Command Reference

What is a Command?

A command is an instruction in Suika2's language, think of them as the building blocks that make up your game. They will almost always begin with an @ symbol and usually include at least one value. There's no need to know every command off by heart, so please refer to this page if you're unsure about how or when to use a command.

@bg

This command changes the background image, often called a 'bg'. After changing the background image, all character images will vanish from the stage.

Usage 1

In this example, we use the command to change the background image to sample.png with a 1.5 second fade-in time.

@bg sample.png 1.5

Usage 2

In this example, we use the command to change the background image to sample.png immediately.

@bg sample.png

Usage 3

In this example, we use the command to change the background image to sample.png with a 1.5 second fade-in time. You can see that we also use a fading type, in this case right curtain.

@bg sample.png 1.5 c

Usage 4

Changes the background color with a 1.5 second fade-in time. You can see that we also use a fading type, in this case left curtain.

@bg #ff8080 1.5 curtain-left

Usage 5

Close eyes.

@bg #000000 1.5 eye-close

Usage 6

Open eyes.

@bg sample.png 1.5 eye-open

Usage 7

In this example we use a rule-based transition called rule-star.png

@bg sample.png 1.5 rule:rule-star.png

You are able to specify the following effects:

Effect type mask was removed. Please use rule:rule-mask.png instead.

@bgm

This command plays background music, often called 'BGM'. BGM files need to be stored in the bgm folder. Suika2 can only play Ogg Vorbis 44.1kHz stereo and monaural format.

Usage 1

In this example we are playing sample.ogg.

@bgm sample.ogg

Usage 2

In this example we are stopping the BGM.

@bgm stop

Usage 3

Plays BGM once.

@bgm sample.ogg once

Application

In this example we apply a two second fade-out to the BGM

@vol bgm 0 2
@wait 2
@bgm stop

@ch

This command changes the character.
The available character positions are:

Effect types are the same as @bg.

Usage 1

In this example we will have sample.png fade-in for 0.5 second and display at front center.

@ch center sample.png 0.5

Usage 2

You can also abbreviate center as c.

@ch c sample.png 0.5

Usage 3

By specifying none we can remove the character from the screen.

@ch c none 0.5

Usage 4

If there is no fade-in (or fade-out) time specified, our changes are applied immediately.

@ch c sample.png

Usage 5

Effects can also be applied to characters. (The character command can use the same effects as @bg)

@ch c sample.png 1.0 mask

Usage 6

While having preset positions is helpful, sometimes it is necessary to specify an offset character position. In this following example, we'll move the character 100-pixels right and 50-pixels down from the center (c) position.

@ch c sample.png 1.0 n 100 50

Usage 7

In order to set an animation origin, load the character image with an alpha value.
Alpha values range from 0 (invisible) to 255 (completely visible). If you prefer, you can also specify show which is the equivalent to an alpha value of 255 or hide which is the equivalent to an alpha value of 0.

@ch c sample.png 1.0 n 0 0 show

Usage 8

We can show a character face on the left side of the message box.

@ch face face-001.png

@cha

This command moves a character image. To better understand this command, please refer to the @ch section for details on how to specify character positions and alpha values.

Usage 1

In this example, we're going to move the center character 600-pixels to the left and hide it with an animation that lasts 1.0 second.

@cha center 1.0 move -600 0 hide

Usage 2

This usage is similar to Usage 1, but the movement accelerates as the animation plays out.

@cha center 1.0 accel -600 0 hide

Usage 3

This usage is similar to Usage 1, but the movement decelerates as the animation plays out.

@cha center 1.0 brake -600 0 hide

Usage 4

This command also makes it possible to move characters on and off the screen. Before running @cha we can load a character image outside the screen and move it onto the screen.

@ch right sample.png 0 n 600 0 hide
@cha right 2.0 move -600 0 show

@chapter

This command sets the chapter title.

Usage

@chapter "Chapter 1"

@choose

This command shows options and jumps to the specified label. This is most often used when branching the story or offering an in-game choice to the player. You can create up to eight options with this command.

Usage 1

In this example we're displaying three options.

@choose label1 "Good morning." label2 "Good afternoon." label3 "Good evening."
:label1
Good morning.
@goto end
:label2
Good afternoon.
@goto end
:label3
Good evening.
:end

Usage 2

In this example we're displaying two options.

@choose label1 "Good morning." label2 "Good afternoon."
:label1
Good morning.
@goto end
:label2
Good afternoon.
:end

Usage 3

This command also supports single-options.

@choose label1 "Good morning."
:label1
Good morning.

@ichoose

This command shows inline options and jumps to the specified label. While @choose shows options outside the message box, this command show options inside the message box.
Note that you have to use transparent images for config switch.bg.file and switch.fg.file.
Other feature is the same for @choose.

@chs

This command has the ability to change multiple characters at once. In addition, it can change the background at the same time.
The character specification order is: center, right, left and back.
The available effects specifiers are the same as @bg.

Usage 1

In this example we are changing the center and right characters with a 1.0 second fade-time.
Note that other characters won't be changed (stay denotes no change).

@chs center.png right.png stay stay 1.0

Usage 2

In this example, we're vanishing the center character with a 1.0 second fade-time.

@chs none stay stay stay 1.0

Usage 3

In this example, we're changing the background (without any effects on the characters) with a 1.0 second fade-time.

@chs stay stay stay stay 1.0 background.png

Usage 4

In this example, we're only changing the center character and background with a 1.0 second fade-time.
We're also using a curtain effect.

@chs center.png stay stay stay 1.0 background.png curtain

@click

This command instructs Suika2 to wait for a click before continuing. While waiting, the message box is hidden.

Usage

Waits for a click.

@click

@gosub

Note: This command is not used by visual novels.
This command jumps to the specified subroutine. Use @return to return.

Usage

Runs subroutine SUB.

@gosub SUB
:SUB
Describe the process here.
@return

@goto

This command jumps to a label. You can also use @goto to make or break loops.

Usage 1

In this example, we're telling Suika2 to jump to the abc label.
Because the @goto command is included within the abc label, we also create a loop.

:abc
Describe the process here.
@goto abc

Usage 2

Here we show the load screen.
Note that $LOAD is a special label.

@goto $LOAD

Usage 3

Here we show the save screen.
Note that $SAVE is a special label.

@goto $SAVE

@gui

This command displays a GUI (graphical user interface). The GUI command is a replacement of @menu and @retrospect. You can show up to 128 buttons on the screen using this command with button types such as "jump to label" and "show if variable is set". GUI definition files (found in the GUI folder) are also used for config, save, load and history screens.

Usage 1

Here we display the menu GUI stored in menu.txt.

@gui menu.txt

Usage 2

Allows right click cancel.

@gui menu.txt cancel

@if

This command jumps to the specified label if the specified condition (a prerequisite) is true.
Available operators are as described below; however, when creating common visual novels, == (equal to) is usually sufficient.

The LHS must be one of local variable names (e.g., $1), global variable names (e.g., $10000) and name variable names (e.g., %a).
If the LHS is a local variable name or a global variable name, the RHS must be an integer value or a local and global variable name.
If the LHS is a name of a name variable, the RHS must be a string value. In this case, the variable names in the string will not be expanded into values.

Usage

This examples branches the story by jumping to the abc label if the local variable at number 1 is equal to 1. In other words, it branches the story by a flag.

@if $1 == 1 abc
The value of the local variable 1 is not 1. It means, the flag is not set.
Write story here.
@goto end
:abc
The value of the local variable 1 is 1. It means, the flag is set.
Write story here.
:end
Branched stories join here.

Label

This command creates a label, which can be used as a jump target.
You can think of labels like interactive chapter headings.
Where chapter headings change the window title, labels provide sections the game can jump to and from.
They are typically used with the @choose, @goto, @if and @menu commands.

Usage 1

In this example we're creating a simple jump from label A to C while ignoring label B.

:A
Show some messages.
@goto B

:B
These messages are skipped in this label jump!
@goto end

:C
Show some more messages.
@goto end

Usage 2

In this example we're creating a simple loop.

:JumpTarget
Show some messages.
@goto JumpTarget

@load

This command jumps to another script.
Script files need to be in the txt folder.

Usage

In this example, we jump to the script file 001.txt.

@load 001.txt

@menu

This command displays a menu using two images. You can create up to 16 buttons with @menu.
This works by displaying the first image by default, with the second image being substituted in when you hover over a button.
See the demo game for a helpful example!
Note: Menus cannot be canceled using right click.

Usage

@menu menu.png menu-selected.png START 640 480 240 120 END 880 600 240 120
:START
:END

Meanings of parameters:

• menu.png ... First image
• menu-selected.png ... Second image
• START ... Jump target label when button clicked
• 640 480 ... Top-left position of button (x, y)
• 240 120 ... Button size (width, height)

Messages

This prints text to the message box.
You can put the following special strings in messages:

• Putting \n inserts a line feed.
• Putting $ + number prints the value of a local or global variable (e.g., $1)
• Putting % + lower case alphabet prints the value of a name variable (e.g., %a)
• Putting \ at the beginning of a line continues the previous line. (for NVL-style)
• Putting \#{RRGGBB} changes font color.
• Putting \@{size} changes font size.
• Putting \w{seconds} inserts a wait.
• Putting \p{x,y} moves the pen.
• Putting 長\^{おしゃまんべ}万部 inserts a ruby.

Usage

Hello, world!

@news

Caution: This command is not used by common visual novels and is therefore not recommended.

This command is a variant of @switch. It shows the first four options on the north, east, west and south areas of the screen. The first eight options (parent options) are hidden when * is specified.

@retrospect

This command executes "event image catalog mode". You could use this command to display the CG artwork that a player has unlocked.
@retrospect is similar to @menu in its use of two images, however it has some more advanced parameter options.

The difference between @menu and @retrospect is:

• @retrospect can create up to twelve buttons.
• @retrospect can hook variables to buttons. If the value of the variable is 0, the button is hidden.
• @retrospect can be canceled using right click.

@retrospect has many parameters:

• Background image.
• Background image (selected button).
• RGB values to fill buttons when the specified variable is 0.
• The width and height of buttons.
• For each button:
  • The jump target label.
  • The variable to check.
  • The X and Y position of the button.

Usage

@retrospect menu.png menu-selected.png 0 0 0 320 240 PICTURE1 $1 320 240
Canceled.
@goto END
:PICTURE1
@bg picture1.png 1.0
@click
:END

@return

Caution: This command is not used by common visual novels.
This command is used to return from subroutines.

Usage

Run subroutine SUB.

@gosub SUB

:SUB
Describe the process here.
@return

@se

This command plays sound effects (se).
Sound effect files need to be in the se folder. Note: Suika2 can only play Ogg Vorbis 44.1kHz stereo and monaural format.

Usage 1

we'reIn this example we're simply playing a sound effect file, in this case a 'click' sound.

@se click.ogg

Usage 2

To stop a sound effect simply specify the stop value.

@se stop

Usage 3

We can also play sound effects on repeat by specifying the loop value.

@se sample.ogg loop

Special Usage

We can use the sound effects command to test voice-volume with a sound effect file without a text message.

@se click.ogg voice

@select

Caution: This command is deprecated. Use @choose instead.

This command, like @choose shows options and jumps to the specified label.
The number of options is fixed to three.

Usage :

@select label1 label2 label3 "Good morning." "Good afternoon." "Good evening."
:label1
Good morning.
@goto end
:label2
Good afternoon.
@goto end
:label3
Good evening.
:end

Messages with character names

This command is similar to messages in that it displays text in the text box.
However, it also prints a character name to the name box.
Suika2 can also play voice files when printing messages. Voice files need to be in the voice folder. Note: As previously mentioned, Suika2 can only play the Ogg Vorbis 44.1kHz stereo and monaural format.

Usage 1

Here, we're printing a message with the character name.
Character names should have an * (asterisk) on each side.

*Name*Hello, world!

Usage 2

Here we're printing a message with the character name as well as plaing the character's voice.
Note: In this case we add an * between the name and audio file while still maintain one on each side.
(This means we should have three *.)

*Name*001.ogg*Hello, world!

Usage 3

In this example we're printing a message with the character name and playing a beep.

*Name*@beep.ogg*Hello, world!

@set

This sets a value to a local, global, or name variable.
The local variables range $0 to $9999. They are stored independently in each save file.
The global variables range $10000 to $10999. They are stored commonly across all save data.
Note: all local and global variables have a integer value and initiallized by zero.
The name variables range %a to %z. They are stored independently in each save file.
Note: all name variables have a string value and initialized by an empty string.
Available operators are as below, but a common visual novel will usually only use = to set a flag. In addition, the assignment (=) is the only operator for name variables.

If the LHS is a local or global variable name, the RHS can be one of a integer value, a local variable name and a global variable name.
If the LHS is a name of a name variable, the RHS must be a simple string, and the variable names in the string will not be expanded into their values.

Usage 1

Sets the value 1 to the local variable $0.
This assignment is used for a flag setting. Because the initial value of a local variable is 0, setting value 1 to a local variable means setting a flag.

@set $0 = 1

Usage 2

Adds the value 23 to the local variable $10.

@set $10 += 23

Usage 3

Gets a random number that ranges 0 to 9 and assigns it to the local variable $0. You can use this method for random events.

@set $0 = $RAND
@set $0 %= 10

Usage 4

Adds the value of the local variable $2 to the local variable $1.
Usually, you don't need to use this feature to create a common visual novel.

@set $1 += $2

Usage 5

Sets the string value midori to the name variable %a.
This method is useful to set a default value to a name variable.

@set %a = midori

@setsave

Caution: This command is not used by common visual novels.
This command enables or disables the save and load screen which is called by right clicking while waiting for message click or option click. When you call @goto $LOAD or @goto $SAVE, @setsave enable is implicitly called.

Usage 1

Here we enable the save and load screen. [by default]

@setsave enable

Usage 2

Here we disable the save and load screen.

@setsave disable

@shake

This command shakes the screen.

Usage 1

In this example we're shaking the screen three times horizontally by 100-pixels over 1.0 second. Note: horizontal can be abbreviated to h.

@shake horizontal 1.0 3 100

Usage 2

In this example we're shaking the screen three times vertically by 100-pixels over 1.0 second. Note: vertical can be abbreviated as v.

@shake vertical 1.0 3 100

@skip

This command enables or disables the ability to skip timed commands with user interaction.
A good use for this command is displaying a brand or game logo during boot time.
You can also use this command to enable and disable a user's ability to skip messages during sections of gameplay. If you wish to do this however, you have to use @setsave disable to inhibit the save and load screen, as no-skip mode is not saved to the save file. In addition, don't use @goto $LOAD and @goto $SAVE while in no-skip mode, this is for similar reasons.

Usage 1

Enables skip. [by default]

@skip enable

Usage 2

Disables skip.

@skip disable

@switch

Note: This command is not recommended. Use @choose instead.

This command shows two-level options. There are eight parent options, and each parent option has eight child options.

Usage

This example shows two levels of two options, four in total.

@switch "Parent option 1" "Parent option 2" * * * * * * LABEL1 "Child option 1" LABEL2 "Child option 2" * * * * * * * * * * * * LABEL3 "Child option 3" LABEL4 "Child option 4" * * * * * * * * * * * *
:LABEL1
:LABEL2
:LABEL3
:LABEL4

@video

This command plays a video file. At the moment, this functionality is enabled on Windows and Mac only.
On Windows, please use the .wmv video file format. On Mac, please use the .mp4 video file format.
Video files are stored in the mov directory. Note: The mov directory is not stored in data01.arc file.

Usage

Play a video file.

@video sample.wmv

@vol

This command sets the sound volume.
Sound tracks are, in lower case, bgm for BGM, voice for voice, se for sound effects.
The sound volumes of these three tracks are stored in each local save file. You can change the volumes frequently for sound production purposes. The initial values of all sound volumes are 1.0. They can range from 0.0 to 1.0. 0.0 means muted and 1.0 means max.
If you want to set "global volumes" which are common between save files, you can specify the track name in UPPER CASE. Global volumes indicate volumes which are set in the game config screen. When you set the global volumes, set fading time to 0.
Note: Actual output volume is "volume for save data × global volume".

Usage 1

Here we're setting the BGM volume to 0.5, the volume will fade-in or fade-out dependent on its original value over 1.0 second. bgm can be abbreviated as b.

@vol bgm 0.5 1.0
@wait 1.0

Usage 2

This is an example of setting the global volume. (In this case, we're setting the BGM to 0.5) (this is useful when you create sound config menu.)

@vol BGM 0.5 0

@wait

This command instructs Suika2 to wait for a specified time. Input from the keyboard or mouse will interrupt @wait (thus allowing Suika2 to continue).
If the previous command is a message, the message box is visible while waiting for input. Otherwise, the message box is hidden while waiting for input.

Usage

Here, we're telling Suika2 to wait for five seconds.

@wait 5.0

@wms

@wms [file]

Execute a WMS (Watermelon Script).

Usage

Execute hello.txt.

@wms hello.txt

@anime

@anime [file] (options)

Execute an animation file. Animation files must be stored in the folder anime. Currently (Suika2/12.26), we don't support rotate and scale, but we'll support them no later than Suika2/13.0.

Usage1

Execute anime1.txt.

@anime anime1.txt

Usage2

Execute anime1.txt. Don't show the collapsed system menu.

@anime anime1.txt nosysmenu

Usage3

Execute anime1.txt with showing the message box.

@anime anime1.txt showmsgbox

Sample animation file

# Animation File

# Move center character twice.
move {
    layer: chc;  # CHaracter Center
    clear: chc;  # Clear existing animations for the layer (only needed for the first move of the layer)
    start: 0.0;  # Start at time 0.0s
    end: 2.0;    # End at time 2.0s
    from-x: 0;   # X coordinate to start
    from-y: 0;   # Y coordinate to start
    from-a: 255; # Alpha value to start
    to-x: 100;   # X coordinate to end
    to-y: 100;   # Y coordinate to end
    to-a: 255;   # Alpha value to end
}
move {
    layer: chc;  # CHaracter Center
    start: 2.0;  # Start at time 2.0s
    end: 4.0;    # End at time 4.0s
    from-x: 100; # X coordinate to start
    from-y: 100; # Y coordinate to start
    from-a: 255; # Alpha value to start
    to-x: 0;     # X coordinate to end
    to-y: 0;     # Y coordinate to end
    to-a: 255;   # Alpha value to end
}

# Simultaneously, move the right character.
move {
    layer: chr;  # CHaracter Right
    clear: chr;  # Clear existing animations for the layer (only needed for the first move of the layer)
    start: 0.0;  # Start at time 0.0s
    end: 3.0;    # End at time 3.0s
    from-x: 1000;# X coordinate to start
    from-y: 0;   # Y coordinate to start
    from-a: 255; # Alpha value to start
    to-x: 0;     # X coordinate to end
    to-y: 0;     # Y coordinate to end
    to-a: 255;   # Alpha value to end
}

Acknowledgements

Initial reference planned and written by ktabata.

English documentation revised and edited by Kyou (2022 –).

We are grateful to Maikuolan and Sherlack for improving this document in 2018 and 2021 respectively.