View source for SA Tools/SALVL/Object Definitions

== Introduction to Object Definitions ==
An object definition is a part of a [[SA Tools/Project template|project template]] that enables [[SA Tools/SALVL|SALVL]] to display [[SET Object|SET objects]] in the editor. The object definition sets up the object's model and textures, provides the position, rotation and scale routines to make the object look like it does ingame, and optionally converts SET data into customizable variables used to pick variations of the object or alter its behavior ingame.

At the moment, SALVL is lacking a lot of object definitions for many stages in both SADX and SA2, and contributions are highly appreciated.

=== Types of Object Definitions ===
Depending on the complexity of the object's rendering, object definitions can be either of the following two types:

# '''The default definition''' (also known as "script", "codeless" or "simple" definition) provides basic functionality to load and render a model. Many objects in the game will display in the editor with a properly configured default definition. For example, a ring or a stage decoration can work with the default definition.
# '''Custom definitions''' (also known as "code" definitions) provide custom code for loading the object, rendering its model(s) in the editor and collision checks. These definitions supply separate <code>.cs</code> files which are compiled by SALVL when it loads a stage.

=== Creating Object Definitions ===
The following is a list of steps to go through to get a SET object to display in SALVL.

==== Setting up stage properties ====
''Note: For PC versions of SADX and SA2 the work on this step has already been done for all stages. The information below is provided for reference.''

''Note 2: The file <code>sadxlvl.ini</code> is found in two locations. The file in <code>SA Tools\GameConfig\PC_SADX</code> (or <code>PC_SA2</code>) is copied to the project folder when you make a new mod project. If you are adding custom objects in your mod, edit the file in your mod project folder. If you are making object definitions for vanilla game objects, edit the main file.''

The <code>sadxlvl.ini</code> file should have an entry for the stage you need that defines level textures, object textures, the location of the object list INI file and the object definition list INI file. Here is an example for Emerald Coast Act 3.<syntaxhighlight lang="ini">[Action Stages\\Emerald Coast 3]
LevelGeometry=stg01_beach/landtable0102.c.sa1lvl
LevelID=0102
Textures=BEACH03
ObjectList=stg01_beach/objList.ini
ObjectTextureList=stg01_beach/objTextures.ini
DeathZones=stg01_beach/killcolli/act3/killZones.ini
Effects=objdefs/Level Effects/EmeraldCoast.cs
ObjectDefinition=objdefs/stg01.ini</syntaxhighlight>''LevelGeometry'' is the relative path to the [[LandTable]] file.

''LevelID'' is the internal ID used by the stage. The first two digits are level ID and the second two digits are act ID. For SA1, see [[Sonic Adventure/Level List]].

''Textures'' is the name of the texture file (usually PVM, GVM, PRS or PAK) '''without extension''' used for level textures.

''ObjectList'' is the relative path to the [[Object List]] split file.

''DeathZones'' is the relative path to the [[Death Zones]] split file.

''Effects'' is the relative path to the [[SA Tools/SALVL/Level Definition|Level Definition]] .cs file.

''ObjectDefinition'' is the relative path to the Object Definition list.

'''Editing the object's entry in the object definition list'''

''Note: The objdefs folder can be found in two locations. See the note about <code>sadxlvl.ini</code> in Step 1, it's the same principle.''

''Note: The text below describes manual editing of object definition entries in the INI file. If you prefer a GUI editor, you can use the Object Definition Editor in SALVL. Editing object definitions in SALVL will save them to your mod's project.''

Each entry in the object definition list should begin with the object's internal name in square brackets, which represents the INI section for the entry. All internal names are already filled in at the moment, so you only need to edit the parameters.
[[File:SA Tools SALVL Object Definitions 1773488122468.png|thumb|SALVL Object Editor that includes the Object Definition Editor.]]
Here is an example of a '''custom''' object definition for the jump panel (internal name <code>O JPanel</code>). Assuming we're still working with Emerald Coast, its entry will be in <code>objdefs/stg01.ini</code>.<syntaxhighlight lang="ini">
[O JPanel]
codefile=objdefs/Common/JumpPanel.cs
codetype=SADXObjectDefinitions.Common.JumpPanel
Name=Jump Panel
</syntaxhighlight>''Name'' is the name you would like the object to have when it appears on the SET item list.

''codefile'' is the relative path to the .cs file containing the code of the custom definition.

''codetype'' is the name of the class used by the definition.

'''Note: codefile and codetype are spelled in all lowercase.'''

'''Important! Use forward slash <code>/</code> instead of backslash <code>\</code> for all paths.'''

For a tutorial on creating code for a custom object definition, see [[SA Tools/SALVL/Object Definitions/Creating a Custom Object Definition|Creating a Custom Object Definition]].

However, many objects don't need a custom definition. For example, if the object only displays one model (as in, loaded from a single model file) and doesn't exhibit any complex behavior that needs to be accounted for in the editor, you can use the default object definition. In many cases, all you have to do is fill in a few parameters for its entry in the INI file to get the object to show up in the editor.

