=====================
SB3Utility User Guide
=====================
Last modified for SB3Utility v0.7.21
SB3Utility is originally based on RLUtility


Requirements
============
- DirectX v9.0c
- Microsoft Visual C++ 2008 Redistributable Package (different from the editor)
- .NET Framework 3.5 SP1 (different from the Compact Framework)
- If you're still experiencing a crash on start, try installing CEGui Mesh Viewer


Opening Files
=============
Either drag-n-drop files or use the File menu.
Selecting a .pp file will show its packed files in the lists below.


Opening Files: .pp Format Autodetection
=======================================
Some games use the same .pp header format but different encryption for packed files. If the wrong "Source Format" is shown, you must set it manually before selecting its packed files.
There is a ranking for each format, so the autodetection will choose the highest ranked format of the conflicting games.
There are also certain letters that a .pp filename can start with to be autodetected as that format. They are shown below.
Whenever a .pp file is opened or when the "Source Format" is set, the format ranking gets set to the highest. This is so that it won't keep autodetecting the wrong format when you're opening multiple .pp files for the same game.
The format rankings are automatically saved in the user settings when exiting.

The following is a list of which games use the same .pp header format:
SM Trial, SM Retail, AG3 Welcome, Hako Trial. Filename prefixes: "smt" -> [SM Trial], "sm" -> [SM Retail], "js3" -> [AG3 Welcome], "hkt" -> [Hako Trial]
AG3 Retail/Make Trial, DG, Hako Retail. Filename prefixes: "js3" -> [AG3 Retail/Make Trial] , "hk" -> [Hako Retail]


Adding Files to a .pp File
==========================
First open a .pp file, and select it.
Open the other files you want to add, and highlight them. Only files listed under the "Img" or "Other" tabs can be added.
Click "Add", and they should be added to the .pp file's lists. If a file with the same name already exists in the .pp file, it will be replaced.
Save the .pp file.


Opening .xx/.xa Files
=====================
First open a .pp file, and select it.
Its files will be listed under the .xx, .xa, etc tabs.
Either highlight .xx/.xa files and press Enter or double-click the files to open them in the Editor.


Editing .xx Files
=================
Open the .xx file to open it in the Editor.
The "Object Tree" shows the general data structure.
Select a Frame/Bone/Mesh/Material/Texture to view it under its respective tab.
Edit a field and click "Apply". Only changed fields (with bold text) will be applied.
The "Hex" field represents unknown flags or properties for the object.
Save the .pp file.


Editing .xx Files: Textures
===========================
You can export textures by selecting them and clicking "Export".
Once you've edited an exported image, open it in SB3Utility, and it will show under the "Img" tab. Only 24-bit BMP and 32-bit TGA uncompressed image formats are supported.
Select it, and select the texture you want to replace.
Click "Replace".
Save the .pp file.


Editing .xx Files: Meshes
=========================
Each mesh has a number of mesh objects, and each mesh object can have its own material.
You can change a mesh object's material by selecting it in the "Mesh Objects" list under the "Mesh" tab. Select the new material in the combo box, and click "Set".
Save the .pp file.

You can export meshes by selecting them and clicking "Export". If no meshes are selected, it will export all meshes.
All opened .xa files will have their animations added to the export, for supported 3D formats.
Edit the exported files using a 3D editor.
Open the 3D file and select it. It should open the Workspace window.
Set the desired options in the Workspace. See the "Using the Workspace" section for more info.
Make sure the correct .xx tab is selected in the Editor, and click "Auto-Replace" in the Workspace.
Save the .pp file.


Editing .xa Files
=================
Open the .xa file to open it in the Editor.
Only the "Skeletal" tab is working. The others haven't been implemented yet.
Animations are exported when exporting meshes. See the "Editing .xx Files: Meshes" section for more info.
You can change the animation track name by selecting it and then clicking on it, similar to Windows Explorer.
"Remove" for animation tracks and keyframes will only apply to selected tracks.
"Normalize Length" will make sure all animation tracks have the same number of keyframes by copying the last keyframe. You might get unexpected results if they don't all have the same number.
You can edit animation clips by clicking "Edit".
Save the .pp file.


