Modification and Addition of Switches

From z64 wiki
Revision as of 06:40, 28 July 2013 by Spinout (talk | contribs) (Credits)
Jump to: navigation, search

Notes by Petrie911 (Switches, Doors, Chests, and All That Jazz: A guide to dungeon infrastructure)

Probably the biggest part of Zelda hacking is making your own dungeons.  The Utility of Time is great for changing your actors and moving them around, but it won't help you design the dungeon itself.  If you want to make a good, solid, Ocarina-of-Time-style dungeon, you're going to need to understand the basic elements that create a dungeon.

Also, a quick note.  I refer to a single hexadecimal digit as a "hex".  This is not standard usage, but I feel nybble and hexit sound stupid.  Anyways, on with the guide.


Flags are a way of storing events that have occurred in the game in a compact manner.  One flag is stored within a single bit, giving us two possible states: 0 and 1. Changing a flag to 1 is called setting the flag, and changing it to 0 is called clearing it.  Thus, if a flag is cleared, it is 0, and if the flag is set, it is 1.  Typically a flag will start out as 0.

Objects that react to a flag being cleared or set are said to be attached to it.  If they react when the flag is set, they are said to be rising-edge triggered.  Those that react when the flag is cleared are falling-edge triggered.  An object attached to a flag can be both rising- and falling-edge triggered.

There are a few different types of flags that an actor can be attached to.

Scene-Level Flags

Scene-level flags are flags which store states for a given scene.

Switch Flags

Switch Flags are by far the most important group of flags.  They control just about everything in the scene not mentioned elsewhere.  There are 64 switch flags in a scene, which can be divided into three groups.

00-1F -- Permanent flags -- retain their values when you leave the current scene, and are not affected by other scenes
20-37 -- Temporary flags -- cleared when you leave a scene via specific type of exit? (typically on leaving a dungeon)
38-3F -- Local flags -- cleared every time you change rooms

There are a few important things to note.

Farore's Wind saves the values of the temporary flags as they were when entering the room when cast.  When you warp back to the room you cast it in, it writes these values back into the temporary flags, regardless of what their current values are.  This holds true even if you are warping between two different rooms of the same dungeon.

It is generally good idea to never attach anything to switch flag 3F. Several actors use "attached to 3F" as a shorthand for "not attached to anything" or "attached to clear trigger".  It can be done, but it'll save you a lot of headache to just not do it.

It is a bad idea for two adjacent rooms to use the same local flag.  This is because the next room will load before the flags are cleared, and you may set off things in the next room you didn't intend to.

Lastly, in dungeons with a boss key, switch 0x14 is reserved for the boss door.  Don't use it.

The RAM address for the current scene's switch flags is 0x00213D48.

Collectible Flags

Collectible flags are a group of flags set or read by actors that give out collectible items. Like switch flags, there are 64 collectible flags within each scene, they follow the same format, and have the same limitations.

00-1F -- Permanent flags -- Typically Heart Pieces or Keys
20-37 -- Temporary flags -- Pots, free hearts
38-3F -- Local flags

Chest Flags

Chest flags are a distinct group of flags set only by the Chest actor (000A). Each scene stores its own set of 32 chest flags.  If multiple chests share the same chest flag, opening one will cause all other chests attached to that flag to be open as well.

Which flag a chest is attached to is determined by its actor variable.


000A WYY0 + 00ZZ, Object 000E

W  - The type of chest.  See below for a list
YY - Contents of chest.  Always even.
ZZ - Chest flag.  Ranges from 00 to 1F.

For a list of chest contents YY, see the Actor List.

The RAM address for the current scene's chest flags is 0x00213D58.

Clear Triggers

Clear Triggers are another distinct group of flags. They determine whether all the enemies within a particular room have been defeated. Each scene has up to 32 clear triggers, one per map/room.  However, since no scene has 32 rooms (Spirit Temple comes closest with 29), they will not all be used.

The way the clear trigger works is very simple. First you must have an actor which attaches itself to the room's clear trigger. Then, when all enemies in the room are killed (specifically, Actors in category 5), the clear trigger is set. When a room's clear trigger is set, enemies are forbidden from spawning in the room.  However, keep in mind this definition of "enemies" may not always be what you think it is.  For example, the clear trigger does not count Gold Skulltulas as enemies. A clear trigger cannot be zeroed without some form of ASM modification.

