Hylian Toolbox Version 1.7.1

Introduction

Thank you for taking the time to read this document. Hopefully it proves useful to you when you are using the tool. The new things are red.

Version History

Version 1.7.1

A glitch with saving groups was solved. It was reported by SanguinettiMods.

Version 1.7

OBJ to F3DZEX conversions are now powered by X-Daniel's Model2N64.
OBJ files can now be imported as areas (conversion to the mesh is powered by Model2N64; addition of the header and conversion to the collision was written by Flotonic). A lot of Windows 8 testing was done by supermariokoopa. (Scroll down to "Map Importing" to read more about map importing to learn how to save a lot of time editing collision!)
ZSCENE files can now be loaded. (Link actors render Link and transition actors render doors and can be added and edited with ease.) (Treasure chest actors render treasure chests.)
OBJ files can be exported of ZMAP files now. Additionally, one can export an OBJ file of an area's collision now that ZSCENE files can be loaded. The problem with OBJ files not being exported to the same directory as Hylian Toolbox has also been taken care of.
Collision can be edited in many ways. This includes the editing, addition, and deletion of water boxes, which were figured out by spinout. CubanR supplied the "Climbable Wall" collision flags. SanguinettiMods (who also did a lot of testing and found some bugs!) suggested the "Ice" collision preset. Credit goes to spinout for the code to calculate collision normals.
The actors from the map previously being viewed are no longer rendered when one switches to a ZOBJ file.
Clicking and holding buttons in order to press them became necessary when viewing maps with multiple actors. This is no longer a problem.
A problem similar to the one described above having to do with clicking buttons after/when editing matrices has also been taken care of.
Exits can be added and changed.
Scene actors (Link and transition actors) can be added and edited.
Alternate headers in ZMAP and ZSCENE files can be edited.

Version 1.5

Loading ZMAP files and editing, adding, and deleting actors and groups.

Version 1.4.1

I took care of a problem with it reading Link's animations. It was still using some code from when I modified it to use MM Link's animations.

Version 1.4

Importing OBJ files. (Jason777 wrote a highly-complex vertex-and-face-data condenser for this. X-Daniel provided useful information about gbi.h (a header file from the Nintendo 64 SDK) for compiling texture commands. I never got around to actually implementing it, so some non-32x32 textures will look like garbage, as well as 32x32 textures with no more than sixteen colors.)
Modifying files directly in the rom (OoT debug rom only for now).
~~Checking for new versions (you can disable this by putting a file named no_updates.txt in the same directory as the program).~~ - This code was working, but apparently does not work for people who do not compile it themselves. Besides, virus software may have even detected this as malicious activity. Aquarhane installed the Windows SDK and sent me the file I needed for this in the first place. He should still be credited even though this feature was not included.
After adding a matrix, you no longer need to save and re-open the file in order for it to render correctly.
Selecting points works perfectly now.
Exporting OBJ files of Display Lists from files without hierarchies no longer results in a crash.
New color scheme. (Recommended by lllsondowlll.)
Use of the Win32 API for opening files. (Also recommended by lllsondowlll.)

Version 1.2

Keyframe generation.
Matrix rendering. (X-Daniel wrote the original documentation; SoulofDeity explained it multiple times.)
Matrix creating.
Improved Display List detection.
Buttons work perfectly.
Clicking the "Apply" button after rotating or scaling a Display List no longer saves it to the file automatically.
The object can now be translated during its animation.
No more problems with saving hierarchies over and over with each added limb. (Reported by Jason777.)
Hierarchies now include the byte that says the number of limbs with Display Lists. (Reported by SoulofDeity.)
Even though this was taken care of in a later release of Hylian Toolbox Version 1.0, Sting_Chameleon must be credited for constantly testing the new versions of the program that I built until we finally got the font issue taken care of on computers that do not support non-power-of-two texture dimensions.

Version 1.0

Initial release.

Controls and Modes

Controls
Modes
Opening Files

Mesh Editing
OBJ Importing
- Display Lists
- Map Importing
OBJ Exporting
Hierarchy Operations

Matrices

Animation Operations
- Link's Animations
- Keyframes
- Translations
Map Editing
Scene Editing and Map Injection

1.) Controls and Modes

Controls

Camera
Click + Drag Mouse	Rotate Camera
Shift + Click + Drag Mouse	Pan Camera
W	Zoom In
S	Zoom Out
L	Left View
R	Right View
T	Top View
B	Bottom View
F	Front View
Shift + B	Back View
Shift + R	Reset Camera

