Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rogual/oot-scene-tool

Some tools for making Ocarina rom hacks
https://github.com/rogual/oot-scene-tool

Last synced: 16 days ago
JSON representation

Some tools for making Ocarina rom hacks

Awesome Lists containing this project

README 

        
* Installation



I haven't packaged this up as a proper add-on yet. Here's how I load it:



- Make sure you have Fast64 loaded

- Open blender_text.py in the Blender text editor

- Press Alt+P to load it.

- If it loads successfully, you should have an "OOT Scene Tool" panel underneath the Fast64 panels.

- If you're hacking on the code, you can press the "Reload Tool" button in the panel to reload it.



* Configuring settings



- Configure the decomp path and all other Fast64 scene settings as normal.

- In the OOT Scene Tool panel, set your scene's display name. This is only used to generate the dungeon map's title image right now, but can be used in the future for title cards and world map captions.

  

* Features in detail

** Room splitting



Fast64 exports one room per object, but I find it easier to model my whole scene as a single object, so this tool can perform "Room Splitting".



To use room splitting, model your scene as a single object. Call this object =Geom=. Then define "Room Boxes" to specify how it will be split into rooms.



*** Defining room boxes



Make a collection called =Room Boxes=. In this collection, create one or more bounding objects for each room you want to export. Only the bounding boxes of the objects matter; I suggest you use cuboids and set them to wireframe.



Rooms are numbered starting at 0. The bounding objects for room 0 must be called =Bounds0.0=, =Bounds0.1=, and so on. Those for room 1 must be called =Bounds1.0=, =Bounds1.1=, etc.



At export, any polygons that intersect any of Room 0's bounding boxes will become part of room 0, and likewise for the other rooms.



You'll probably only need one bounding box for most rooms, but you might need several if a room is a funny shape and you need fine control of which polygons become part of the room.



** Dungeon maps and dungeon minimaps



This tool can automatically generate dungeon pause maps and dungeon minimaps and update the decomp code to use them.



*** Creating dungeon maps



To create a dungeon map, you'll need to specify where the boundaries between your floors are. You do this by defining "floor planes".



*** Defining floor planes



- Create a collection called =Floor Planes=.

- Create objects in this collection wherever you want a division between two floors.

- Only the Z-coord of each object's position matters. I suggest you make them large planes the size of your level.



*** How floor planes are used



Floor planes are used for two things:



- They define how the dungeon map is divided into floors.



- They can also split individual rooms into vertical slices, each of which gets its own minimap. Any room which straddles a floor plane will be split like this.



*** Exporting



Press "Render Maps" to create and export the maps.



- The map textures will be written to =$OOT/assets/textures= where =$OOT= is your decomp dir.

- The decomp code will be updated to use them.

- Intermediate files will be written to =$OOT/build/oot-scene-tool=. It's OK to delete these.

- The tool will also find and update the map mark data and all other map-related data.



** Overworld minimaps



Overworld minimaps can also be exported. They're similar to dungeon minimaps with a few differences:

- They don't have to be 96x85

- There is one minimap per scene, showing all of the scene's rooms

- Stylistically, they are ususally more detailed, and they lack the outer rectangle that's drawn around dungeon minimaps.



There is a rudimentary material-based system for adding detail to overworld minimaps. If you give a material a custom property called =MinimapColor= and set it to an integer, 0-7 inclusive, then surfaces with that material will be drawn into the minimap in that color, where 0 is darkest and 7 is lightest. The default color is 3.



Any surfaces with actor collision disabled are not included in the overworld minimap, and neither are any objects with "Ignore Collision" set. Right now this is the only way to exclude surfaces from the minimap.



** Title cards



(You need to have the right fonts installed for this to work, and the fonts are not configurable. Letting you choose your own fonts would be a good improvement, but until then, you can edit =text.py= to make it do what you want.)



Set your scene's display name in the OOT Scene Tool panel, then press “Render Title Card”.



The scene's name will be rendered to a texture in an approximation of the style OOT uses. This texture will be installed into the appropriate place within the OOT decomp directory and will replace the vanilla title card for your scene.



** Lighting



OOT's indoor scenes use precalculated vertex lighting, which means that every vertex in the scene's geometry is assigned a colour, in addition to its texture coordinates. These colours are assigned at build time and are not dynamic. The textures are then modulated by these vertex colours. This can be used to simulate the effects of light and shadow.



This tool can help you assign vertex colours in your scene in order to create lighting effects.



*** Blender's vertex colour support



In Blender, a mesh can have any number of "Colour Attributes". These are like layers of vertex colours; each one is a separate mapping of the mesh's vertices to colours.



*** Fast64 vertex colour support



If your scene geometry has a colour attribute called =Col=, Fast64 will export it as part of your display list.



*** OOT Scene Tool's vertex colour tools



OOT Scene Tool supports several layers of vertex colours, which are combined at export into the single =Col= layer that Fast64 expects.



=AO= is an ambient occlusion layer which is intended to be generated automatically by the "Bake AO" tool. It gives an approximation of non-directional, ambient lighting. Corners will be darker and open surfaces will be lighter.



=Multiply= is a layer which is intended to be painted manually using Blender's vertex painting tools. This is useful for manually painting in shadows, making trippy MM colours, etc.



These two layers are combined into the =Col= layer at export time, like so:



=Col= = =AO= * =Multiply=



**** Suggested vertex colouring workflow



Press "Bake AO" to create or update the AO layer. This is done automatically at export but you can do it manually as a preview.



Use Blender's vertex colour painting tools to paint on the =Multiply= layer if you want to use it. You'll have to create it yourself.



Press "Merge Vertex Colours" to update the =Col= layer. Again, this is done automatically on export.



** Actor Tools



*** Move Actors To Rooms



Fast64 expects actor objects to be children of the rooms they are in.



The "Move Actors To Rooms" button sets this up automatically for you; any actor that's inside a room's bounding box will be made a child of that room.



** Miscellaneous Tools



*** Export Scene



This just calls through to Fast64's export function.



*** Compile OOT



This compiles OOT by running =/usr/local/bin/gmake= in your OOT decomp directory.



The path to =gmake= is currently not configurable.