Bottle Adventure

1. How Hot Spring Timers Work

In order to understand the possibilities and limitations of Bottle Adventure, one first has to understand how the game writes a timer for hot spring water (hsw).  Upon catching hsw, the game has to set a timer for the water to cool down.  Since there are 6 intended bottles in the game, the game needs to be able to set 6 of these timers separately.  This means that, when you use a bottle to catch hsw, the game has to look at the equipment slot to which the bottle belongs.  This brings us to needing to understand how equipped items are handled.

Items equipped to the C buttons are stored in memory in 3 consecutive bytes. Bottles have an id of 0x12 (a number prefixed with 0x is understood to be in hexadecimal), so, if I had bottles equipped to all of my C buttons, the 'equipped C items' bytes would look like 0x121212.  Exactly one row below this in memory are 3 more bytes which indicate to which inventory slots these bottles would belong.  All bottles are identical, and this is how the game deals with having multiple copies of the same item living in different inventory slots.  The 6 inventory slots allotted to bottles have values from 0x12 to 0x17.  So again, for example, if I equip the 3 leftmost bottles on the inventory screen to my C buttons, the 'equipped C items' bytes will still read 0x121212, but the 'C item inventory slots' bytes below that will read 0x121314.  These 'C item inventory slots' bytes are what the game uses to determine which bottle you're using and hence where to write the timer data.

The hotspring timers consist of 4 rows of data plus a single byte, used as an indicator that the corresponding bottle/timer is 'active.'  When you catch hot spring water, the first row of data that is written is a time stamp indicating when you caught the water.  The second row indicates the maximum length of the timer (which is 0x1770), the third row is the timer itself, and the fourth row is a second timestamp which is not set until you close the text box explaining that you've caught hot spring water.  The reason for having two timestamps is that, while the rest of the values are set upon catching the water, the game does not run hsw timers unless you have control of Link.  Therefore, upon closing the hsw text, it writes a second timestamp indicating an offset from the initial timestamp.  This second timestamp is updated any time the game is paused for any reason.

These 4 rows of data have 2 rows of spacing between them, which means that the data for a single bottle look like so:

Timestamp
--------
--------
Timer Length
--------
--------
Timer
--------
--------
Second Timestamp

There are two such areas designated in the memory, such that with all 6 bottles filled with hsw the memory looks like this:

Timestamp 1
Timestamp 3
Timestamp 5
Timer Length 1
Timer Length 3
Timer Length 5
Timer 1
Timer 3
Timer 5
Second Timestamp 1
Second Timestamp 3
Second Timestamp 5

and similarly for the other 3 bottles.  The indicator bytes reside, 6 in a row, just before these blocks.

1.1 How to Check These Operations for Yourself

It's not hard, using memory hacking software, to confirm that this is how the timers work.  In Bizhawk on MM JP 1.0, the indicator bytes start at 0x1F362C, and the rest of the data is written shortly after that.  Using hex editor, you can see that the first 3 rows of data and the indicator byte are written upon catching the water.  The 4th row is written upon closing the text box.  The game knows which 4th rows to populate based on which of the 6 indicator bytes are active -- try freezing the 6 indicator bytes at 0x01 and catching hsw in any bottle, real or duped.  You will see all 6 4th row values update when you close the text box.  Also, it's not hard to see by frame advance that the actual value of the timer depends dynamically on all 3 other values -- changing either of the two timestamps or the timer length immediately impacts the timer itself.  Similarly, if you have a hsw timer running and you pause the game, you'll see the 4th row update, essentially adding back the time that you were paused to the timer.

2. Bottle Adventure (BA)

Now, the reason that this is of any practical interest for glitching is the earlier-mentioned fact that the game determines which bottle you're using based on the values in the 'C item inventory slots' bytes.  When you catch hsw, the game does simple math using this value in order to determine where in memory to place the first 3 rows and indicator byte.  The formula used is set up such that the values 0x12 through 0x17 map the data to the intended locations in memory.  Of course, we have developed methods for placing bottles on any possible inventory slot, meaning we can catch hsw with 'C item inventory slot' bytes that fall outside the intended range.  This causes the timer data to be written either lower down or farther up in the memory than intended, depending on whether the inventory slot used has a value of less than 0x12 or greater than 0x17, respectively.  In fact, using bottle duping we can write with a 'C item inventory slot' value as high as 0x2F (the inventory slot corresponding to Fierce Deity Mask).  Writing outside the intended range allows us to affect other game data, simply by catching hsw.

