Documentation for the file format used for Story scripts.

The usual file encryption is used, get the keys from the adv_script table in the assets database.

These values should be defined somewhere in the header according to the Jigbox.NovelKit.AdvScriptDataHeader class: CompressedMask, HasResourceMask, DataInfomationByte, DataBeginIndexBeginByte, ResourceBeginIndexBeginByte, DataLengthBeginByte, ResourceLengthBeginByte, CheckByteBeginByte, NonceBeginByte, KeyNonceBeginByte. There's 22 bytes left in all the headers I've seen so far, which implies four of these are 4-byte integers and the rest are single bytes. No idea which is which, though.

AdvScript files are compressed by using length-distance pairs (comparable to LZ77).

A copy instruction starts with the identifier byte defined in the file header. The following byte is the offset, the one after that is the match length. To decompress the data stream, the copy instruction must be replaced by length + 1 bytes read from the data stream rewound by offset bytes from the last written byte.

Note that length can be greater than offset, in which case a sequence can be repeated several times - for example, using identifier byte 0x80, the byte sequence 11 22 33 80 02 05 would decompress into 9 bytes: 11 22 33 11 22 33 11 22 33.

One must take care that copy instructions are only handled outside of completed characters - the identifier byte may occur within a multibyte UTF-8 character, especially full width punctuation, but does not represent a copy instruction in that case.

Once the header is removed and the file is decompressed, you have the actual AdvScript script, a text file in UTF-8 encoding.

The first line of an AdvScript script has some cool values that probably mean something.

Files that should be imported are listed from line 2, containing things such as prefabs or constants to use later.

The line containing only #main ends the import list and begins the main section, where AdvScript commands are listed to be played back when the player watches the story.

Each command is one line in the script, and arguments are split by half-width spaces (0x20). Leading/trailing spaces must be ignored, multiple consecutive spaces are treated as a single space. Since spaces split arguments, if they're needed for anything (a textbox label, a message, a dialogue option…), surrounding text with pipes like this escapes them: ||I can use spaces||.

Many commands deal with “planes”, where backgrounds, characters and effects can be placed on. It's easier to think of them as layers. All planes are shown at once (with some exceptions like phone mode), and elements on them can be shown and hidden on demand. However, only one background/character/effect/… each can exist per plane.

<label> <message> [voice] [skip_pause]

label: If the command in the first argument is not known, it is interpreted as a Text command. The message box pops up and displays the given text. The first argument, which would usually be the command name, is used as the label for the box, showing the speaker of the text. This can be any unicode string, but the string [player] is replaced by the player's chosen nickname.

message: The message to display. Some simple HTML-like styling is supported, check the Markup section below.

voice (optional): The ID of the voice clip to play when this message box appears.

skip_pause (optional): If this argument is set to +, the script will immediately continue instead of waiting for the player to click. Usually used if delay commands are neccessary, which will be followed by a waitclick command.

# marks a label that can be jumped to (see goto and select).

backeffection <enable/disable>

chat <open/close>

changewindow <window_type>

1: Regular bottom message box.

2: Full-screen message box without speaker label.

3: Message bubbles for chat mode.

clear

Hides the message box after it was displayed by a Text command.

click <enable/disable>

Whether to allow the user to click the screen to move forward in the script. Can be used with delays or waittext to avoid the user accidentally breaking animations and such.

delay <duration>
[command]
[command]
[command]
...
enddelay

Opens a block in which all commands will only be executed after a certain wait time. The script is not paused, a timer is set instead. The block is closed by an enddelay instruction. If waits or pauses following this command are interrupted by the player, any unfinished delay blocks are immediately executed.

This is usually used to have character sprites animate at certain points during a voice line. A non-pausing Text command is used, followed by one or more delay blocks for each animation, and finished with a waitclick command.

duration: In seconds, can be a decimal.

command: A list of any number of commands to be executed once the timer finishes.

effection <enable/disable>

See delay.

eyeblink <enable/disable>

fade <in/out> <layer?> <duration> [color]

If color is not set, it will default to black.

fadesetting type <fade_type>

AlternateStripeHorizontal: horizontally striped, each stripe wiping alternating between wiping left to right and right to left

Circle

Default: uniform fade

Horizontal: horizontal wipe left to right

Round: rotating wipe from top, going clockwise (the “time passing” fade)

SlimStripeHorizontal: like StripeHorizontal but thinner

StripeHorizontal: vertically striped, each stripe wiping horizontally left to right

StripeVertical: horizontally striped, each stripe wiping vertically top to bottom (“blinds transition”)

Vertical: vertical wipe top to bottom

fadesetting flip <enable/disable>

Whether to rotate the fade animation 180 degrees.

goto <label>

Jumps to the given label and executes commands from there.

letterbox <show/hide> [duration] [size]% [plane]

duration: Duration of the animation that both moves and fades the borders, in seconds

size: Size of the borders relative to the screen, in percent. This is per border, not in total - so 50% will cover the entire screen.

plane: Which plane to show the borders on.

When chat is open and the window type is 3 (message bubbles), this adds the member avatar next to the message bubble created by the next Text command.

phone set <plane>

Sets up the phone module, using plane as the displayed plane number for commands such as bg and ch.

phone open

Plays the phone opening animation (sliding up from the center of the bottom edge)

phone close

Plays the phone opening animation (sliding down)

phonepos /<x> /<y>

The / is required (?). Can be used to place the phone off-center.

sic

pillerbox <show/hide> [duration] [size]% [plane]

See letterbox.

For cutins

recollect <enable/disable>

select <text> <label>

Shows dialogue options for the player character. If a select command is read, all following select commands are also processed. The script is then paused and all selections are shown as an option list for the player, with the given display text on the buttons. If a button is pressed, the script jumps to the given label and resumes.

textmode <textmode_type>

Normal: The default mode, where each Text command clears the message box and only displays the text from that one command.

Additive: Will not automatically clear the message box for each Text command, and allows appending text to an existing one. The clear command can still be used to manually empty message boxes. Note that text will be appended directly without line breaks, so if you want them you must add a <br/> tag at the end of the previous message or at the start of the new message.

AdditiveNewLine: Will not automatically clear message boxes like Additive, but will add a double new line for each new Text command automatically (so that there is a blank line in-between).

viewing <enable/disable>

Show or hide the top right menu buttons.

wait <duration>

Pauses the script for a certain amount of time. Cannot be skipped by the player.

duration: In seconds, can be a decimal.

waitclick

Pauses the script until the user clicks the screen. Usually used after a non-pausing Text command once the delay commands after it were executed.

waittext

Pauses the script until the text typing animation finishes for the previous Text command. Usually used after a non-pausing Text command, combined with textmode set to Additive and some delay commands, this allows delaying parts of a message box.

waitload

Pauses the script until all preloads started before this command finish.

In the message of Text commands, AdvScript supports some HTML-like markup to style the text. While some name and attributes might be different, it generally works just like HTML.

<br/>

A linebreak.

<span size="number" spacing="number">...</span>

Apply a style to the text between the tags. All attributes are optional.

size: Text size. Default text size seems to be about 28?

spacing: Distance between characters, can be set to “0” to remove any spacing.