Shortcut Keys / Hidden Features
0	Go to first Display List
1	Toggle Wireframe
U/I	Next/Previous Display List
Tab	Next Text-Box (when entering text)
M	Toggle Matrix Rendering
C	Toggle Back-face Culling (Maps only.)
H	Hide Selected Triangles
Shift + H	Unhide Hidden Triangles

Additionally, many things will perform actions when clicked.

For example, clicking the left or right arrow
on this part of the interface will allow you to go to the previous or next
Display List in the file, respectively.

Modes
Once a model has been loaded, to the right of "View," there are three possible selections: Display Lists, Hierarchy, and Render All. Selecting Display Lists will allow you to cycle through the Display Lists of the file and edit them individually, Hierarchy will allow you to view and edit the hierarchy and animations of the file, and Render All will render all of the Display Lists at the same time.

Opening Files
To open an individual file, use File > Open Individual. This can open an individual ZOBJ file that you have saved on your computer, separate from a rom. To open a rom file, use File > Open ROM. The Browser tab lists the files and allows you to select whichever one you want to open directly from the rom. The Editor tab allows you to edit the file within the rom. It also applies to individually opened files. The only rom supported at this time is the Ocarina of Time Debug ROM. When you save, a new document by the name of the rom (ZELOOTMA.Z64_OFFSETS.txt, for example) will be generated in the same directory as the rom. It contains the new offsets of each ZOBJ file just in case you added data and it had to move the file. This is useful for editing the files within the rom via a hex editor.

2.) Mesh Editing

When a file is loaded, you will see two things listed under Mesh. They are Scale and Rotate. Select whichever one is suitable and enter whatever values will do the job. When doing so, axes will render that match the colors of the labled text areas.

If you are in Display List Mode, the one you are viewing will be edited. If you are in Hierarchy Mode, the one that is highlighted will be edited. To apply the scale or rotation to the Display List, click Apply. To cancel, click Cancel.

3.) OBJ Importing

Display List Importing
With a ZOBJ file open (either from the rom or as an individual file), go to File > Import OBJ. You will be prompted to select an OBJ file. Unless you are replacing Link's head or something, a little bit of hex editing is required, but it is simple.

Here are some things to keep in mind (new things are in red):

Texture sizes must be of a power-of-two. Valid texture dimensions are 16x16, 8x8, 16x8, 32x64, 32x32, 64x64, and other things like that.
A 64x64 texture can have no more than 16 colors.
Textures with no more than 256 colors (if 32x32 or greater) take up less space. Textures with no more than 16 colors take up even less space.
Grayscale textures take up even less space than most textures. Grayscale textures with no more than 16 colors take up the least space.
To make a texture be 256, 16, or less colors, go to Image > Mode > Indexed in GIMP. You can set a maximum number of colors.
~~Textures must be in RGB or RGBA mode for now. In GIMP, you can change this by going to Image > Mode > RGB. You should do this after indexing it, if you decide to do that.~~
Creating a file named "Injection Offset.txt" allows you to decide which offset in the ZOBJ file that is currently open to inject custom model data. You can save it with 0x0 in it to make that the injection offset. This is more of something for advanced users and not a requirement. Data is appended to the end of the file by default.

Map Importing
With Hylian Toolbox's feature for importing OBJ files as maps, some (if not most or even all) of the work of collision editing can be done for you if you pay attention to this information and reference the following table:

Component/Group Name	Result
Main Attributes (choose only one)
Ladder	The collision will be a ladder.
LadderTop	The collision will be the top of the ladder for climbing down.
CrawlEnter	The collision will be the entrance to a crawlspace.
CrawlExit	The collision will be for crawling out of a crawlspace.
ClimbWall	The collision will be for a climbable vine wall.
FloorSink	Link will sink into the floor.
FloorLava	The floor will damage Link. You can slow the damage by wearing the Goron Tunic. Footprints of fire are left wherever Link walks.
FloorDamage	The floor will damage Link. The Goron Tunic still slows the damage, but footprints of fire are not left behind.
Death	Touching the floor will reset the room. It is like falling into the lava in Death Mountain Crater.
Ice	Link will slide around on the floor.
Other Attributes (multiple can be used)
Hookshot	The collision will be Hookshotable.
WallDamage	The collision will damage Link when he comes in contact with it. This is generally used for walls. When applied to floors, it only damages Link when he lands on them.
Sounds (choose only one)
Dirt
Dirt1
Dirt2
Dirt3
Dirt4
Sand
Stone
WetStone
ShallowWater
ShallowWater2	The sound of this is lower-pitched than the above one.
Brush
LavaSound
WoodenPlank
PackedDirtWood
Ceramic	This is generally used for ice.
LooseDirt