Many objects have a way to attach to the room's clear trigger.  For most of these, this will be discussed when we discuss switch flags below.

The RAM address for the current scene's clear triggers is 0x00213D5C.

Global Event Flags

Global Event flags (or event flags) are flags that are accessible anywhere within the game. Most actors that set or read global level flags do so via asm only. However, Gold Skulltulas and actors that spawn Gold Skulltulas can be attached to a different Event Flag through their variable parameters.

Attaching Actors to Switch Flags

Now that we've discussed how switches work, it's time to start using them.  Below is a list of actors that can be attached to switch flags, how to change their actor variable to attach them, and their behavior with regards to changing switch flags.  The switch flag will always be represented as XX.  You must fill in the value with the desired switch.

Some actors have properties that depend on individual bits of the actor variable.  In this case, the relevant hex will be expanded into its 4 bits, and each bit will have its function listed.  Bits represented with ? have unknown function.

Some actors will have their actor variables given as arithmetic expressions.  The final actor variable will require evaluating the expression.  If you're not familiar with doing math in hexadecimal, the standard calculator in Windows has a hexadecimal mode.

Actor Entities

Switch Actor

012A XXYZ, Object 0003 (always loaded in dungeons)
X = Switch Flag

   I = 1 - frozen in ice

  C = 1 - activates automatically when flag is set (crystal only)

   P = 1 - clears when not stood on (floor and rusted only)
   T = 1 - can be turned on and off
Notes on C: Used by two crystal switches in the Spirit Temple. Usually, if two crystal switches are set to the same flag, activating one won't activate the other one. But if they have both this bit set, they will activate together.
Furthermore, if the first switch has this bit not set, activating it will still activate the second one which has the bit set, while activating the second one which has the bit set won't activate the first one which has the bit not set. I propose to call it like this: activates automatically when flag is set (crystal only).

Z = switch type
   0 - Floor switch
   1 - Rusted switch
   2 - Eye switch
   3 - Crystal switch
   4 - Targetable crystal switch


000A WYY0 + 00ZZ, Object 000E

YY = Contents, see actor list
ZZ = Chest flag, see above
W = Chest Type
   0 - No action, Large
   5 - No action, Small
   2 - No action, Ornate (Boss key)
   1 - Clear Trigger, Large
   7 - Clear Trigger, Small
   4 - Invisible, Large
   6 - Invisible, Small
   9 - Zelda's Lullaby, Large
   A - Sun's Song, Large

Switch-triggered chests

   3 - Falling, Large
   8 - Falling, Small
   B - Appearing, Large

Unlike most objects, chests don't specify the switch they're attached to in their actor variable. To attach a chest to switch XX, set the chest's Z-rotation to XX.  If using UoT for this, remember that the switch number XX is in hexadecimal, while UoT accepts angles in decimal.

Switch-triggered chests are rising-edge triggered only.  Falling chests will land on the first solid thing they encounter.  When loading a room containing a falling chest after its switch has been set, it will be on the first solid thing below it.

Standard Door

0009 0080 + 00XX, Object 0002

This is a small key door.  It triggers on neither edge.  The flag will be set when the door is opened for the first time.  If you don't want to attach the door to a flag, use 003F as your actor variable.

Lifting Door

002E 0YY0 + 00XX, Object 0002

YY = door type
   00 - Normal door (XX is ignored, but usually 3F)
   04 - Barred to clear trigger on front side; normal on back side (XX is ignored, but usually 3F)
   08 - Barred to switch flag on front side; normal on back side
   0C - Won't open on front side; normal on back side (one-way)

  10 - Nothing
14 - Boss door on front side; won't open on back side (use 14 as XX)
18 - Nothing
1C - Barred to switch flag on front side; barred to clear trigger on back side (meant to be entered first through front side)
20 - Nothing
24 - Normal door
28 - Normal door
2C - Locked on front side; locked on back side
30 - Normal door
34+ - Nothing

Barred doors trigger on both edges, locked doors on neither. The boss door should always be attached to flag 14.
Notes on behavior YY = 1C: This door is meant to be opened on front side (switch flag side) first. If you try to open it on the back side (clear trigger side) first, the door will immediately reclose after the clear trigger has been set because it checks if the front side is still barred. But if you change rooms, the clear trigger side will be open again. To avoid this strange behavior, make sure that the front side/switch flag side has to be opened first when designing dungeons.
Keep in mind that boss doors need their object to show up and that alternate door skins need additional objects (see section below).