The utility of such a trick is entirely contingent upon the data that's nearby the hsw timers.  The English and Japanese versions put their timer data in slightly different places, which is why BA produces such different results on the two versions.  Of note, on the English version, the hsw timers fall immediately before the pictograph picture, which takes up a large region of memory, and the amount to which we could feasibly write with BA is negligible.  This means that, on English, we're only ever going to get interesting results out of BA with values less than 0x12.

On the Japanese version, the hsw timers immediately precede a chunk of interesting addresses, rather than following them.  This means that on Japanese we can get milage out of almost the full range of BA -- any value greater than 0x17, while not necessarily useful, at least puts us among interesting regions of memory.

2.1 4th row and Bottle Adventure

While changing the equipment slot value will move the indicator byte and first 3 rows of data, the 4th row unfortunately works differently.  The 6 locations allocated for 4th row timestamps, which update based on the 6 intended indicator byte locations, are a fixed structure; they have a set place in the memory and will not move based on C item inventory slot.  This means that some of the neat things which would be theoretically possible if we could write 4th row data anywhere, such as Kaztalek's proposed method of moon warp (http://pastebin.com/yX7T9ujV), do not appear to be possible.

3. Extending Bottle Adventure

This section is more speculative, but should indicate possible directions for future research.  I mentioned above that, using inventory slots, we can BA with values up to 0x2F.  While this is true, it's not the whole story.  The location to which the timer data are sent is determined by the byte 1 row down from the bottle's location, and a byte can take values up to 0xFF.  This means that our inventory slots give us access to under 1/5 the theoretical full range of BA possibilities.  On English, this would only allow writing further into the pictograph image -- not useful.  On Japanese version, however, we get into some very interesting territory.  If we could freely manipulate the bytes controlling inventory slots, we would not only have access to moon warp (BA with a value of 0x31 writes the timestamp directly to entrace mod setter), we would be able to write to scene flags; this would open up many, many new possibilities.

3.1 BA with Bottle on B

There's one possibility I haven't touched on yet, and that's doing BA with a bottle on the B button.  It's the only place other than the C buttons that we can 'equip' an item, and it produces at least one unique result.  Doing BA with a bottle on the B button works the same way as with C buttons -- the game looks at the byte one row below where the item value is stored to determine the 'inventory slot value.'  In the case of human Link, the item on B is stored directly to the left of the items on the C buttons.  The corresponding byte one row down appears to be unused and sits at its default value of 0x00.  This means that BA with a bottle on human B always uses the value of 0x00, which is the same as the Ocarina inventory slot.

Transformation B buttons, however, are more interesting.  Directly below the transformation B button items are, again, unused bytes, except their value is 0xFF.  This means that by performing BA with a bottle on a transformation's B button, our 'inventory slot' value is read as 0xFF.  This writes the BA data well into the game's scene flags.  It's also the theoretical farthest into the memory that we can write data with BA.  BA on transformation B doesn't do anything spectacular, but you can get some tangible results out of it -- the timestamp writes to scene data used in Mountain Village (winter and spring) and can allow you to collect the red rupee under the Blacksmith's steps multiple times (if manipulated).  The timer values write to scene data in Music Box House and Path to Ikana.  I don't believe that anything can be done with the Music Box House addresses, but in Path to Ikana you can remove the flag for the hookshot tree that the Garo guy creates.

It's also worth noting that if you've never equipped any item to a C button, the corresponding 'C item inventory slot' byte is 0xFF.  So, if you dupe a bottle over an empty C slot using the Curiosity Shop, you can achieve the same result as transformation BA with bottle on B.  This method also would give us a way, if we could manipulate the 'C item inventory slot' bytes, to use BA without messing up the value by equipping a bottle.

In summary, if anything is found that is able to write to the bytes directly below the B button item values (or a way to manipulate the C item inventory slot values), we would suddenly have access to a vastly expanded version of BA on Japanese version.