Treasure
"Treasure" and "Items" are slightly different concepts, in terms of the disassembly's vocabulary. A "treasure" is a collectible thing (ie. rupee drops, items lying on the ground), while an "item" is an object whose main purpose is to interact with enemies (ie. the sword). This distinction is a bit confusing, since most items (like the sword) can exist as both a "treasure" (when in collectible form) and as an "item" (when being used).
Overview
Look in constants/common/treasure.s to find the index and the name of the treasure you're interested in. Treasures with indices between $00-$1f correspond to items in Link's inventory with the same index. Treasures with indices $20 or higher are not equippable, so they're usually "passive" items (like the mermaid suit).
Each and every treasure also has a single bit associated with it, located at wObtainedTreasureFlags ($c69a). The game uses this to check if you have an item (ie. if the mermaid suit bit is set, you can swim in deep water).
Important functions
giveTreasure (00:171c)
Gives Link treasure 'a' with parameter 'c'. It does this by setting the corresponding bit in wObtainedTreasureFlags, and putting it in his inventory if applicable (index < $20).
What the parameter 'c' does depends on the item, but it usually makes logical sense; for instance, parameter $05 for item $20 would give you 5 ember seeds.
loseTreasure (00:1733)
Removes item 'a' from Link's inventory and clears the corresponding bit in wObtainedTreasureFlags.
checkTreasureObtained (00:1748)
Sets the carry flag if Link has item 'a'. The game uses this frequently to test what items Link has.
It also returns the item's "paremeter" in 'a', indicating the item's amount, level, etc.
Data structures
treasureCollectionBehaviourTable
Search for this in main.s. The exact details are fairly well documented there.
This table determines what "extra" things happen when Link collects the treasure; for instance, an item's corresponding level variable may need to be set, or Link may be supposed to obtain a certain number of bombs.
This is part of the implementation of the giveTreasure function.
treasureDisplayData
This data structure describes how the treasure appears in Link's inventory and his A/B buttons. It contains the following data:
- The icon (sprite and palette)
- The text to show (text ID
$09xx) - Whether to display a level number, a quantity, or the harp icon along with it
It also allows an item to have multiple versions of this data based on another variable (such as the level number, equipped seeds, etc).
Its exact format is documented in main.s.
Treasure objects
See: data/{game}/treasureObjectData.s(ages/seasons)
Although you could just call giveTreasure to give Link an item, it would do so instantaneously, and you wouldn't know what you got. For this reason, each treasure has a few corresponding "treasure objects".
These objects contain a bit of extra data, including:
- Its "spawn mode" (should it just appear instantly, appear with a poof, or fall from the ceiling?)
- Its "collect mode" (should Link hold it over his head, or should it just be collected instantaneously?)
- The text to show on collection
- The sprite to use
- The parameter to pass to
giveTreasure(ie. the item's level, the amount of the item to give, etc)
This data is editable through LynnaLab's chest editing interface.
Indices
When using treasure chests or the "giveitem" script opcode, you must specify the index of a treasure object. The index consists two bytes, ID1 and ID2. ID1 corresponds to the treasure that will be given to you, so you can use constants/common/treasure.s to see what that is.
ID2 determines what the "extra data" will be (text to show, sprite, etc). This is editable in LynnaLab's chest/treasure editing plugin, though the interface needs work.
A treasure object is an interaction with mainID = $60. The subID = ID1, and var03 = ID2 (var03 is address dx43). Although you could place a treasure object directly into a room through LynnaLab or ZOLE, the game would not remember when you've collected it (and there's no easy way to set ID2). So, treasure objects are usually created through scripts.