SA Tools/SALVL/Object Definitions - Revision history

PkR at 14:22, 14 March 2026

2026-03-14T14:22:09Z

← Older revision		Revision as of 14:22, 14 March 2026
Line 1:		Line 1:
	== Introduction to 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.		An object definition is a part of a [[SA Tools/Project Template\|project template]] that enables [[SA Tools/SALVL\|SALVL]] to display [[SET File\|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 object definitions for most stages in both SADX and SA2, and contributions are highly appreciated.		At the moment, SALVL is lacking object definitions for most stages in both SADX and SA2, and contributions are highly appreciated.

PkR at 12:19, 14 March 2026

2026-03-14T12:19:59Z

← Older revision		Revision as of 12:19, 14 March 2026
Line 2:		Line 2:
	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.		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.		At the moment, SALVL is lacking object definitions for most stages in both SADX and SA2, and contributions are highly appreciated.

	=== Types of Object Definitions ===		=== Types of Object Definitions ===

PkR at 12:19, 14 March 2026

2026-03-14T12:19:17Z

← Older revision		Revision as of 12:19, 14 March 2026
Line 1:		Line 1:
	== Introduction to 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.		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 ===		=== Types of Object Definitions ===

PkR at 12:12, 14 March 2026

2026-03-14T12:12:35Z

← Older revision		Revision as of 12:12, 14 March 2026
Line 63:		Line 63:
	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]].		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 in the ~~its entry~~ to get the object to show up in the editor.		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">		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">

PkR at 12:11, 14 March 2026

2026-03-14T12:11:16Z

← Older revision		Revision as of 12:11, 14 March 2026
Line 43:		Line 43:

	''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.''		''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.]]		[[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>.		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">

	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.<syntaxhighlight lang="ini">
	[O JPanel]		[O JPanel]
	codefile=objdefs/Common/JumpPanel.cs		codefile=objdefs/Common/JumpPanel.cs

PkR at 12:09, 14 March 2026

2026-03-14T12:09:58Z

← Older revision		Revision as of 12:09, 14 March 2026
Line 9:		Line 9:

	=== Creating Object Definitions ===		=== 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~~.		The following is a list of steps to go through to get a SET object to display in SALVL.

	==== Setting up stage properties ====		==== Setting up stage properties ====

PkR at 12:09, 14 March 2026

2026-03-14T12:09:24Z

← Older revision		Revision as of 12:09, 14 March 2026
Line 6:		Line 6:

	# '''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.		# '''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) ~~that~~ provide ~~their own~~ code for loading the object, rendering its model(s) in the editor and collision checks. These definitions supply ~~their own~~ code ~~in separate~~ .cs files which are compiled by SALVL when it loads a stage.		# '''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 ===		=== Creating Object Definitions ===

PkR at 12:05, 14 March 2026

2026-03-14T12:05:29Z

← Older revision		Revision as of 12:05, 14 March 2026
Line 3:		Line 3:

	=== Types of Object Definitions ===		=== Types of Object Definitions ===
	Depending on the complexity of the object's rendering, object definitions can be ~~one~~ of the following two types:		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.		# '''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.

PkR at 12:04, 14 March 2026

2026-03-14T12:04:36Z

@@ Line 36: / Line 36: @@
 ''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 split file.
+''ObjectDefinition'' is the relative path to the Object Definition list.
 '''Editing the object's entry in the object definition list'''
@@ Line 58: / Line 58: @@
 '''Note: codefile and codetype are spelled in all lowercase.'''
 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]].
@@ Line 75: / Line 77: @@
 ''Texture'' is the filename (without extension) of the texture archive used for loading the object's textures.
 ''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>.
@@ Line 99: / Line 103: @@
 ''AddXRot'', ''AddYRot'' and ''AddZRot'' are rotation offsets that work just like ''AddXPos'', ''AddYPos'' and ''AddZPos'' but for rotations.
 ''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.
@@ Line 105: / Line 111: @@
 ''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.

PkR at 11:42, 14 March 2026

2026-03-14T11:42:18Z

← Older revision		Revision as of 11:42, 14 March 2026
Line 14:		Line 14:
	''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: 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.''		''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 ~~file `~~sadxlvl.ini` 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]		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		LevelGeometry=stg01_beach/landtable0102.c.sa1lvl
	LevelID=0102		LevelID=0102
Line 40:		Line 40:
	'''Editing the object's entry in 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 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.''		''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.''
	[[File:SA Tools SALVL Object Definitions 1773488122468.png\|thumb\|SALVL Object Editor that includes the Object Definition Editor.]]		[[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 `O JPanel`). Assuming we're still working with Emerald Coast, its entry will be in `objdefs/stg01.ini`.		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>.

	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.<syntaxhighlight lang="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.<syntaxhighlight lang="ini">
Line 63:		Line 63:
	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.		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`):<syntaxhighlight lang="ini">		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]		[O EME P]
	Name=Emerald Shard		Name=Emerald Shard
Line 76:		Line 76:
	''Texture'' is the filename (without extension) of the texture archive used for loading the object's textures.		''Texture'' is the filename (without extension) of the texture archive used for loading the object's textures.

	''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`.		''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 `None` is often used. The following values are possible:<syntaxhighlight lang="ini">None, // Default scale (X=1.0, Y=1.0, Z=1.0)		''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		XYZ, // Scale X, Y and Z
	X, // Scale only by the X axis using the X Scale value		X, // Scale only by the X axis using the X Scale value
Line 92:		Line 92:
	''TexturePacks'' is a comma-separated list of texture files without extension for objects in SA2 that use multiple [[Texture List\|texture lists]].		''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 (.tls) loaded by the object. This is required for objects that use multiple or partial 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''.		''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''.
Line 104:		Line 104:
	''GndDst'' is "distance from the ground", a vertical offset used for placing objects on the ground in SALVL.		''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.		''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.