Guides‎ > ‎zzromtool‎ > ‎

Custom Actor Overlay Workflow

If you haven't read the intro yet, start there.

This guide builds upon principles established in the Adding Objects and Actors example. Please read it before attempting this one.

The most important prerequisite is that you have set up the environment needed to compile custom actor overlay files. Here is a guide on how to do that on Windows.

Required resources
Please use a clean rom, for the sake of reducing potential user errors. Some steps may vary if you've already added content to the game. If you haven't already, dump your rom's filesystem using zzromtool before proceeding to the next section.


First, update scene/85 with the assets provided in This will place some orange vases in the Young Link version of Kokiri Forest.

Now extract somewhere. Navigate its contents and enter the actor/seagull directory.

The zobj.zobj from actor/seagull should be placed in object/134 in your rom's filesystem, which will overwrite the orange vase object. You can rename the 134 folder to 134 - Seagull to make finding it easier.

The remaining contents of actor/seagull should be merged into actor/130 in your rom's filesystem. This is the orange vase's matching actor. You can rename the 130 folder to 130 - Seagull to make finding it easier.

A brief summary of what's what

Direct your attention to the actor/130 directory. It contains the following files:

The build script that says how to compile the actor overlay

The linker script containing the actor overlay's entry point. It's 0x80800000, and this will be a common trend with custom actors. Keep this value in mind.

The source code for the overlay. This is the code that says how to render it, how it behaves, and more.

conf.txt (contents)
Allocation        0x00000000    allocation type
Reserve           0x00000000    bytes following actor in VRAM
VRAM              0x80800000    entry point, must match entry.ld

Notice that the Initialization block is omitted. That's because we're storing the initialization data inside the actor's source code.


In that folder, Right Click > Open MSYS2 here.

In the window that pops up, type make and press the return/enter key.

If all went well, actor.zovl should be generated.

If there's anything wrong with the code, errors will be generated.


Now simply rebuild the rom and test it. If everything worked, this should be your result: