GUI

Introduction

GUI is Suika3's UI/UX creation feature.

In Suika3, buttons are defined in a dedicated GUI mode and operate in a synchronous manner, that is, calling a GUI results in a button click or a cancel.

Asynchronous callbacks such as showing buttons while text tag execution are intentionally avoided because they can be difficult for beginner programmers to understand and manage.

A GUI file contains a list of button definitions. Each button includes a behavior type, idle and hover images, and additional properties. Buttons are mapped to animation layers, and animation files can be triggered when a button's state changes.

---

GUI Sample

# Global settings section.
global {
    fadein:       0.2;            # Fading-in time in seconds.
    fadeout:      0.2;            # Fading-out time in seconds.
}

# A block describes a button.
# The name of a block can be whatever you like and it won't affect anything.
button1 {
    # Layer ID (`1`-`32`)
    # `1` means the top-most and `32` means the bottom-most in the GUI layers, respectively.
    id: 1;
 
    # Behavior Type (`goto` means go to a label when clicked.)
    type: goto;

    # Label to go to.
    label: button1_clicked;

    # Position
    x: 39;
    y: 99;

    # `width:` and `height:` are omissible as they can be inferred from the image size.

    # Images
    image-idle:  gui/item-idle.png;    # Shown when the button is not pointed.
    image-hover: gui/item-hover.png;   # Shown when the button is pointed.
    image-press: gui/item-press.png;   # Shown when the button is pressed.

    # Animations
    anime-idle:  gui/item-idle.anime;   # Executed when the button state is changed to `idle`.
    anime-hover: gui/item-hover.anime;  # Executed when the button state is changed to `hover`.
    anime-press: gui/item-press.anime;  # Executed when the button is pressed.

    # Note that `press` is not an independent state, it's an additional flag to the state `hover`.
    # When a `hover` anime runs, `idle` anime will be canceled.
    # And when `idle` anime runs, `hover` anime will be canceled.
    # However, `press` anime doesn't cancel anything.
}

In the global section, you can specify options for the GUI.

Other sections are interpreted as button definitions. Here, button1 makes a button at position (39, 99). If the button is clicked, a jump so called goto will happen.

---

Button Types

noaction

A non-clickable image.

background {
    type: noaction;
    x: 0;
    y: 0;
    image-idle: idle.png;
}

goto

A clickable button. When clicked, tag execution jumps to a label specified by label: parameter.

button1 {
    type: goto;
    label: label_clicked_button1;
    x: 0;
    y: 0;
    image-idle:  idle.png;
    image-hover: hover.png;
}

gui

A clickable button. When clicked, GUI execution is chained to a new GUI specified by file: parameter.

button1 {
    type: gui;
    label: gui2.gui;
    x: 0;
    y: 0;
    image-idle:  idle.png;
    image-hover: hover.png;
}

mastervol

A slider to set the master volume.

slider1 {
    type: mastervol;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Slider base bar
    image-hover: hover.png;  # Slider base bar (bright)
    image-knob:  knob.png;   # Slider knob
}

bgmvol

A slider to set the BGM volume.

This slider sets the volume to be stored in the global save data file. This is defferent than the volume to be set by the [volume] tag and stored in the local save data.

slider1 {
    type: bgmvol;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Slider base bar
    image-hover: hover.png;  # Slider base bar (bright)
    image-knob:  knob.png;   # Slider knob
}

sevol

A slider to set the SE volume.

This slider sets the volume to be stored in the global save data file. This is defferent than the volume to be set by the [volume] tag and stored in the local save data.

slider1 {
    type: bgmvol;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Slider base bar
    image-hover: hover.png;  # Slider base bar (bright)
    image-knob:  knob.png;   # Slider knob
}

voicevol

A slider to set the SE volume.

This slider sets the volume to be stored in the global save data file. This is defferent than the volume to be set by the [volume] tag and stored in the local save data.

slider1 {
    type: bgmvol;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Slider base bar
    image-hover: hover.png;  # Slider base bar (bright)
    image-knob:  knob.png;   # Slider knob
}

charactervol

A slider to set a per-character volume.

Character index is passed by the index: parameter. index 0 is for non-defined character, and 1-32 for defined characters.

slider1 {
    type: charactervol;
    index: 1;  # Character Index
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Slider base bar
    image-hover: hover.png;  # Slider base bar (bright)
    image-knob:  knob.png;   # Slider knob
}

textspeed

A slider to set the text speed.