For an example of a codeless object definition, let's examine the entry for the Master Emerald shard (internal name <code>O EME P</code>):<syntaxhighlight lang="ini">
[O EME P]
Name=Emerald Shard
Model=object/obj_emekakera.nja.sa1mdl
Texture=OBJ_REGULAR
RotType=None
SclType=None
</syntaxhighlight>''Name'' is the name you would like the object to have when it appears on the SET item list.

''Model'' is the relative path to the object's model file.

''Texture'' is the filename (without extension) of the texture archive used for loading the object's textures.

'''Important! Use forward slash <code>/</code> instead of backslash <code>\</code> for all paths.'''

''RotType'' is the order in which the object's model should be '''rotated''' when the editor renders it. It can be <code>Y</code> if the object is only rotated on the Y axis (which is the most common), or <code>XYZ</code> if all axes are used for rendering. Any other combination of <code>X</code>, <code>Y</code> and/or <code>Z</code> can also be used. If the object model doesn't need to be rotated at all, use <code>None</code>.

''SclType'' is the order in which the object's model should be '''scaled''' when the editor renders it. Most objects do not scale, so <code>None</code> is often used. The following values are possible:<syntaxhighlight lang="ini">None, // Default scale (X=1.0, Y=1.0, Z=1.0)
XYZ, // Scale X, Y and Z
X, // Scale only by the X axis using the X Scale value
Y, // Scale only by the Y axis using the Y Scale value
Z, // Scale only by the Z axis using the Z Scale value
XY, // Scale the X axis using the X Scale value and then by the Y axis using the Y Scale value
XZ, // Scale the X axis using the X Scale value and then by the Z axis using the Z Scale value
YZ, // Scale the Y axis using the Y Scale value and then by the Z axis using the Z Scale value
AllX, // All axes are scaled by the X Scale value
AllY, // All axes are scaled by the Y Scale value
AllZ // All axes are scaled by the Z Scale value</syntaxhighlight>For the most part, filling in the above parameters (particularly ''Model'' and ''Texture'') is enough for the object to appear in SALVL. For slightly more complex objects the following additional parameters are available:

''TexturePacks'' is a comma-separated list of texture files without extension for objects in SA2 that use multiple [[Texture List|texture lists]].

''Texlist'' is the name of the texture list file (<code>.tls</code>) loaded by the object. This is required for objects that use multiple or partial texture lists.

''AddXPos'', ''AddYPos'' and ''AddZPos'' are floating point values that offset the model's initial transformation for rendering. For example, if your object sinks into the ground, it might need a positive ''AddYPos'', and if it appears higher than it should be it might need a negative ''AddYPos''.

''DefXRot'', ''DefYRot'' and ''DefZRot'' are initial rotations for objects that have a fixed rotation different from the one specified in the SET file.

''AddXRot'', ''AddYRot'' and ''AddZRot'' are rotation offsets that work just like ''AddXPos'', ''AddYPos'' and ''AddZPos'' but for rotations.

''Note: Rotation values are hexadecimal.''

''DefXScl'', ''DefYScl'', ''DefZScl'' are initial scale values, and ''AddXScl'', ''AddYScl'' and ''AddZScl'' are offset scale values that work under the same principle as the other offsets mentioned above.

''GndDst'' is "distance from the ground", a vertical offset used for placing objects on the ground in SALVL.

''IgnorePos'' is a boolean value (<code>True</code> or <code>False</code>) that tells the renderer and collision checks to ignore the object's model (<code>NJS_OBJECT</code>)'s position.

=== Testing Object Definitions ===
To test an update to object definitions, copy the modified files in the <code>objdefs</code> folder to your mod project's <code>objdefs</code> folder, (re)start SALVL, open your mod project and load the stage. The following is a list of common errors with object definitions and potential solutions.

==== Object displays as a box with a question mark ====
In most cases this means that the object definition is missing or incomplete. If you are using the default definition, make sure at least the ''Model'' and ''Texture'' fields are specified in the object definition list INI file.

==== SALVL Error: "SET objects failed to load their model(s). Please check SET object load errors in the log for details." ====
The most likely cause of the error is the model or texture file missing. In SALVL, select ''Help>View Log'' in the top menu and scroll to the bottom of the log to find the error. If you see "Exists: False", it means the model or texture file was not found. Make sure the path to the model or texture file is correct. Use <code>/</code> instead of <code>\</code> for all paths. If the model does not use textures, do not specify the texture file.

==== Object appears misrotated ====
Rotate the object using the editor's rotation gizmo to find the rotation values that make it look correct. Add the difference between these values as ''AddXRot'', ''AddYRot'' or ''AddZRot'' values in the object definition list INI file. Some objects are rotated on the Y axis by <code>4000</code> (16384 in decimal), see <code>O STATION BACK</code> in <code>adv00.ini</code> for an example. Alternatively, experiment with default rotations.

==== Object appears too small or too large ====
Set ''DefXScl'', ''DefYScl'' and/or ''DefZScl'', or add scale offsets in the object definition list INI file.

==== Object appears in the wrong place ====
If there is a fixed difference (always 10 units above or below etc.), add a position offset. Alternatively, add ''IgnorePos=True'' in the object definition list INI file. If that doesn't help, try a different rotation order or experiment with a combination of all of the above.