Scripting

What are scripts?

Gameboy games, in general, are written in assembly code. However, the Oracle games defined a custom scripting language in order to make it easier to control certain events - mainly dungeon puzzles and NPC behaviour.

Scripts can be used on their own, or in combination with assembly code. As a rule of thumb, scripts are used for long, sequential operations which wait for triggers and span over long periods of time; while assembly code is used when code must be run every single frame. In the case of NPCs, both scripts and assembly code are necessary. The assembly code is responsible for core functionality such as animations (which must be updated every frame), while the script is responsible for waiting for conditions (ie. Link talked to them) and telling them what to do when those conditions are satisfied.

That being said, anything that a script can do, assembly code can also can do, while the reverse is not true. However, scripts can be quite powerful on their own, and are easier to understand, making them a good place to start when it comes to implementing custom events.

Tutorials

See the tutorials page. In particular, see Scripting/Spawning a Treasure Outside a Chest for setting up your first script.

Or, learn from the game - browse the scripts/ directory and get a feel for how the developers used it.

Opcodes

A complete list of scripting opcodes can be found in include/script_commands.s. Additional information about some opcodes is provided below.

asm15 [parameter]

The "asm15" opcode calls an assembly function in bank 15 (or bank 0, which is always visible). It takes an optional parameter.

Unless the function you're calling is located in bank 0, the function should be in the "scriptHelp" namespace. By convention, in the disassembly, any code which could be used by the "asm15" opcode is located in this namespace. For example:

asm15 scriptHelp.carpenter_buildBridgeColumn, $52

Although bank 0 functions don't have a namespace, so this also works:

asm15 loseTreasure, TREASURE_TOKAY_EYEBALL

Useful functions

In addition to the standard scripting opcodes, you can use these functions with the "asm15" opcode for more useful effects.

Function name	Description
loseTreasure	Analogous to the "giveitem" opcode. See constants/common/treasure.s for what parameters to give.
removeRupeeValue	Removes some rupees based on the parameter. See the Rupee value table.
scriptHelp.blossom_checkHasRupees	Checks whether Link has a certain number of rupees. Writes 0 to var3c if he has at least that many, or 1 otherwise. See the Rupee value table.

Example

This will cause Link to lose his seed shooter:

asm15 loseTreasure, TREASURE_SHOOTER