Level script (Gen IV)

Level scripts are special script files that are executed under specific circumstances, most of them related with the overworld initialization process. They don't contain normal script commands, since their only task is to call scripts of the local script archive (the ones editable with SDSME, PPRE or DSPRE). The binary file of level scripts is formed by the concatenation of encoded call commands. There are 4 call types in Generation IV level scripts.

End

Ends the level script. It is encoded in one byte only.

u8 00

Call triggered by variables

Possibly the most important in terms of practical use. It compares the value of a variable with a specific value, and calls a script if they are equal. Unlike the other types of level script calls, this one is linked to an hexadecimal structure (the conditional structure) that is declared at the end of the level script file, right after the End command.

Complex scripts that make use of commands like Message or ApplyMovement can only be called with this kind of level script. Any other call type would result in a crash. This is because the other level script call types are executed before the overworld is fully initialized.

The conditional structure is an array of three u16 elements, following the format:

u16 V: Variable

u16 E: Expected value of the variable

u16 S: Script that is called in case that V equals E

These three numbers can be repeated so many times as necessary, so that the same variable or different variables can appear with different expected values. The structure must end with 00 00, which we can consider a local end.

Here is an example of a possible conditional structure of a level script:

80 40 01 00 01 00 80 40 02 00 03 00 81 40 01 00 04 00 00 00

It doesn't make much sense until it's ordered properly:

80 40 | 01 00 | 01 00 ----> IF (0x4080 == 0x0001) then CALL Script_#1

80 40 | 02 00 | 03 00 ----> IF (0x4080 == 0x0002) then CALL Script_#3

81 40 | 01 00 | 04 00 ----> IF (0x4081 == 0x0001) then CALL Script_#4

00 00 ----> Local end

This conditional structure needs to be called from the main segment of the level script file, encoded this way.

u8 01
u32 Distance

u8 01 is the level script call type specifier (in this case, triggered by variables). It's the only call type that depends on an additional structure, the conditional structure we explained above. u32 Distance is the amount of bytes, counting after the u32 Distance itself, where the start of the conditional structure is located in the level script file.

Since the other level scripts encoded calls occupy 5 bytes (one byte for the level script type specifier, 4 bytes for the script identifier), and the level script End takes 1 byte only (always u8 00), the value of u32 Distance should usually equal (1 + 5 * N), being normally 01 00 00 00 or 06 00 00 00.