From CloudModding OoT Wiki

Switches, Doors, Chests, and All That Jazz: A guide to dungeon infrastructure

Notes by Petrie911

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

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.

Type Range Details
Permanent flags 00-1F Keep their values when you leave the current scene or save. Never affected by other scenes.
Temporary flags 20-37 Cleared or preserved on leaving a scene, depending on the zone-out type variable set.
Local flags 38-3F Cleared every time a room unloads.

The RAM address for the current scene's switch flags is 80213D48 in the Debug Rom. See Game Play Struct for other versions. The zone-out type variable is located at Save Context + 0x1364, and is normally set to the following values: 

/* zoneoutTypes
// -3 = Warp Song, reset temp flags. Uses zoneoutRespawn 1 data for spawning
// -2 = ?, preserves temporary flags (sun's song, tower collapse, continue)
// -1 = ?, preserves temporary flags. Warp back to last entrance index
// 00 = Standard Exit, reset temporary flags
// 01 = zoneoutRespawn 0, void
// 02 = zoneoutRespawn 1, grotto and warp songs
// 03 = zoneoutRespawn 2, farore's wind

There are a few important things to note.

Farore's Wind copies the state of the temporary flags as they were when entering the room when cast, and restores this state when you warp back, regardless of what their current values are.  This holds true even if you are warping between two different rooms of the same dungeon.

Never attach events to switch flag 3F. Several actors use "attached to 3F" as a shorthand for "not attached to anything" or "attached to clear flag".  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 when the previous room unloads, which can trigger events 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.

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, have the same limitations, and Farore's Wind will preserve the state of the temporary collectibles flag.

Type Range Details
Permanent flags 00-1F Typically Heart Pieces or Keys.
Temporary flags 20-37 Pots, free hearts
Local flags 38-3F Most likely never used by collectibles

Chest Flags

Chest flags are a group of permanent flags used to determine if a chest has been opened. They are only set by the Chest actor (000A). Each scene stores its own set of 32 chest flags, giving a range of flags between 00-1F. If multiple chests share the same chest flag, opening one will cause all other chests attached to that flag to be open as well.

Type Range Details
Permanent Chest Flags 00-1F

See Chest for an explanation of the chest actors parameters.

The RAM address for the current scene's chest flags is 80213D58. See Game Play Struct for other versions.

Clear Flags

Room Clear Flags (Clear Flags for short) are a set of flags that store whether all the enemies within a particular room have been defeated, and prevent enemies from spawning within that room once set. Each scene has up to 32 clear flags, one per room.  However, since no scene has 32 rooms (Spirit Temple comes closest with 29), they will not all be used.

Clear Flags are pretty simple. First you must have at least one actor which attaches itself to the room clear event. Then, when all enemies in the room are killed (specifically, category 5 Actors), the Clear Flag is set, preventing enemies 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 room clear event does not count Gold Skulltulas as enemies. Clear Flags cannot be zeroed without some form of ASM modification.

Many actors have a way to attach to the room's clear flag, which will be discussed below.

The RAM address for the current scene's clear flag is 80213D5C. See Game Play Struct for other versions.

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

Main article: Actor List (Variables)

Switch Actor

012A XXYZ, Object 0003 (always loaded in dungeons)

X = Switch Flag
Y = ICPT

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. 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.

Z = switch type

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

Chest

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 Flag, Large
   7 - Clear Flag, 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 0001

XX = Switch Flag
YY = door type

YY Purpose
00 Normal door (switch flag is ignored, but usually 3F)
04 Barred to clear flag on front side; normal on back side (switch flag 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 flag 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 flag side) first, the door will immediately reclose after the clear flag has been set because it checks if the front side is still barred. But if you change rooms, the clear flag 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 - Rising

ZZZ = XX WW

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

Rising 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 rising 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 Flag activiated. This is paired with the Stalfos Actor with a variable of FFFF.
0500 - Clear Flag 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)

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

Its 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 room 7 of Gerudo Training Grounds in NTSC 1.0 (the first room to the right), Nintendo uses a variable of 0x785A which causes the actor to set the 1E switch flag, and a timer of 90 seconds:
(0x785A & 0xFC00) >> 10 = 1E
(785A & 0x03FF) = 5A.

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 clear flags into a switch flag.

For example, if we wanted to attach switch flag 0x03 to a clear flag 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

Actors 0009 (standard door) and 002E (lifting door) can both use alternate door skins. This is scene dependant. In most scenes, the lifting door will use its default skin (object 0001, always loaded); the standard door will use one of two default skins based on which special object is loaded for the scene (0002 or 0003).

However, in dungeon scenes, doors behave in a different way and will try to use alternate door skins, if applicable.

For instance, if a dungeon has alternate doors skins for standard doors (actor 0009), lifting doors (actor 002E), bar-locked and key-locked doors (actor 002E, different variable):

  • The doors will use their alternate door skin IF a corresponding object is loaded (see table below).
  • If this object is missing, they will use neither their alternate door skin nor their default skin (even though objects 0001 and 0002 or 0001 and 0003 are present); they will simply not appear.
  • The doors will only use their alternate door skin in their native scene; in a different scene, the alternate door skin will not appear, even if the corresponding object is loaded. Therefore, it is not possible yet to make Water temple doors in the Fire temple or in any scene that does not overwrite the Water temple.


If a dungeon has alternate door skins for certain types of doors only (e.g.: Deku tree has alternate door skins for locked doors only (actor 002E, specific variable)), these doors will need their corresponding object and work as explained above. However, the doors which do not have an alternate door skin in this dungeon (e.g.: Deku tree has no alternate door skins for standard doors (actor 0009) and lifting doors (actor 002E, variable 0000)) will use their standard door skins, depending on whether objects 0001 and 0002 or objects 0001 and 0003 are loaded.

As with any actor, in order to prevent doors with custom skins from unloading during transition between two maps, it's important to make sure that any objects you don't want to unload are listed in the same order and in the same object list position between the two transitions. As such, the best way to prevent doors with custom skins from unloading is to place the dependent object at or near the first position in the object list for all maps within a scene that require the door skin.

Without modifying the actor in question, it isn't possible to load an alternate skin for a different dungeon. It even doesn’t matter if, say, in the Fire temple, the object used for alternate door skins of the Water temple is first in the object list and the object used for Fire temple alternate door skins is second only; the scene will always use the Fire temple alternate door skins, because, as explained above, each scene always uses its native alternate door skins.

Boss doors (actor 002E, specific variable) will need object 0003 for the key look (otherwise it will appear corrupted). They need object 00B0, as well; without it, they won’t display. In most scenes, a default boss door skin will be displayed. In certain dungeon scenes, an alternate door skin will be used, without need of additional objects (in contrast to other door types). Like other doors, the alternate door skin used depends on the native scene; the Fire temple will always use the Fire temple alternate boss door skin (as long as object 00B0, needed for any boss door, is present). The position of the boss door object in the object list is not important.



Bar-locked lifting doors are only shown when different from regular lifting doors; in the case of Dodongo’s cavern and Spirit temple, the doors look the same but the bars are different, therefore pictures have been provided. Key-locked doors always look the same as the corresponding bar-locked door, but with the bar replaced by a key lock (which may or may not adjust its size to the door’s size, see table for details).


Credits

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

Retrieved from "http://wiki.cloudmodding.com/woot/index.php?title=Tutorial:Modification_and_Addition_of_Switches&oldid=6644"