slider1 {
    type: textspeed;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Slider base bar
    image-hover: hover.png;  # Slider base bar (bright)
    image-knob:  knob.png;   # Slider knob
}

autospeed

A slider to set the auto mode speed.

slider1 {
    type: textspeed;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Slider base bar
    image-hover: hover.png;  # Slider base bar (bright)
    image-knob:  knob.png;   # Slider knob
}

preview

A text area to preview the font, language, and speed.

preview1 {
    type: preview;
    x: 0;
    y: 0;
    image-idle: idle.png;
}

fullscreen

A clickable button. When clicked, the engine will enter a full screen mode.

fullscreen1 {
    type: fullscreen;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
    image-disable: disable.png;  # For when in the full screen mode.
}

window

A clickable button. When clicked, the engine will enter a windowed mode.

window1 {
    type: window;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
    image-disable: disable.png;  # For when in the windowed mode.
}

default

A clickable button. When clicked, it resets all settings.

reset1 {
    type: default;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}

savepage

A clickable button. When clicked, it switches the save screen page.

savepage1 {
    type: savepage;
    index: 0; # Page index (0-)
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
    image-active:  active.png;  # For when the page is active.
}

save

A clickable button. When clicked, it executes a save.

save1 {
    type: save;
    index: 0; # Index in apage. actual save slot = page * saveslots + index

    x: 0;
    y: 0;

    image-idle: system/save/save-item-idle.png;
    image-hover: system/save/save-item-hover.png;

    index-x:   10;   # Number
    index-y:   0;
    date-x:    60;   # Date
    date-y:    0;
    thumb-x:   27;   # Thumbnail
    thumb-y:   77;
    chapter-x: 260;  # Chapter title
    chapter-y: 48;
    msg-x:     260;  # Last message
    msg-y:     96;
}

load

A clickable button. When clicked, it executes a load.

load1 {
    type: load;
    index: 0; # Index in apage. actual save slot = page * saveslots + index

    x: 0;
    y: 0;

    image-idle: system/load/load-item-idle.png;
    image-hover: system/load/load-item-hover.png;

    index-x:   10;   # Number
    index-y:   0;
    date-x:    60;   # Date
    date-y:    0;
    thumb-x:   27;   # Thumbnail
    thumb-y:   77;
    chapter-x: 260;  # Chapter title
    chapter-y: 48;
    msg-x:     260;  # Last message
    msg-y:     96;
}

auto

A clickable button. When clicked, it start Auto Mode.

auto1 {
    type: auto;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}

skip

A clickable button. When clicked, it start Skip Mode.

skip1 {
    type: skip;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}

title

A clickable button. When clicked, the engine goes back to the specified NovelML file.

title1 {
    type: title;
    file: title.novel;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}

history

A clickable button. It shows a message history item.

history {
    type: history;
    index: 0; # Index in a page
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;

    name-x: 20;   # Name
    name-y: 10;
    text-x:  20;  # Text (for when there is a name)
    text-y:  50;
    msg-x:  20;   # Message (for when no name)
    msg-y:  10;
}

historyscroll

A vertical scroll bar for history screen.

scroll1 {
    type: historyscroll;
    x: 1200;
    y: 40;

    image-idle:  system/history/history-bar-idle.png;
    image-hover: system/history/history-bar-hover.png;
    image-knob:  system/history/history-bar-knob.png;
}

historyscroll-horizontal

A horizontal scroll bar for vertical writing history screen.

scroll1 {
    type: historyscroll-horizontal;
    x: 40;
    y: 650;

    image-idle:  system/history/history-bar-idle.png;
    image-hover: system/history/history-bar-hover.png;
    image-knob:  system/history/history-bar-knob.png;
}

cancel

A clickable button. When clicked, the GUI will be canceled.

cancel1 {
    type: cancel;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}

var

A text area to show a variable value. It is used for name editing.

var1 {
    type: var;
    variable: variable_name;
    x: 0;
    y: 0;
    image-idle:    idle.png;
}

char

A button to append a character to a variable. It is used for name editing.

char1 {
    type: char;
    variable: variable_name; # Variable name.
    msg: A;                  # Text to append.
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}

language

A button to switch the language.

language_english1 {
    type: language;
    langu: en;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
    image-disable: disable.png; # For when English is active.
}

---

Common Button Options

pointse:

pointse: btn-change.ogg; indicates a sound effect file is played back when the mouse cursor enters the button.

clickse:

clickse: click.ogg; indicates a sound effect file is played back when the button is clicked.