Unlit Torch

005E 10XX + 0040*N, Object 00A4

N - number of torches that need to be lit to set the flag.

Unlit torches have an internal timer that causes them to go out after a certain period of time if the flag has not been set.  If the flag is set, the torches will all be lit and stay lit.  The torches immediately go out when the flag is cleared, and will all immediately ignite when the flag is set.

Golden Torch Stand

005E 03XX, Object 00A4

Triggers on both edges.  Is lit when switch is set, goes out when switch is cleared.

Flame Circle

0049 ZYXX, Object 0001

Z - Behavior of flame circle, see Actor List
Y - Camera movement on rising edge.  Use F if unsure.

Flame circles are rising-edge triggered only.  Timed flame circles clear their switch flag when time runs out.

Hookshot Tower

012D XXY1, Object 011C

Y = ??I?
I = 1 - frozen in ice

Switch-triggered hookshot towers are rising-edge triggered only.  They start with their base 100 units below their specified actor position, then rise 100 units when triggered.  A hookshot tower is exactly 100 units tall.

If you don't want the tower to be switch-triggered, use FFC0 as the actor variable, or FFE0 for a frozen one.

Transparent Platform

01B4 XX01, Object 01B4

Transparent platforms trigger on rising and falling edges.  They are present when the flag is set and absent when the flag is cleared.

Transparent Platform Timer

01B4 XX02, Object 01B4

Rising edge triggered only.  I have only tested this with XX = 39.  When triggered, the timer sets both 38 and 39, and clears both when the timer runs out.

Sacred Meadow Entrance Gate

018D XX01, Object 0161

This actor is a bit strange and I haven't fully figured it out... It seems to clear whenever you defeat a certain enemy. I have only tried this with the Wolfos actor (as the gate is used in the Sacred Meadow) using a variable of XX0Y where XX is the switch flag and Y is the Wolfos color (0 = gray, 1 = white). It may work with other enemies. It is also evident that you can also attach this gate to a switch... however, there are some problems which arise. I have only tried attaching it to a regular ground switch and noticed that stepping on the switch clears the gate but Link can no longer move (the game doesn't freeze, Link is just stuck staring at the ground). Using the no-clip feature on the Debug ROM will allow you to regain movement for Link, though.

Water Temple Gate (With a Timer)

01BB, YZXX, Object 0059

Y = Gate Size.
   0 - small
   1 - large
Z = I'm not quite sure. It seems to affect the speed of the timer attached to the gate.
   0 - endless fast ticking
   F - normal ticking

Setting the part of the variable labelled 'Z' to 0 will cause the timer to tick very fast... but it never seems to end. Attaching this actor to a switch causes the switch to be timed so anything else attached to the switch will reset itself (switch pops back up, doors will re-bar themselves, flame circles will turn back on, etc.) once the timer ends.

Water Temple Gate (Without a Timer)

01BB, YFXX + 00C0, Object 0059

Y = Gate Size
   0 - small
   1 - large

It works like this... If you want to attach a timer to the gate, just plug the switch flag into XX. If you don't want a timer, plug the switch flag into XX as normal and then add 00C0 onto XX.

Pushable Blocks

00FF, XXYZ, Object 0003 (always loaded in dungeons)

X = switch flag
Y = block coloration
   0 - brown
   4 - blue
Z = block type
   0 - small, loads when switch flag unset
   1 - large, loads when switch flag unset
   2 - very large, loads when switch flag unset
   3 - huge, loads when switch flag unset
   4 - small, loads when switch flag set
   5 - large, loads when switch flag set
   6 - very large, loads when switch flag set
   7 - huge, loads when switch flag set

Small Ice Block

01B4, XXYY, Object 0179

YY = Block Type
   00 - Nothing?
   01 - Normal Ice Block

If you don't wish to attach the blocks to a switch flag, set the part of the variable labelled 'XX' to FF.

Water Jet Actor

015F, YZZZ, Object 013A

Y = Spout Behavior

    1 - Lowering
0 - Raising


    XX - 6-bit switch flag
WW - 5-bit chest flag

Raising jets have no chest variable, and you should use 0x1F for them. Lowering jets disappear when the relevant chest flag is set.

For lowering jets, the X rotation is the height of the jet, in 40 unit intervals. The Y rotation is the timer, in seconds.

For raising jets, the jet always rises 400 units and has a timer of 15 seconds.