In Google SketchUp, individual objects are called "Components." It may vary from one 3D modeling program to the next. Either way, as long as you export them as OBJ Groups (this is a setting in Blender, but most programs do it by default), this is simple. When you create a component and you want it to be a climbable wall, simply name it "ClimbWall." If you have multiple different components that you want to have this attribute, you can name them "ClimbWall2" and so on.

Multiple attributes can also be set. If you want Link to be able to sink into the floor (FloorSink), you want it to sound like sand (Sand), and you want it to be Hookshotable (Hookshot), name the component FloorSink|Sand|Hookshot or include all of them back to back or separated by underscores or whatever you like.

When you import the OBJ file as the map's collision, the importer will recognize these OBJ Group Names and automatically do the work so you do not have to edit individual collision triangles.

Enabling Colors
Generally, colors darken the converted files and that is ugly, but if you use a grayscale texture for something and use OBJ settings to change the color of it, you can enable colors by creating a file in the same folder as Hylian Toolbox named Include_Colors.txt. This is more of an advanced user setting.

4.) OBJ Exporting

If a user goes to File and then Export OBJ while viewing a display list, a file named out.obj will be created in the directory of the program. If Export OBJ is chosen while viewing hierarchy, the object's default hierarchy will be exported as a single file still named out.obj.

5.) Hierarchy Operations

Cycling Through Limbs
When Hierarchy Mode is selected, you will see the object in its hierarchical state. Make sure the selected animation below "Animation" is set to "Hierarchy." This is how it looks with no rotations applied to any of the limbs. If you cycle through the animations, the hierarchy can still be edited. In a file without a hierarchy, you will be given the option of creating one. To cycle through the limbs, click the buttons next to the current limb (

).

Assigning New Display Lists
The Display List of the selected limb will be highlighted if it has one. The offset to the limb's Display List will be displayed where you would normally cycle through Display Lists.

You can click the left and right arrows there to change the Display List assigned to the limb that is selected.

Repositioning Limbs
You can shift around the selected limb by either using the - and + buttons or modifying the values themselves under "Position."

Notice that the X, Y, and Z are colored. They are colored based on the axis of the selected limb so there is less confusion when shifting them, especially when modifying them during an animation.

Adding and Deleting Limbs
If you want to extrude a new limb from the currently selected limb, you click the "Add Child" button. The added limb is now the selected limb and is automatically set to have no Display List, so the first thing you may want to do is assign a Display List to it. Then, position it accordingly. You can add a child to this limb if you like, and a child to its child. If you want to add a child to a limb that already has a child, that works, too. For example, if you were creating a custom hierarchy, you would add three children to the torso: one for the left arm, one for the right arm, and one for the head. If you want to delete a limb you just added or any existing limb, click the "Delete" button to the right of the "Add Child" button. The child of that limb will taken on the position of the one you just deleted. When adding and deleting limbs, the animations are adjusted accordingly. Something important to remember is that you can only replace an object that has the same amount of limbs as the object you edit/create, so if your edited object has more or less limbs than the original, you cannot replace the original. Once we figure out how to use any number of limbs with any object in-game, this will no longer be an issue.

Matrices
In Hierarchy Mode, navigate to the limb that you will be adding matrices to. Click the "Matrix" button and it will prompt you to choose the limb to connect the currently selected limb to. The currently selected limb is the red one and the one that it is going to be connected to is green. Once you have them selected, click the "Go" button.

You will now see both Display Lists and a bunch of points. The goal is to connect the points of the Display List that corresponds to the red one to the Display List that corresponds to the green one. You can click the first point, the point to connect it to, and click the "Merge" button to do this. If you accidentally select the wrong point, click the "Clear" button to clear your selection. If you want to undo your changes and start over, you can click the "Back" button to go back to the hierarchy and the "Go" button again to go back to editing. If using the cursor to select points is not being very effective, try using the R, L, T, B, F, and Shift + B keys to set the camera to certain perspectives. If that does not help, you can navigate through the points with the "<" and ">" buttons and click the "Select" button to select the one that is highlighted in green. When you are finished, click the "Apply" button.

6.) Animation Operations

Cycling Through Animations
Much like cycling through limbs, there will be a left and right arrow followed by the offset to the current animation (unless the hierarchy is being viewed, in which case the text, "Hierarchy," will be displayed). You use the left and right arrows to go from one animation to the next. If animations are not available, you will be given the option of creating one.

