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. While the player is in a map whose level script has this call type, it constantly 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.

Call triggered by overworld initialization

There are three types of level script call that are executed at certain points of the overworld initialization code. These call types don't depend on variables nor the script environment and, as long as the calls are encoded in the level script file, they will always be triggered by the main game code when they have to.

Scripts called with these three types cannot use private variables, since the script engine is not initialized by the time the calls are triggered. Also, some complex script commands (mostly those which produce a visible effect) cannot be used in these types, for they also need the full script engine operative.

Call triggered by map change

The specified script will be called upon entering a map, whether by the use of a warp, a scripted warp, or simply walking into the map. Its common use consists in changing flags and variables when entering a zone. It is also very common that this type of call is used for modifying a variable that enables a triggered-by-variable level script call, so a complex script can be called when the player enters the map.

It is encoded in the form:

u8 02
u32 Script

u8 02 is the level script call type specifier (in this case, triggered by map change). u32 Script is the ID of the script executed upon entering the map.

Call triggered by screen reset

Every time the screen is reset (either by warping to the map, by opening/closing a menu, ending a battle...) the specified script will be executed.

It is encoded in the form:

u8 03
u32 Script

u8 03 is the level script call type specifier (in this case, triggered by screen reset). u32 Script is the ID of the script executed when the screen is reset.

Call triggered by overworld reset

This type seems to be called exactly in the same circumstances as the screen-reset call type, excepting that some aspects of the overworlds are not fully initialized when this type is called.

It is encoded in the form:

u8 04
u32 Script

u8 04 is the level script call type specifier (in this case, triggered by overworld reset). u32 Script is the ID of the script executed when the overworld is reset.