For both jets, the Z rotation is the size of the jet. This is a signed value. Negative sizes do not push Link upwards, while positive sizes do. Jets get very large quickly. Sizes above 10 not recommended.

2D Ice Bars

01C8, ????, Object 006B

FF02 - Clear Trigger activiated. This is paired with the Stalfos Actor with a variable of FFFF.
0500 - Clear Trigger activated. This is paired with a Wolfos with a variable of FF01 and two Frezzards with variables of FFFF.

At the moment I am trying to figure this actor out. So far, I have two variables which are taken from the Ice Cavern...

Silver Rupees

There are two types of Silver Rupee actors needed for a complete Silver Rupee puzzle. 0117, 1FC0 + Switch Flag, Object 0001
0117, 0140 + Switch Flag, Object 0001

1FC0 - Normal Silver Rupee. For the puzzle to work, there needs to be exactly 5 Silver Rupee Actors 0140 - Possibly a counter actor for the puzzle.

Brown Boulder

0127, YYXX, Object 0163
XX = Switch flag
YY = Behavior?

00 - Normal
80+ - Puzzle solved sound when destroyed

Triggered on neither edge. When it is destroyed, it sets its flag. When Link re-enters the room and the flag is still set, it doesn't reappear. If the flag is cleared, it reappears.

Megaton Statue

0040, XXYY, Object 002C
XX = Switch flag
YY = Part

00 - Lower Part (flame decal)
01+ - Top Part (face decal)

Triggered on neither edge. When it is destroyed, it sets its flag. When Link re-enters the room and the flag is still set, it doesn't reappear. If the flag is cleared, it reappears.

Fake Door

01C1, XXYY, Object 018E
XX = Switch flag
YY = Type

00 - Fake door
01 - Debris
02 - Debris
03 - Debris
04 - Debris
05+ - Crashes

Triggered on neither edge. When it is destroyed, it sets its flag. When Link re-enters the room and the flag is still set, it doesn't reappear. If the flag is cleared, it reappears.

Special Objects

Timer Actor

0187, VVVV, Object 0001 (always loaded)

((VVVV & 0xFC00)>>10) = Switch Flag
(VVVV & 0x03FF) = Timer in seconds (capped to 10 minutes).

It's normal purpose is to display a count down timer which will zone out the player if the time runs out. However, it checks the clear flag for the room it's placed in to determine when to shut the timer off, and it will set it's own switch flag once the clear flag changes state.

For example, in the Map 7 of Gerudo Training Grounds in v1.0 (first map to the right), Nintendo uses a variable of 0x785A which causes the actor to set the 1E switch flag (0x785A & 0xFC00)>>10 = 1E, and a timer of 90 seconds (785A & 0x03FF) = 5A.

But what makes this actor interesting, is that if you disable the timer by turning on all the bits of the timer portion of the variable, the actor will still set it's switch flag when the clear flag is triggered, essentially allowing us to convert the clear flag into a switch flag. For example, if we wanted to attach switch flag 0x03 to a clear trigger our variable would end up being 0x0FFF. (0x0FFF & 0xFC00)>>10 = 0x03, (0x0FFF & 0x03FF) = 0x03FF

This list will be continued with other general actors and dungeon specific actors, but I think this is a good starting place.

Alternate Door Skins

The object for the style of door you want to use must be first in the object list, otherwise the door loading can be unpredictable at best. This is important. The boss door object is less fussy. Also, in order to use an alternate door skin, you must overwrite a scene that uses alternate skins. I am not sure where the definition in the game that decides this is, however, so it remains to be seen whether other scenes can use these doors.

Required Objects
002B - Dodongo's Cavern Doors
002C - Fire Temple Doors
0036 - Great Deku Tree Doors
004D - Gerudo Training Grounds Doors
0059 - Water Temple Doors
0072 - Required for Forest Temple Boss Door
0073 - Required for Forest Temple Boss Door
0139 - Ganon's Castle Doors
016D - Spirit Temple Doors (may also require object 00F1, untested)
0187 - Shadow Temple / Beneath The Well Doors (may also require object 0069, untested)
00B0 - Required to load ANY Boss Door


Arcaith - Alternate Door Skins and various additions to the puzzle actor documentation
Petrie911 - Explaining various flags, additions to the puzzle actor documentation, and the majority of the text in this document
Jisaan - Work with Arcaith on switches
Jason777 - Additions to the puzzle actor documentation