Cycling Through Frames
The same way you cycle through animations, you will be able to cycle through the frames of the currently selected animation by using the left and right arrows to the right of the text that specifies the current frame out of the total frames (Frame 1/4, for example).

Rotating Limbs
In Hierarchy Mode, cycle through the limbs (as described in Hierarchy Operations) until you find the one that you want to rotate. Under Rotation, you can modify the rotation for each axis by either entering your own values or using the - and + buttons.

Like with everything else, the X, Y, and Z have been colored to match the axis of rotation.

Copying and Pasting Frames
You can click "Copy" to copy the current frame of the current animation. You can click "Paste" to paste the copied frame over any frame of any animation.

Creating and Deleting Animations and Frames
Once you have an animation selected, you can click "New Animation" to create a new animation. The program will jump to that animation. Limbs will have no rotations whatsoever, so if you do not want to start from scratch, you can copy and paste a frame from another animation. Clicking "Delete" will set the animation to be deleted. This can be undone just in case you accidentally clicked it, but once you click File > Save, the changes are applied and cannot be undone. Clicking "Add Frame" will add a new frame after the current frame. It will have the same rotation data as the current frame so you do not have to bother copying and pasting and can continue from there. You cycle to this new frame the same way you cycle through frames. To delete a frame, click "Delete." A word of warning is that, because animations are indexed in the files and indexing them the same way after editing an animation may not be the same (thus, the amount of data they take up may be more or less), the animation data will be moved to the end of the file, increasing the size of the file. This applies to both newly created animations as well as edited animations.

Link's Animations
To be able to view Link's animations, the files link_animetion.zdata and gameplay_keep.zdata must be located within the same directory as the program. All editing attributes apply to these animations the same as any other save for the exception that new animations cannot be added to these files. Likewise, old ones cannot be deleted. Be sure not to get this confused with the frames as new frames can be added to old animations.

Keyframes
When you have two animation frames and want to generate in-between frames, simply click the "Keyframe" button, specify the number of frames you want to generate, and click the "Apply" button.

Translations
Right next to "Rotation" (for the rotations of a limb), there is a "Translation" button. Click it to switch to the translation of the current animation frame. This controls the X, Y, and Z Positions of the object during the current frame of the animation.

7.) Map Editing

Editing Actors on a Map
Open a .zmap file.
Click an actor to select it.
The "-" and "+" buttons can be used to alter the location and rotation of it. You can also enter your own values.
Click and drag any arrow sticking out of an actor to move the actor along that axis.
Click the "Add Actor" button to add an actor.
Click the "Delete" button to delete the currently selected actor.
Click the "Edit Groups" button to launch Notepad and edit them. Close Notepad to continue using Hylian Toolbox.

Rotations
Multiply the degrees to rotate by 182.044444444. This is the rotation to use in the program. I will get around to making it use easier-to-read rotations later. For example, 90 Degrees * 182.044444444 = 16384.

Editing the Search Boundaries
Edit the number in ZLIMIT.txt to be lower if you want the program to run more quickly, but it seems to work well at 30000. The lower the number, the lower the search bounds when selecting an actor, so edit carefully.

8.) Scene Editing and Map Injection

Editing collision and water is easy! Editing water is straightforward, but collision could require some explaining. Here is how to edit collision and things relating to it:
Collision Effects
In "Groups" tab, click any triangle on the map to select the entire group that pertains to it. Multiple settings now arise.

Clicking the button next to Effect allows you to cycle through the various collision effects, such as entering crawlspaces, leaving them, climbing up ladders, climbing down ladders, and so on.
Camera is a more-advanced setting that you will not edit the value of in general.
The button next to Exit allows you to cycle through exits. Because there is no determined amount, it will go to the maximum number of exits allowable in a scene before returning to N, which indicates that no exit is applied to the collision. The Edit Exits button will launch a Notepad window. Edit the exits (or even change the number of them!) to your liking, save, and close. This can be done as many times as necessary.
The button next to Wall Damages Link? toggles whether the wall can damage Link or not. When applied to floors, it only damages Link when he lands on them. Y indicates that it can, while N indicates that it cannot.
The button next to Hookshotable? works the same way as described above, but it pertains to whether the collision is Hookshotable or not.
The button next to Type allows you to cycle through the various sounds for the collision. This also relates to whether dirt will come from the ground or not when Link rolls on it.
Clicking the button next to Brute Search toggles the range to search for collision triangles when selecting them. The more triangles on the map, the slower this will be. It is best to leave this set to "No" until you are trying to select a triangle that is not becoming selected.