Importing 3D Files
==================
Open the 3D file.
Once you select it, it will open a Workspace window.
You can replace meshes or animations using "Auto-Replace". See the "Using the Workspace" section for more info.


Using the Workspace
===================
To open a Workspace, you can either select an imported 3D file or create a "New Workspace" from the File menu.
You can right-click on the tree to expand/collapse or check/uncheck all nodes.

Selecting an object in the tree will show options for replacing.
Only root nodes that are checked will be used when replacing.
Replacing happens in order from top to bottom. This is important for objects that depend on others. For example, you'll want to add hierachies before adding meshes. It won't add a mesh if the target frame doesn't exist.
When replacing a skinned mesh with an unskinned mesh (ie. mqo), and if a base mesh object is found, the bones of the new mesh object's vertices will be set to the base mesh object's closest matching vertices.
When you're ready to replace, make sure the correct tab is selected in the Editor and click "Auto-Replace".

Calculating normals over multiple roots or the entire workspace is useful if an object is split into different meshes or files.
When calculating normals or aligning vertices, the local coordinates are compared. If calculating over several meshes and they are in different transformation frames, you need to export with the "World Coordinates" option for mqo. I might add in frame consideration for hierarchies later.


Using the Workspace: Adding Objects
===================================
To add animations, select a .xa tab in the Editor and click "Add Animations From XA Tab".
To add objects to the Workspace, you can drag-n-drop objects either from a .xx Object Tree or from another workspace.
Hold shift/ctrl to move/copy. By default, drag-n-drop will move the object if doing it within the same workspace. Otherwise, it'll copy the object. You can only copy from a .xx Object Tree, not move.
Dropping to a Workspace's node will insert at that position. If dropping to an empty space, it'll create a new root node.

The following is a list of valid drag-n-drop source to target objects:
From .xx Object Tree:
Frame -> Root
Frame -> Frame (adds it as a child of the target frame)
Mesh -> Root
Mesh Object -> Mesh (adds it to the end)
Mesh Object -> Submesh (inserts)
Material List -> Root
Material -> Material List (adds it to the end)
Material -> Material (inserts)
Texture List -> Root
Texture -> Texture List (adds it to the end)
Texture -> Texture (inserts)

From workspace:
Root -> Root
Frame -> Root
Frame -> Frame (adds it as a child of the target frame)
Submesh -> Mesh (adds it to the end)
Submesh -> Submesh (inserts)
Material List -> Root
Material -> Material List (adds it to the end)
Material -> Material (inserts)
Texture List -> Root
Texture -> Texture List (adds it to the end)
Texture -> Texture (inserts)


Using the Renderer
==================
The Renderer is only a preview. Things will probably look different in the game.
Select meshes from .xx tabs in the Editor. You can view meshes from different .xx files at the same time.
To view animations, open a .xa file in the Editor and select an Animation Clip. Then press the play button.
Deselect all animation clips to unload them from the Renderer.
If animations clips from multiple .xa files are loaded, they will all be applied and show a mixed animation.

Right-click and drag will pan the camera.
Left-click and drag will rotate the camera.
Using the scroll wheel will zoom in/out.


Other Notes
===========
General:
- Most of the main panels can be resized
- You can clear the Status Log by right-clicking on it and selecting "Clear Log"

Renderer:
- The Renderer receives focus when the mouse hovers over it. While you're editing a textbox, don't move the mouse over to the renderer or else you'll have to click the textbox again to continue typing

Mqo:
- Exporting/Importing .mqo always has "x10 Mode" enabled. All vertex coordinates are multipled by 10 when exporting and divided by 10 when importing. This makes it easier to edit in Metasequoia
- When importing .mqo, normals are automatically calculated over each mesh list
- The "World Coordinates" option for .mqo export multiplies vertices by their frame's combined transformation matrix, converting local coordinates to world coordinates. When exporting with this option, "[W]" is appended to the mesh object's name in the .mqo for automatic detection when importing back in SB3Utility

Hidden Hex Fields:
The following is a list of .xx hex fields that you can't edit in SB3Utility:
- Duplicate Vertex List: unknown[8]
- Texture: unknown[4]
- Texture: unknown[20]
These haven't been added to the GUI because there hasn't been a reason to edit them or lack of space in the GUI, but you can let me know if you want them added.
