Jump to content

SA Tools/SALVL/Object Definitions

From SA Docs
Revision as of 12:09, 14 March 2026 by PkR (talk | contribs)

Introduction to Object Definitions

An object definition is a part of a project template that enables SALVL to display 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.

Types of Object Definitions

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

  1. 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.
  2. 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 .cs files which are compiled by SALVL when it loads a stage.

Creating Object Definitions

To display a SET object in SALVL, several things are required. The following is a list of steps to go through to get an object working in the editor.

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 sadxlvl.ini is found in two locations. The file in SA Tools\GameConfig\PC_SADX (or PC_SA2) 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 sadxlvl.ini 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.

[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

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 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 sadxlvl.ini 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.

SALVL Object Editor that includes the Object Definition Editor.

Here is an example of a custom object definition for the jump panel (internal name O JPanel). Assuming we're still working with Emerald Coast, its entry will be in objdefs/stg01.ini.

Each entry 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.

[O JPanel]
codefile=objdefs/Common/JumpPanel.cs
codetype=SADXObjectDefinitions.Common.JumpPanel
Name=Jump Panel

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 / instead of backslash \ for all paths.

For a tutorial on creating code for a custom object definition, see 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 in the its entry 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 O EME P):

[O EME P]
Name=Emerald Shard
Model=object/obj_emekakera.nja.sa1mdl
Texture=OBJ_REGULAR
RotType=None
SclType=None

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 / instead of backslash \ for all paths.

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

SclType is the order in which the object's model should be scaled when the editor renders it. Most objects do not scale, so None is often used. The following values are possible:

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

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 lists.

Texlist is the name of the texture list file (.tls) 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 (True or False) that tells the renderer and collision checks to ignore the object's model (NJS_OBJECT)'s position.

Testing Object Definitions

To test an update to object definitions, copy the modified files in the objdefs folder to your mod project's objdefs 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 / instead of \ 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 4000 (16384 in decimal), see O STATION BACK in adv00.ini 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.

Retrieved from "https://sadocs.unreliable.network/index.php?title=SA_Tools/SALVL/Object_Definitions&oldid=726"