Regrouping Triangles
If you want to separate certain triangles into their own group, switch to the "Triangles" tab. You will be able to select triangles (hold Shift to select multiple!). Click the Yes Button under "Put selected triangles into a new group?" in order to do so. You will automatically be switched back to the "Groups" tab and the group with the triangles you selected will already be selected for you to edit as described in the "Collision Effects" section above.

Map Injection

Launch "Map Injector.exe." You will be prompted to open the OoT debug rom that you will be porting the area into.
It will now print something to the command line window. It is asking for the Injection Offset. You can enter 35D0000 if you have not imported any other maps. If you are importing multiple areas, you will want to refer to the Output.txt file that is generated each time and add 0x10 to the last map's end offset for the new injection offset. This is more of an "Advanced User" setting. If you are importing an area into a rom that has no areas imported, though, just use 35D0000.
Upon pressing the Enter Key, you will be prompted for the ZSCENE file to inject. Locate it and open it. It will ask for each room that goes with the ZSCENE in order. Whether you are reinjecting an area that came from OoT or a custom map generated by Hylian Toolbox, they will be named ending in room_0, room_1, and so on.
You will now be asked for the scene to replace. Refer to the list below this one for which values correspond to which maps.
Test in-game!

Scene List (taken from wiki.spinout182.com)

000	Deku Tree
001	Dondogo's Cavern
002	Jabu Jabu's Belly
003	Forest Temple
004	Fire Temple
005	Water Temple
006	Spirit Temple
007	Shadow Temple
008	Below the Well
009	Ice Cavern
010	Ganon's Tower (Second Part)
011	Geruode Training Grounds
012	Thieves' Hideout
013	Ganon's Tower
014	Ganon's Tower (Floor beneath boss chamber)
015	Ganon's Tower Crumbling (Exit)
016	Treasure Chest Shop
017	Deku Tree Boss
018	Dondogo Cavern Boss
019	JabuJabu's Belly Boss
020	Forest Temple Boss
021	Fire Temple Boss
022	Water Temple Boss
023	Spirit Temple Middle Boss
024	Shadow Temple Boss
025	Second-To-Last Boss Ganondorf
026	Ganondorf, Death Scene
027	Market Entrance (Day)
028	Market Entrance (Night)
029	Market Entrance (Adult)
030	Back Alley (Day)
031	Back Alley (Night)
032	Market (Day)
033	Market (Night)
034	Market (Adult)
035	Temple of Time (Outside - Day)
036	Temple of Time (Outside - Night)
037	Temple of Time (Outside - Adult)
038	Know-it-all Brothers
039	House of Twins
040	Mido's House
041	Saria's House
042	Kakariko Village House
043	Back Alley Village House
044	Kakariko Bazaar
045	Kokiri Shop
046	Goron Shop
047	Zora Shop
048	Kakariko Potion Shop
049	Market Potion Shop
050	Bombchu Shop
051	Happy Mask Shop
052	Link's House
053	Puppy Woman's house in market
054	Stables
055	Impa's House
056	Lake Hylia Labatory.
057	Carpenter's Tent
058	Dampe's Hut
059	Great Fairy Fountain
060	Small Fairy Fountain
061	Magic Fairy Fountain
062	Grottos
063	Grave (1)
064	Grave (2)
065	Royal Family's Tomb
066	Shooting Gallery
067	Temple of Time Inside
068	Chamber of Sages
069	Castle Courtyard (Day)
070	Castle Courtyard (Night)
071	Cutscene Map
072	Dampe's Grave
073	Fishing Pond
074	Zelda's Courtyard
075	Bowling Alley
076	Talon's House
077	Lots'o Pots
078	Granny's Potion Shop
079	Final Battle against Ganon
080	Skulltula House
081	Hyrule Field
082	Kakariko Village
083	Graveyard
084	Zora River
085	Kokiri Forest
086	Sacred Forest Meadow
087	Lake Hylia
088	Zora's Domain
089	Zora's Fountain
090	Gerudo Valley
091	Lost Woods
092	Desert Collusus
093	Gerudo's Fortress
094	Haunted Wasteland
095	Hyrule Castle
096	Death Mountain
097	Death Mountain Crater
098	Goron City
099	Lon Lon Ranch
100	Ganon's Tower (Outside)
101	Collison Testing Arena
102	Besitu
103	Depth Test
104	Stalfos Middle Room
105	Stalfos Boss Room
106	Dark Link Testing Area
107	Beta Castle Courtyard
108	Action Testing Room
109	Item Testing Room