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.
This command changes the background image, often called a 'bg'. After changing the background image, all character images will vanish from the stage.
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
In this example, we use the command to change the background image to sample.png
immediately.
@bg sample.png
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
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
Close eyes.
@bg #000000 1.5 eye-close
Open eyes.
@bg sample.png 1.5 eye-open
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 | Effect Name | Abbrev. Name 1 | Abbrev. Name 2 |
---|---|---|---|
fade/dissolve (alpha blending) |
normal
|
n
|
(not specified)
|
rule-based transition (1-bit) |
rule:file-name
|
||
rule-based transition (8-bit) |
melt:file-name
|
||
right curtain |
curtain-right
|
curtain
|
c
|
left curtain |
curtain-left
|
cl
|
|
up curtain |
curtain-up
|
cu
|
|
down curtain |
curtain-down
|
cd
|
|
right slide |
slide-right
|
sr
|
|
left slide |
slide-left
|
sl
|
|
up slide |
slide-up
|
su
|
|
down slide |
slide-down
|
sd
|
|
right shutter |
shutter-right
|
shr
|
|
left shutter |
shutter-left
|
shl
|
|
up shutter |
shutter-up
|
shu
|
|
down shutter |
shutter-down
|
shd
|
|
clockwise wipe |
clockwise
|
cw
|
|
counterclockwise wipe |
counterclockwise
|
ccw
|
|
clockwise wipe (20 degrees stepped) |
clockwise20
|
cw20
|
|
counterclockwise wipe (20 degrees stepped) |
counterclockwise20
|
ccw20
|
|
clockwise wipe (30 degrees stepped) |
clockwise30
|
cw30
|
|
counterclockwise wipe (30 degrees stepped) |
counterclockwise30
|
ccw30
|
|
open eyes |
eye-open
|
||
close eyes |
eye-close
|
||
open eyes (vertical) |
eye-open-v
|
||
close eyes (vertical) |
eye-close-v
|
||
open slit |
slit-open
|
||
close slit |
slit-close
|
||
open slit (vertical) |
slit-open-v
|
||
close slit (vertical) |
slit-close-v
|
Effect type mask
was removed.
Please use rule:rule-mask.png
instead.
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.
In this example we are playing sample.ogg
.
@bgm sample.ogg
In this example we are stopping the BGM.
@bgm stop
Plays BGM once.
@bgm sample.ogg once
In this example we apply a two second fade-out to the BGM
@vol bgm 0 2
@wait 2
@bgm stop
This command changes the character.
The available character positions are:
Display Position | Target Name |
---|---|
Front Center | center |
Right | right |
Left | left |
Back Center | back |
Effect types are the same as @bg
.
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
You can also abbreviate center
as c
.
@ch c sample.png 0.5
By specifying none
we can remove the character from the screen.
@ch c none 0.5
If there is no fade-in (or fade-out) time specified, our changes are applied immediately.
@ch c sample.png
Effects can also be applied to characters. (The character command can use the same effects as @bg
)
@ch c sample.png 1.0 mask
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
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
We can show a character face on the left side of the message box.
@ch face face-001.png
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.
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
This usage is similar to Usage 1, but the movement accelerates as the animation plays out.
@cha center 1.0 accel -600 0 hide
This usage is similar to Usage 1, but the movement decelerates as the animation plays out.
@cha center 1.0 brake -600 0 hide
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
This command sets the chapter title.
@chapter "Chapter 1"
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.
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
In this example we're displaying two options.
@choose label1 "Good morning." label2 "Good afternoon."
:label1
Good morning.
@goto end
:label2
Good afternoon.
:end
This command also supports single-options.
@choose label1 "Good morning."
:label1
Good morning.
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
.
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
In this example, we're vanishing the center character with a 1.0 second fade-time.
@chs none stay stay stay 1.0
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
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
This command instructs Suika2 to wait for a click before continuing. While waiting, the message box is hidden.
Waits for a click.
@click
Note: This command is not used by visual novels.
This command jumps to the specified subroutine.
Use @return
to return.
Runs subroutine SUB
.
@gosub SUB
:SUB
Describe the process here.
@return
This command jumps to a label.
You can also use @goto
to make or break loops.
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
Here we show the load screen.
Note that $LOAD
is a special label.
@goto $LOAD
Here we show the save screen.
Note that $SAVE
is a special label.
@goto $SAVE
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 log screens.
Here we display the menu GUI stored in menu.txt
.
@gui menu.txt
Allows right click cancel.
@gui menu.txt cancel
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.
Condition Type | Meaning |
---|---|
> | a > b (a is greater than b) |
>= | a ≧ b (a is greater than or equal to b) |
== | a = b (a is equal to b) |
<= | a ≦ b (a is less than or equal to b) |
< | a < b (a is less than b) |
!= | a ≒ b (a is not equal to b) |
LHS must be a variable name (e.g., $1
).
RHS must be an integer or a variable name.
This examples branches the story by jumping to the abc
label if the variable at number 1
is equal to 1
.
i.e. branches the story by flag.
@if $1 == 1 abc
Variable 1 is not 1. It means, the flag is not set.
Write story here.
@goto end
:abc
Variable 1 is 1. It means, the flag is set.
Write story here.
:end
Branched stories join here.
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.
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
In this example we're creating a simple loop.
:JumpTarget
Show some messages.
@goto JumpTarget
This command jumps to another script.
Script files need to be in the txt
folder.
In this example, we jump to the script file 001.txt
.
@load 001.txt
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.
@menu menu.png menu-selected.png START 640 480 240 120 END 880 600 240 120
:START
:END
Meanings of parameters:
menu.png
... First imagemenu-selected.png
... Second imageSTART
... Jump target label when button clicked640 480
... Top-left position of button (x, y)240 120
... Button size (width, height)
This prints text to the message box.
You can use \n
to insert a line feed and $ + number
to show the value of a variable (e.g., $1
)
You can put \
at the beginning of a line to continue the previous line. (for NVL-style)
Hello, world!
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.
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:
0
.@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
Caution: This command is not used by common visual novels.
This command is used to return from subroutines.
Run subroutine SUB
.>
@gosub SUB
:SUB
Describe the process here.
@return
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.
we'reIn this example we're simply playing a sound effect file, in this case a 'click' sound.
@se click.ogg
To stop a sound effect simply specify the stop
value.
@se stop
We can also play sound effects on repeat by specifying the loop
value.
@se sample.ogg loop
We can use the sound effects command to test voice-volume with a sound effect file without a text message.
@se click.ogg voice
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.
@select label1 label2 label3 "Good morning." "Good afternoon." "Good evening."
:label1
Good morning.
@goto end
:label2
Good afternoon.
@goto end
:label3
Good evening.
:end
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.
Here, we're printing a message with the character name.
Character names should have an *
(asterisk) on each side.
*Name*Hello, world!
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!
In this example we're printing a message with the character name and playing a beep.
*Name*@beep.ogg*Hello, world!
This sets a value to a variable.
Local variables are $0
to $9999
.
Local variables are stored independently in each save file.
Global variables are $10000 to $10999.
Global variables are stored commonly across all save data.
Note: all variables are integers and initially zero.
Available operators are as below,
but a common visual novel will usually only use =
to set a flag.
Operator Type | Meaning |
---|---|
= | a = b simply assigns b to a |
+= | a += b assigns the result of a + b to a |
-= | a -= b assigns the result of a - b to a |
*= | a *= b assigns the result of a × b to a |
/= | a /= b assigns the result of a ÷ b to a |
%= | a %= b assigns the reminder of a / b to a |
Set the value 1
to the variable $0
.
This assignment is used for flag setting.
Because the initial value of a variable is 0
,
setting value 1
to the variable means setting flag.
@set $0 = 1
Adds the value 23
to the variable $10
.
@set $10 += 23
Gets a random number which ranges from 0
to 9
and assigns it to the variable $0
.
You can use this method for random events.
@set $0 = $RAND
@set $0 %= 10
Add the value of the variable $2
to the variable $1
.
Usually, you don't need to use this feature to create a common visual novel.
@set $1 += $2
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.
Here we enable the save and load screen. [by default]
@setsave enable
Here we disable the save and load screen.
@setsave disable
This command shakes the screen.
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
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
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.
Enables skip. [by default]
@skip enable
Disables skip.
@skip disable
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.
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
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.
Play a video file.
@video sample.wmv
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".
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
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
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.
Here, we're telling Suika2 to wait for five seconds.
@wait 5.0
We express our sincere thanks to Brayden for supervising this document in 2022.
We are grateful to Maikuolan and Sherlack for improving this document in 2018 and 2021 respectively.