SA Docs - User contributions [en]

SA Tools/Contributing to the tools

2026-03-15T02:10:51Z

PkR:

= Building SA Tools =
Prerequisites:
* Visual Studio 2022
* .NET 8.0 Desktop runtime

To produce a package, build the <code>SA Tools.sln</code> file in Visual Studio and run <code>buildSATools.exe</code> in the solution's root folder. The package is placed in the <code>output</code> folder by default. Run <code>buildSATools.exe</code> with the <code>-help</code> command line switch for additional build settings.

= Contributing to SA Tools =
There are many ways to contribute to the development of SA Tools, some of which don't require any programming knowledge.

== Updating Game Templates ==
Game [[Project Templates|templates]] used by the tools contain information on how to extract levels, models, animations and other data from the games. Work has been done to identify this data and extract it in a way that could resemble the original source assets.

=== Object Definitions ===
For [[SA Tools/SALVL|SALVL]] to display objects in the editor, [[SA Tools/SALVL/Object Definitions|Object Definitions]] are required. A lot of definitions are currently missing, and any contributions of definitions to cover vanilla game objects are highly appreciated.

=== Metadata Fields ===
To make it easier for the end users to find the assets they want, most data in mod projects has meta sections that contains descriptions, texture files to use etc. This is used in the menu in [[SA Tools/SAMDL|SAMDL]] that appears when you load a project file. However, not all models have descriptions or texture files defined at the moment.

Any help on updating the metadata is appreciated. The metadata is stored as additional fields in INI files for each template in the <code>GameConfig</code> folder.

If you want to update existing labels, please focus on PC ports of SA1 and SA2 as these have the most complete split data, and the labels can be transferred to different versions without redoing them all over.

=== Split Data ===
You can add more data to existing templates, or make new templates for other versions of SA1 and SA2 on different platforms, including prototypes, region exclusive trial versions etc.

If you know the location of a model, animation, texture list etc. that isn't included in a game template's split configuration, please add it to the template. If you are working with a console version of the game, make sure asset filenames match those of their PC counterparts.

== Documentation ==
Documentation for some tools is lacking or missing entirely. If you have learned how to use a certain tool or feature and want to make it more accessible for others, you can update this wiki to share your knowledge with others!

== Bug Reports ==
Any well-structured bug report for a reproducible issue is an important contribution to the development of SA Tools. While there is no guarantee that all issues will be resolved, a reported bug has a higher chance of being fixed than an unreported one.

SA Tools/SALVL/Object Definitions

2026-03-14T14:22:09Z

PkR:

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

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

SA Tools/SALVL/Object Definitions

2026-03-14T12:19:59Z

PkR:

== 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 object definitions for most 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.

SA Tools/SALVL/Object Definitions

2026-03-14T12:19:17Z

PkR:

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

SA Tools/SALVL/Object Definitions

2026-03-14T12:12:35Z

PkR:

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

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

SA Tools/SALVL/Object Definitions

2026-03-14T12:11:16Z

PkR:

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

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

SA Tools/SALVL/Object Definitions

2026-03-14T12:09:58Z

PkR:

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

=== 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.''
[[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>.

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

SA Tools/SALVL/Object Definitions

2026-03-14T12:09:24Z

PkR:

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

=== 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 ===
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 <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.''
[[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>.

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

SA Tools/SALVL/Object Definitions

2026-03-14T12:05:29Z

PkR:

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

=== 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) 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.

=== 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 <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.''
[[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>.

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

SA Tools/SALVL/Object Definitions

2026-03-14T12:04:36Z

PkR:

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

=== Types of Object Definitions ===
Depending on the complexity of the object's rendering, object definitions can be one 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) 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.

=== 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 <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.''
[[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>.

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

SA Tools/SALVL/Object Definitions

2026-03-14T11:42:18Z

PkR:

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

=== Types of Object Definitions ===
Depending on the complexity of the object's rendering, object definitions can be one 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) 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.

=== 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 <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 split file.

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

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

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.

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.

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

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

SA Tools/SALVL/Object Definitions

2026-03-14T11:38:52Z

PkR: Created page with "== 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..."

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

=== Types of Object Definitions ===
Depending on the complexity of the object's rendering, object definitions can be one 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) 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.

=== 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 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]
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 split file.

'''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.''
[[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`.

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

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.

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

''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:<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 (.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.

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

File:SA Tools SALVL Object Definitions 1773488122468.png

2026-03-14T11:35:22Z

PkR:

SALVL

2026-03-14T09:45:50Z

PkR: PkR moved page SALVL to SA Tools/SALVL

#REDIRECT [[SA Tools/SALVL]]

SA Tools/SALVL

2026-03-14T09:45:50Z

PkR: PkR moved page SALVL to SA Tools/SALVL

SALVL is a level editor for the Sonic Adventure games. It is primarily meant for editing SADX PC (2004) layouts, with limited support for other games.

== Navigating the Editor ==
[[File:Labeled SALVL Interface.png|thumb|443x443px|The interface of SALVL, with the individual windows highlighted.]]

=== 3D Viewport ===
The ''3D Viewport'' (highlighted in yellow) is the primary window for the interface. You can use it to fly around and view the stage from various angles, select, move, and rotate objects within the scene; and various other tasks.

See [[3D Editor Controls]] for default camera controls.

=== Scene Graph ===
The Scene graph (highlighted in blue) shows a list of everything inside of the level that can be edited, sorted by type. You can select items here and it will function in exactly the same way as if you had clicked the item inside of the viewport. The Scene graph supports multi-select by holding the SHIFT key.

=== Inspector ===
Every object in the game world has many properties associated with it, and many times the game have properties that cannot be manipulated directly in 3D space via the viewport. For this reason, the Inspector (highlighted in green) will display as much information as possible about the currently selected object (''In the case of multiple selected objects at once, it will display information that is common across the entire selection'').

=== Character Select ===
The character select (highlighted in purple) behaves exactly like you expect it would. Click on a character's icon to switch their version of the stage. Note that this only changes the currently loaded SET and CAM layouts, as all characters share stage geometry.

=== Model/SET Library (Unfinished) ===
The model library (highlighted in red) is a palette that contains a series of 3d models, stored in memory until you decide to add them to the stage. You can add a model from the model library to the stage by clicking on it and dragging the icon into the 3d viewport. You can import external 3d model files (obj and sa1mdl formats supported) into the Model Library by using the File->Import->To Model Library menu option. It is currently unfinished and is disabled by default. You can enable it by unchecking View->Disable Model Library.

=== Transform Handle Tools ===
[[File:SALVL_Transform_Handles.png|thumb|The following menu buttons alter the behavior of the transform handle.]]
SALVL uses a feature called a Transform Handle for manipulating the selected stage objects. The transform handle resides in the 3D viewport and is directly manipulated by the mouse, using a click and drag action.

=== Lights Editor ===
SADX has two types of light data: Stage Lights (<code>LE_LIGHT_ENV</code>) and Character Lights (<code>LE_PALIGHT_ENV</code>). Stage Lights are used for level and object models, while Character Lights are used for characters, some specific enemies and bosses. You can edit both types of lights and preview changes in the editor. If a light of a selected type is not present in the selected level, click the <code>+</code> button to create it (if a light already exists, it will be overwritten with default data). To clear the current light, click the <code>-</code> button. Click <code>Apply</code> to update the lights in the main editor.

==== Stage Lights ====
[[File:SALVL_Stage_Lights_Editor.png|thumb|313x313px]]
Each act in a level can have up to four Stage Lights. You can switch between the four lights using the Light Index control. Each light has the following parameters:

* '''Diffuse Color'''
* '''Ambient Color'''
* '''Diffuse''': Directional light intensity
* '''Specular''': Unused
* '''Use Direction''': Indicates a directional light; if this flag is disabled, only ambient lighting will be used
* '''Light Direction'''

==== Character Lights ====
[[File:SALVL_Character_Lights_Editor.png|thumb]]
Each act in a level has three types of Character Lights:

* '''Character''': Used for most playable characters and NPCs, as well as some enemies such as the Spinners
* '''Character Alt.''': Additional light type used for Super Sonic, E-102 Gamma and some Egg Carrier NPCs
* '''Boss''': Used for boss models

Each Character Light can be configured with the following parameters:

* '''Enabled''': If this flag is off, the game will use the light from the previous act, or a default one if it doesn't exist or is disabled
* '''Use Direction''': If this flag is enabled, the game will use this light's direction; if this flag is disabled, the game will use the Stage Light's direction
* '''Ignore Direction''': If this flag is enabled, light direction will not be set
* '''Double''': If this flag is enabled, an additional light will be created with an inverted direction
* '''Diffuse''': Unused
* '''Light Direction'''
* '''Ambient Color'''
* '''Color 1 RGB and Power''': First component used for diffuse palette generation (see notes)
* '''Color 2 RGB and Power''': Second component used for diffuse palette generation (see notes)
* '''Specular 1 RGB and Power''': First component used for specular palette generation (see notes)
* '''Specular 2 RGB and Power''': Second component used for specular palette generation (see notes)

==== Notes on Lights ====

* The lighting system described above is used in SADX Gamecube and later ports. The original Dreamcast version uses a different system that loads lighting data from PL and SL files. Use PLTool to edit those.
* The lights are applied differently in the Gamecube version, so the same values will produce different results in the PC version.
* The Gamecube version generates 256-color palettes for diffuse (Color 1 and Color 2) and specular (Specular 1 and Specular 2) character lighting, which are used as a lookup texture in a way similar to the palettes in the original Dreamcast game's lighting system. However, in all later ports (including the PC version) there is no palette generation, and only Ambient Color and Specular 1 RGB have any meaningful effect.
* Specular lighting is disabled for Stage Lights, and the <code>Specular</code> value has no effect.
* The <code>Diffuse</code> value has no effect on Character Lights.
* For Station Square and the Mystic Ruins, Act 0 is Day, Act 1 is Evening and Act 2 is Night. Sky Deck Act 3 and Twinkle Park entrance area in Station Square use hardcoded lighting that cannot be edited in SALVL. Casinopolis has hardcoded light rotation. Some other levels have hardcoded ambient color or light direction overrides.

=== Fog Editor ===
[[File:SALVL_Fog_Editor.png|thumb|454x454px]]
SADX PC has fog settings for each detail (clip) level. Since lower clip settings were meant for underpowered machines by 2004 standards, in the majority of cases there is no point in using anything other than High (Far). If a selected act in a stage does not have fog data, click the <code>+</code> button to create it (if fog data already exists, it will be overwritten with default data). To remove current fog data, click the <code>-</code> button. Click <code>Apply</code> to update fog in the main editor.

The following fog parameters can be adjusted:

* '''Fog Toggle''': Enables or disables fog for this act and detail setting.
* '''Fog Start''': Distance from camera where fog starts.
* '''Fog End''': Distance from camera where fog ends.
* '''Fog Color'''

==== Notes on Fog ====

* Positive and negative values for Fog Start and Fog End produce the same results.
* The game uses default fog settings if the difference between Fog Start and Fog End is too small. This behavior is replicated in the editor.
* The A value in Fog Color is ignored.
* In some areas, such as Lost World Act 2, there are hardcoded fog overrides that cannot be edited in SALVL.
* In the Mystic Ruins, the following Acts are used for different times of day:
** Day: Level act number matches fog act number
** Evening: Act 0 (Station) is 4, Acts 1 (Angel Island) and 2 (Jungle) are 5
** Night: Act 0 (Station) is 6, Acts 1 (Angel Island) and 2 (Jungle) are 7
** Act 3 (Mystic Ruins Base) always uses 3

{{SAToolsNavbox}}

MediaWiki:Common.css

2026-03-11T04:02:47Z

PkR:

img {
filter: none !important;
background-color: transparent !important;
}

.thumbinner {
filter: none !important;
background-color: transparent !important;
}

MediaWiki:Common.css

2026-03-11T03:57:28Z

PkR:

img {
filter: none !important;
}

MediaWiki:Common.css

2026-03-11T03:52:59Z

PkR: Created page with "/* CSS placed here will be applied to all skins */ /* Remove gray filter/dimming from images in Vector 2022 dark mode */ html.skin-theme-client-night .mw-page-container img, html.skin-theme-client-night .mw-page-container video { filter: none !important; }"

/* CSS placed here will be applied to all skins */
/* Remove gray filter/dimming from images in Vector 2022 dark mode */
html.skin-theme-client-night .mw-page-container img,
html.skin-theme-client-night .mw-page-container video {
filter: none !important;
}

Sonic Adventure Autodemo/Restoration

2026-03-02T04:51:51Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure DX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the [[Sonic Adventure Autodemo]] was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on [https://forums.sonicretro.org/posts/937406/ booting Sky Deck] as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This project is a collaboration between x-hax users, using symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new [https://github.com/X-Hax/dreamcast-mods/raw/refs/heads/main/AutoDemoPointers.xlsx spreadsheet] of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a [https://github.com/X-Hax/dreamcast-mods/raw/refs/heads/main/AutoDemoPointers.xlsx spreadsheet] along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to add missing textures to the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version (where missing textures were recreated by its developers) and Dreamcast SDKs (which surprisingly have some early SA1 textures). Apart from making stages bootable and readding textures, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, restoring debug functionality etc.

The restoration was primarily discussed in a series of threads on x-hax Discord, which have been archived below:

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/sa1-modding%20-%20New%20Autodemo%20research.html Thread 1: New Autodemo Research (May 10, 2024)]

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/sa1-modding%20-%20Autodemo%20research.html Thread 2: Autodemo Research (Private Version, May 10 - June 18, 2024)]

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/game-research%20-%20Sonic%20Adventure%20Autodemo.html Thread 3: Game Research: Sonic Adventure Autodemo (Public Version, June 7, 2024 - February 28, 2026)]

== Restoration Details ==

=== Twinkle Park ===
Twinkle Park was the first stage restored by ''Speeps''.

=== Stage Select ===
The Stage Select screen is similar to the final version. ''woofmute'' and ''PkR'' found out that the texture error at the bottom right was caused by the game trying to load character pictures, which were added back afterwards.<gallery mode="nolines">
File:Sonic Adventure Autodemo Restoration 1772422970977.png|Autodemo Stage Select with the texture error (''MainJP'')
File:Sonic Adventure Autodemo Restoration 1772422993825.png|Autodemo Stage Select with character pictures (''woofmute'')
</gallery>

=== Debug Functionality ===
The SET Editor was restored by ''woofmute''.

=== Ninja Lights ===

=== Practice Stages ===
''Speeps'': It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

''PkR'': Practice 2 did not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Ninja Lights]] are used instead.
{| class="wikitable"
|+Autodemo Practice Stages
![[File:Sonic Adventure Autodemo Restoration 1772347046976.mp4|none|thumb|Gamma in Practice Stage (''Speeps'')]]
![[File:Pinball mode practice.mp4|thumb|Pinball mode in Practice Stage (''MainJP'')|none]]
|}
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

Sonic Adventure Autodemo/Restoration

2026-03-02T03:46:59Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the [[Sonic Adventure Autodemo]] was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on [https://forums.sonicretro.org/posts/937406/ booting Sky Deck] as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This project is a collaboration between x-hax users, using symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new [https://github.com/X-Hax/dreamcast-mods/raw/refs/heads/main/AutoDemoPointers.xlsx spreadsheet] of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a [https://github.com/X-Hax/dreamcast-mods/raw/refs/heads/main/AutoDemoPointers.xlsx spreadsheet] along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to add missing textures to the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version (where missing textures were recreated by its developers) and Dreamcast SDKs (which surprisingly have some early SA1 textures). Apart from making stages bootable and readding textures, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, restoring debug functionality etc.

The restoration was primarily discussed in a series of threads on x-hax Discord, which have been archived below:

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/sa1-modding%20-%20New%20Autodemo%20research.html Thread 1: New Autodemo Research (May 10, 2024)]

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/sa1-modding%20-%20Autodemo%20research.html Thread 2: Autodemo Research (Private Version, May 10 - June 18, 2024)]

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/game-research%20-%20Sonic%20Adventure%20Autodemo.html Thread 3: Game Research: Sonic Adventure Autodemo (Public Version, June 7, 2024 - February 28, 2026)]

== Restoration Details ==

=== Twinkle Park ===
Twinkle Park was the first stage restored by ''Speeps''.

=== Stage Select ===
The Stage Select screen is similar to the final version. ''woofmute'' and ''PkR'' found out that the texture error at the bottom right was caused by the game trying to load character pictures, which were added back afterwards.<gallery mode="nolines">
File:Sonic Adventure Autodemo Restoration 1772422970977.png|Autodemo Stage Select with the texture error (''MainJP'')
File:Sonic Adventure Autodemo Restoration 1772422993825.png|Autodemo Stage Select with character pictures (''woofmute'')
</gallery>

=== Debug Functionality ===
The SET Editor was restored by ''woofmute''.

=== Ninja Lights ===

=== Practice Stages ===
''Speeps'': It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

''PkR'': Practice 2 did not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Ninja Lights]] are used instead.
{| class="wikitable"
|+Autodemo Practice Stages
![[File:Sonic Adventure Autodemo Restoration 1772347046976.mp4|none|thumb|Gamma in Practice Stage (''Speeps'')]]
![[File:Pinball mode practice.mp4|thumb|Pinball mode in Practice Stage (''MainJP'')|none]]
|}
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

Sonic Adventure Autodemo/Restoration

2026-03-02T03:45:22Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the [[Sonic Adventure Autodemo]] was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on [https://forums.sonicretro.org/posts/937406/ booting Sky Deck] as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This project is a collaboration between x-hax users, using symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new [https://github.com/X-Hax/dreamcast-mods/raw/refs/heads/main/AutoDemoPointers.xlsx spreadsheet] of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a [https://github.com/X-Hax/dreamcast-mods/raw/refs/heads/main/AutoDemoPointers.xlsx spreadsheet] along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to add missing textures to the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version (where missing textures were recreated by its developers) and Dreamcast SDKs (which surprisingly have some early SA1 textures). Apart from making stages bootable and readding textures, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, restoring debug functionality etc.

The restoration was primarily discussed in a series of threads on x-hax Discord, which have been archived below:

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/sa1-modding%20-%20New%20Autodemo%20research.html Thread 1: New Autodemo Research (May 10, 2024)]

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/sa1-modding%20-%20Autodemo%20research.html Thread 2: Autodemo Research (Private Version, May 10 - June 18, 2024)]

[https://dcmods.unreliable.network/owncloud/data/PiKeyAr/files/SA1%20research/autodemo/threads/game-research%20-%20Sonic%20Adventure%20Autodemo.html Thread 3: Game Research: Sonic Adventure Autodemo (Public Version, June 7, 2024 - February 28, 2026)]

== Restoration Details ==

=== Twinkle Park ===
Twinkle Park was the first stage restored by ''Speeps''.

=== Stage Select ===
The Stage Select screen is similar to the final version. ''woofmute'' and ''PkR'' found out that the texture error at the bottom right was caused by the game trying to load character pictures, which were added back afterwards.

[[File:Sonic Adventure Autodemo Restoration 1772422970977.png|left|Autodemo Stage Select with the texture error (''MainJP'')]]
[[File:Sonic Adventure Autodemo Restoration 1772422993825.png|right|Autodemo Stage Select with character pictures (''woofmute'')]]

=== Debug Functionality ===
The SET Editor was restored by ''woofmute''.

=== Ninja Lights ===

=== Practice Stages ===
''Speeps'': It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

''PkR'': Practice 2 did not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Ninja Lights]] are used instead.
{| class="wikitable"
|+Autodemo Practice Stages
![[File:Sonic Adventure Autodemo Restoration 1772347046976.mp4|none|thumb|Gamma in Practice Stage (''Speeps'')]]
![[File:Pinball mode practice.mp4|thumb|Pinball mode in Practice Stage (''MainJP'')|none]]
|}
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

File:Sonic Adventure Autodemo Restoration 1772422993825.png

2026-03-02T03:43:16Z

PkR:

File:Sonic Adventure Autodemo Restoration 1772422970977.png

2026-03-02T03:42:53Z

PkR:

Sonic Adventure Autodemo/Restoration

2026-03-01T16:10:25Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the Sonic Adventure Autodemo was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on booting Sky Deck as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This restoration was achieved in 2024 through a collaboration of x-hax users and symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new spreadsheet of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to find missing textures in the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version, where missing textures were recreated by its developers, and Dreamcast SDKs, which surprisingly have some early SA1 textures.

Apart from making stages bootable, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, adding textures that are missing on the disc, restoring debug functionality etc.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a spreadsheet along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

The restoration was primarily discussed in a series of threads on x-hax Discord. An archive of the discussion will be available for download at a later date.

== Restoration Details ==

=== Stage Select ===

=== Debug Functionality ===

=== Ninja Lights ===

=== Practice Stages ===
''Speeps'': It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

''PkR'': Practice 2 did not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Ninja Lights]] are used instead.
{| class="wikitable"
|+Autodemo Practice Stages
![[File:Sonic Adventure Autodemo Restoration 1772347046976.mp4|none|thumb|Gamma in Practice Stage (''Speeps'')]]
![[File:Pinball mode practice.mp4|thumb|Pinball mode in Practice Stage (''MainJP'')|none]]
|}
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Twinkle Park ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

Sonic Adventure Autodemo/Restoration

2026-03-01T06:56:26Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the Sonic Adventure Autodemo was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on booting Sky Deck as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This restoration was achieved in 2024 through a collaboration of x-hax users and symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new spreadsheet of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to find missing textures in the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version, where missing textures were recreated by its developers, and Dreamcast SDKs, which surprisingly have some early SA1 textures.

Apart from making stages bootable, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, adding textures that are missing on the disc, restoring debug functionality etc.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a spreadsheet along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

The restoration was primarily discussed in a series of threads on x-hax Discord. An archive of the discussion will be available for download at a later date.

== Restoration Details ==

=== Stage Select ===

=== Debug Functionality ===

=== Ninja Lights ===

=== Practice Stages ===
''Speeps'': It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

''PkR'': Practice 2 did not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Ninja Lights]] are used instead.
{| class="wikitable"
|+Autodemo Practice Stages
![[File:Sonic Adventure Autodemo Restoration 1772347046976.mp4|none|thumb|Gamma in Practice Stage (shared by ''Speeps'')]]
![[File:Pinball mode practice.mp4|thumb|Pinball mode in Practice Stage (shared by ''MainJP'')|none]]
|}
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Twinkle Park ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

Sonic Adventure Autodemo/Restoration

2026-03-01T06:38:49Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the Sonic Adventure Autodemo was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on booting Sky Deck as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This restoration was achieved in 2024 through a collaboration of x-hax users and symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new spreadsheet of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to find missing textures in the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version, where missing textures were recreated by its developers, and Dreamcast SDKs, which surprisingly have some early SA1 textures.

Apart from making stages bootable, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, adding textures that are missing on the disc, restoring debug functionality etc.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a spreadsheet along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

The restoration was primarily discussed in a series of threads on x-hax Discord. An archive of the discussion will be available for download at a later date.

== Restoration Details ==

=== Stage Select ===

=== Debug Functionality ===

=== Ninja Lights ===

=== Practice Stages ===
''Speeps'': It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

''PkR'': Practice 2 did not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Ninja Lights]] are used instead.
[[File:Sonic Adventure Autodemo Restoration 1772347046976.mp4|none|thumb|Gamma in Practice Stage (shared by ''Speeps'')]]
[[File:Pinball mode practice.mp4|thumb|Pinball mode in Practice Stage (shared by ''MainJP'')|none]]
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Twinkle Park ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

File:Sonic Adventure Autodemo Restoration 1772347046976.mp4

2026-03-01T06:37:32Z

PkR:

Sonic Adventure Autodemo/Restoration

2026-03-01T06:35:07Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the Sonic Adventure Autodemo was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on booting Sky Deck as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This restoration was achieved in 2024 through a collaboration of x-hax users and symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new spreadsheet of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to find missing textures in the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version, where missing textures were recreated by its developers, and Dreamcast SDKs, which surprisingly have some early SA1 textures.

Apart from making stages bootable, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, adding textures that are missing on the disc, restoring debug functionality etc.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a spreadsheet along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

The restoration was primarily discussed in a series of threads on x-hax Discord. An archive of the discussion will be available for download at a later date.

== Restoration Details ==

=== Stage Select ===

=== Debug Functionality ===

=== Ninja Lights ===

=== Practice Stages ===
It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

Practice 2 does not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Sonic Adventure/Ninja Lights|Ninja Lights]] are used instead.
[[File:Pinball mode practice.mp4|thumb|Pinball mode in Practice Stage (shared by ''MainJP'')|none]]
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Twinkle Park ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

Sonic Adventure Autodemo/Restoration

2026-03-01T06:34:39Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the Sonic Adventure Autodemo was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on booting Sky Deck as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This restoration was achieved in 2024 through a collaboration of x-hax users and symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new spreadsheet of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to find missing textures in the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version, where missing textures were recreated by its developers, and Dreamcast SDKs, which surprisingly have some early SA1 textures.

Apart from making stages bootable, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, adding textures that are missing on the disc, restoring debug functionality etc.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a spreadsheet along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

The restoration was primarily discussed in a series of threads on x-hax Discord. An archive of the discussion will be available for download at a later date.

== Restoration Details ==

=== Stage Select ===

=== Debug Functionality ===

=== Ninja Lights ===

=== Practice Stages ===
It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

Practice 2 does not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Sonic Adventure/Ninja Lights|Ninja Lights]] are used instead.
[[File:Pinball mode practice.mp4|thumb|left|Pinball mode in Practice Stage (shared by ''MainJP'')]]
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Twinkle Park ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

File:SAAD CurrentMRTextureWork.mp4

2026-03-01T05:52:22Z

PkR: Created blank page

File:2025-12-14 13-49-20.mp4

2026-03-01T05:51:47Z

PkR:

File:2024-07-27 14-59-17.mp4

2026-03-01T05:50:40Z

PkR:

File:SAAD BGMCasinopolis edit.mp4

2026-03-01T05:50:10Z

PkR:

File:2024-07-16 22-31-49.mp4

2026-03-01T05:50:02Z

PkR:

File:2026-01-18 07-38-23 edit.mp4

2026-03-01T05:49:38Z

PkR:

File:2024-06-18 10-59-18 edit.mp4

2026-03-01T05:49:17Z

PkR:

Ninja Lights

2026-03-01T03:10:20Z

PkR:

"Ninja Lights" refers to the lighting used by the Ninja library of the [[Katana SDK]].

== Ninja Lights in Sonic Adventure ==
'''Note: Ninja Lights are not implemented in the Lantern Engine mod, so the information below is irrelevant to the PC version.'''

Sonic Adventure (Dreamcast) uses two lighting systems: the palette-based [[Sonic Adventure/Lantern Engine|LANTERN system]] and the Ninja Lights. The game's model rendering functions have "Lantern" and "Ninja" variants, and depending on the function used the game can either draw the model with palette lighting or use Ninja Lights.

The SL file contains data for setting up the Ninja lights. This information consists of: light color (three floats for R/G/B), diffuse multiplier, specular power and ambient multiplier. Both diffuse and specular components are the same color. The “ignore specular” material flag disables the specular component per mesh.

=== Types of Ninja Lights Setup ===
There are three types of lights used for non-palettized models in the game:
{| class="wikitable"
!Lighting Setup
!Description
!Used by
|-
|Two Ninja Lights
|Non-palettized lighting that uses two Ninja Lights. These lights use <code>NJS_LIGHT</code> structures described in the Katana SDK. One is set up using the parameters in the SL file (let’s call it the <code>ENV</code> Light), and the other is set up in code, usually in level binaries (let’s call it the <code>DIR</code> light). The <code>ENV</code> light has one configurable color that is shared for diffuse and specular, the <code>DIR</code> light can have different diffuse and specular color (though the game doesn’t seem to use that). It can also have a different light direction.
|Common switch, Hint monitor, OEggKanban (glowing Eggman logo in Final Egg, tube parts only), Chaos puddle in some cutscenes, Aoki Switch (top)
|-
|Simple Ninja Light
|Non-palettized lighting that uses one Ninja Light using the parameters from the SL file except the color, which is always white.
|Rock bits in Red Mountain, non-Jewel Chao, Master Emerald pieces, Froggy in Gamma’s Emerald Coast
|-
|Easy Light
|Non-palettized lighting that sets up the Easy Light (not <code>NJS_LIGHT</code>) using the parameters from the SL file. The Easy light is described in the Katana SDK. It doesn’t support specular lighting.
|Snowboard, OSandSwitch (Sand Hill switch), shadow blob, Chambr (chambers with opening doors in Sky Deck), debug objects, Aoki Switch (bottom), E101’s missiles, Hedgehog Hammer targets
|}

=== Rendering Functions and their SADX Counterparts ===
In SA1, most models were rendered with palette lighting using the game's custom function, but some models were rendered by calling Ninja drawing functions directly, which made them use the Ninja lights system. There are three light setups depending on the specific variation of the Ninja draw function:
{| class="wikitable"
!Light setup
!Functions in SADX (PC, 2004)
!Comment
|-
|Regular
|<code>njDrawModel</code> (0077EF70)
|Allows to use multiple <code>NJS_LIGHT</code>s of various types (directional, point, spot). Specular is supported.
|-
|Simple
|<code>___SAnjSimpleDrawModel</code> (00408520), <code>__SAnjSimpleDrawObject</code> (0040A130)
|Only the first registered <code>NJS_LIGHT</code> can be used. It is set up as a directional light, and intensity and color settings cannot be adjusted. Specular is supported.
|-
|Easy
|<code>njEasyDrawObject</code> (0040A100), <code>njEasyDrawModel</code> (004084F0), <code>njEasyDrawMotion</code> (00406FA0), <code>njEasyDrawShapeMotion</code> (00406FE0)
|Uses one "easy" light (not <code>NJS_LIGHT</code>). Specular is not supported. From the SDK: The light vector uses the screen space coordinate system. E.g. if set up like <code>njSetEasyLight( 0.0f, 0.0f, 1.0f );</code>, the light source will always be in front of the screen. To set the light source in 3D space, they must be converted with the current matrix:<syntaxhighlight lang="cpp">
light.x = LIGHT3D_X;
light.y = LIGHT3D_Y;
light.z = LIGHT3D_Z;
njCalcVector( NULL, &light, &lwork );
njSetEasyLight( lwork.x, lwork.y, lworkz );
</syntaxhighlight>After this, the Easy light source will be at <code>LIGHT3D_X, LIGHT3D_Y, LIGHT3D_Z</code>.
|}
The SADX functions are a rough match since SADX changed draw functions for a lot of objects, and all that is left is some wrapper functions that call a more generic draw function:

# The Regular functions are difficult to tell from the paletted functions, so the above table is an approximation.
# The Easy functions are mostly still there.
# The Simple functions only have two stubs which aren't called by anything other than the Chao Name Machine, which doesn't match SA1.

=== Lighting Data ===
The data sources for the lights are as follows:
{| class="wikitable"
!Light
!Type
!Direction
!Color
!Diffuse, specular, ambient intensity
|-
|Regular - light 1
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file
|-
|Regular - light 2
|Directional
|<code>njSetLightDirection</code> called in the skybox display function
|<code>njSetLightColor</code> called in the skybox display function
|<code>njSetLightIntensity</code> called in the skybox display function
|-
|Simple
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|White (in SA1 anyway)
|From the SL file
|-
|Easy
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file, no specular
|}
In addition to these lights, there can be custom lights set up by objects' code, which will affect all objects rendered with Regular functions. These custom lights can be directional, spot or point, with or without specular. The custom lights are created with the function <code>le_CreateLight</code> (0040A510 in SADX) and deleted with the function <code>le_DeleteLight</code> (0040A550 in SADX).

In the Dreamcast version, these functions use pointers to actual <code>NJS_LIGHT</code>s. In SADX, the Ninja Lights system appears to have been replaced by a system using the structure <code>LE_LIGHT_ENV</code> (what is also known as "Stage lights"). Instead of specific pointers, there is now an array of four "current stage lights" called <code>le_env</code> at 03ABD9F8. It also has a corresponding array of four Ninja light flags <code>le_env_typ</code> at 03ABDBB8. So instead of <code>NJS_LIGHT</code> pointers, the light create/delete functions manipulate data in these arrays in SADX.

Interestingly enough, the data for the light "Regular- light 2" is completely the same in SADX. It's still set up by the skybox display functions which call <code>njSetLightColor</code> etc. with the same arguments as the Dreamcast version, so basically we don't need the data from this post. However, now that these functions are redirected to modify the first entry in the <code>le_env</code> array, this data is overwritten every time a stage loads. That is happening because the function <code>le_set_env</code> (0040A95) copies over all light data from the SADX stage lights array (00900E88), which happens every time a light type is set and whenever a new level loads.

The following behavior of Ninja Lights is different from palette lighting:

<code>NJD_FLAG_IGNORE_SPECULAR</code> disables specular lighting ''completely'' (per material).

<code>NJD_FLAG_USE_FLAT</code> enables flat shading (used by Master Emerald pieces).

=== '''Custom''' '''Lights''' ===
There's a leftover function in SADX that creates custom lights associated with specific objects: <code>asSetLight</code> at 0040ADC0. It uses a <code>taskwk</code> pointer, an <code>NJS_LIGHT</code> pointer and a pointer to a structure called <code>LightInfo</code>:<syntaxhighlight lang="cpp">
struct LightInfo
{
int lsrc; // Ninja light flags
float spc;
float dif;
float amb;
NJS_ARGB argb;
NJS_POINT3 pos; // Light position (for spot and point lights)
NJS_POINT3 vec; // Light direction
float nrang; // Distance at which light source attenuation begins
float frang; // Distance to cut the effect of the light source (range)
int iang; // The angle at which the specular or spotlight is at maximum intensity
int oang; // The angle at which the specular or spotlight effect ceases
};
</syntaxhighlight>The following Ninja light flags can be used. The ones in bold are used in SA1, and the ones crossed out are unlikely to have been used in SA1.
{| class="wikitable"
!Flags
!Flag name
!Light type
!Ambient
!Diffuse
!Specular
|-
|0x01
|NJD_AMBIENT
|Ambient
|〇
|×
|×
|-
|0x02
|NJD_DIR_LIGHT
|Directional
|×
|〇
|×
|-
|0x03
|'''NJD_LAMBERT_DIR'''
|Directional
|〇
|〇
|×
|-
|0x04
|'''NJD_POINT_LIGHT'''
|Point
|×
|〇
|×
|-
|0x05
|NJD_LAMBERT_POINT
|Point
|〇
|〇
|×
|-
|0x08
|NJD_SPOT_LIGHT
|Spot
|×
|〇
|×
|-
|0x10
|NJD_SPEC_DIR
|Directional
|×
|〇
|〇
|-
|0x13
|NJD_PHONG_DIR
|Directional
|〇
|〇
|〇
|-
|0x20
|NJD_SPEC_POINT
|Point
|×
|〇
|〇
|-
|0x25
|'''NJD_PHONG_POINT'''
|Point
|〇
|〇
|〇
|-
|0x40
|<del>NJD_USER_LIGHT</del>
|Call a custom callback function
|
|
|
|-
|0x80
|'''NJD_SIMPLE_LIGHT'''
|Simplified lighting calculations (NOT the "Simple light" described earlier)
|
|
|
|-
|0xC0
|<del>NJD_BLOCK_LIGHT</del>
|Simplified lighting calculations
|
|
|
|}
The following custom lights have some leftover code and data in SADX. These also exist in SA1 but they aren't visible normally because the models that were supposed to be lit by them are rendered with palette lighting.

# Ice Cap background light: <code>NJD_PHONG_POINT</code>, <code>LightInfo</code> structure at 00C67FA0. Uses angles.
# "Chaos underlight": <code>NJD_POINT_LIGHT</code>, <code>NJS_LIGHT</code> structure at 03D0D5B8. The light is initialized using the function <code>ChaosUnderLightInit</code> (007AD250) that has a "radius" argument which goes unused in SADX but in SA1 it should be the light range. In Chaos' main functions, the light's matrix is transformed to match Chaos' position.
# Some light in Knuckles' story cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006868F0.
# Lights in Gamma's briefing cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006F4570. The light is a leftover, but this effect was adapted to palette lighting, and palette-related functions are called here too.

=== '''Specular''' '''Lighting''' ===
The Specular calculation formula for the Ninja Lights is currently unknown for Basic models. For Chunk models (which SA1 DC doesn't use), the formula was reversed by ''Exant'' for Simple and Easy lights:
[[File:Ninja Lights 1772333955721.png|none]]

Ninja Lights

2026-03-01T03:09:28Z

PkR:

"Ninja Lights" refers to the lighting used by the Ninja library of the [[Katana SDK]].

== Ninja Lights in Sonic Adventure ==
'''Note: Ninja Lights are not implemented in the Lantern Engine mod, so the information below is irrelevant to the PC version.'''

Sonic Adventure (Dreamcast) uses two lighting systems: the palette-based [[Sonic Adventure/Lantern Engine|LANTERN system]] and the Ninja Lights. The game's model rendering functions have "Lantern" and "Ninja" variants, and depending on the function used the game can either draw the model with palette lighting or use Ninja Lights.

The SL file contains data for setting up the Ninja lights. This information consists of: light color (three floats for R/G/B), diffuse multiplier, specular power and ambient multiplier. Both diffuse and specular components are the same color. The “ignore specular” material flag disables the specular component per mesh.

=== Types of Ninja Lights Setup ===
There are three types of lights used for non-palettized models in the game:
{| class="wikitable"
!Lighting Setup
!Description
!Used by
|-
|Two Ninja Lights
|Non-palettized lighting that uses two Ninja Lights. These lights use <code>NJS_LIGHT</code> structures described in the Katana SDK. One is set up using the parameters in the SL file (let’s call it the <code>ENV</code> Light), and the other is set up in code, usually in level binaries (let’s call it the <code>DIR</code> light). The <code>ENV</code> light has one configurable color that is shared for diffuse and specular, the <code>DIR</code> light can have different diffuse and specular color (though the game doesn’t seem to use that). It can also have a different light direction.
|Common switch, Hint monitor, OEggKanban (glowing Eggman logo in Final Egg, tube parts only), Chaos puddle in some cutscenes, Aoki Switch (top)
|-
|Simple Ninja Light
|Non-palettized lighting that uses one Ninja Light using the parameters from the SL file except the color, which is always white.
|Rock bits in Red Mountain, non-Jewel Chao, Master Emerald pieces, Froggy in Gamma’s Emerald Coast
|-
|Easy Light
|Non-palettized lighting that sets up the Easy Light (not <code>NJS_LIGHT</code>) using the parameters from the SL file. The Easy light is described in the Katana SDK. It doesn’t support specular lighting.
|Snowboard, OSandSwitch (Sand Hill switch), shadow blob, Chambr (chambers with opening doors in Sky Deck), debug objects, Aoki Switch (bottom), E101’s missiles, Hedgehog Hammer targets
|}

=== Rendering Functions and their SADX Counterparts ===
In SA1, most models were rendered with palette lighting using the game's custom function, but some models were rendered by calling Ninja drawing functions directly, which made them use the Ninja lights system. There are three light setups depending on the specific variation of the Ninja draw function:
{| class="wikitable"
!Light setup
!Functions in SADX (PC, 2004)
!Comment
|-
|Regular
|<code>njDrawModel</code> (0077EF70)
|Allows to use multiple <code>NJS_LIGHT</code>s of various types (directional, point, spot). Specular is supported.
|-
|Simple
|<code>___SAnjSimpleDrawModel</code> (00408520), <code>__SAnjSimpleDrawObject</code> (0040A130)
|Only the first registered <code>NJS_LIGHT</code> can be used. It is set up as a directional light, and intensity and color settings cannot be adjusted. Specular is supported.
|-
|Easy
|<code>njEasyDrawObject</code> (0040A100), <code>njEasyDrawModel</code> (004084F0), <code>njEasyDrawMotion</code> (00406FA0), <code>njEasyDrawShapeMotion</code> (00406FE0)
|Uses one "easy" light (not <code>NJS_LIGHT</code>). Specular is not supported. From the SDK: The light vector uses the screen space coordinate system. E.g. if set up like <code>njSetEasyLight( 0.0f, 0.0f, 1.0f );</code>, the light source will always be in front of the screen. To set the light source in 3D space, they must be converted with the current matrix:<syntaxhighlight lang="cpp">
light.x = LIGHT3D_X;
light.y = LIGHT3D_Y;
light.z = LIGHT3D_Z;
njCalcVector( NULL, &light, &lwork );
njSetEasyLight( lwork.x, lwork.y, lworkz );
</syntaxhighlight>After this, the Easy light source will be at <code>LIGHT3D_X,</code> <code>LIGHT3D_Y, LIGHT3D_Z</code>
|}
The SADX functions are a rough match since SADX changed draw functions for a lot of objects, and all that is left is some wrapper functions that call a more generic draw function:

# The Regular functions are difficult to tell from the paletted functions, so the above table is an approximation.
# The Easy functions are mostly still there.
# The Simple functions only have two stubs which aren't called by anything other than the Chao Name Machine, which doesn't match SA1.

=== Lighting Data ===
The data sources for the lights are as follows:
{| class="wikitable"
!Light
!Type
!Direction
!Color
!Diffuse, specular, ambient intensity
|-
|Regular - light 1
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file
|-
|Regular - light 2
|Directional
|<code>njSetLightDirection</code> called in the skybox display function
|<code>njSetLightColor</code> called in the skybox display function
|<code>njSetLightIntensity</code> called in the skybox display function
|-
|Simple
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|White (in SA1 anyway)
|From the SL file
|-
|Easy
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file, no specular
|}
In addition to these lights, there can be custom lights set up by objects' code, which will affect all objects rendered with Regular functions. These custom lights can be directional, spot or point, with or without specular. The custom lights are created with the function <code>le_CreateLight</code> (0040A510 in SADX) and deleted with the function <code>le_DeleteLight</code> (0040A550 in SADX).

In the Dreamcast version, these functions use pointers to actual <code>NJS_LIGHT</code>s. In SADX, the Ninja Lights system appears to have been replaced by a system using the structure <code>LE_LIGHT_ENV</code> (what is also known as "Stage lights"). Instead of specific pointers, there is now an array of four "current stage lights" called <code>le_env</code> at 03ABD9F8. It also has a corresponding array of four Ninja light flags <code>le_env_typ</code> at 03ABDBB8. So instead of <code>NJS_LIGHT</code> pointers, the light create/delete functions manipulate data in these arrays in SADX.

Interestingly enough, the data for the light "Regular- light 2" is completely the same in SADX. It's still set up by the skybox display functions which call <code>njSetLightColor</code> etc. with the same arguments as the Dreamcast version, so basically we don't need the data from this post. However, now that these functions are redirected to modify the first entry in the <code>le_env</code> array, this data is overwritten every time a stage loads. That is happening because the function <code>le_set_env</code> (0040A95) copies over all light data from the SADX stage lights array (00900E88), which happens every time a light type is set and whenever a new level loads.

The following behavior of Ninja Lights is different from palette lighting:

<code>NJD_FLAG_IGNORE_SPECULAR</code> disables specular lighting ''completely'' (per material).

<code>NJD_FLAG_USE_FLAT</code> enables flat shading (used by Master Emerald pieces).

=== '''Custom''' '''Lights''' ===
There's a leftover function in SADX that creates custom lights associated with specific objects: <code>asSetLight</code> at 0040ADC0. It uses a <code>taskwk</code> pointer, an <code>NJS_LIGHT</code> pointer and a pointer to a structure called <code>LightInfo</code>:<syntaxhighlight lang="cpp">
struct LightInfo
{
int lsrc; // Ninja light flags
float spc;
float dif;
float amb;
NJS_ARGB argb;
NJS_POINT3 pos; // Light position (for spot and point lights)
NJS_POINT3 vec; // Light direction
float nrang; // Distance at which light source attenuation begins
float frang; // Distance to cut the effect of the light source (range)
int iang; // The angle at which the specular or spotlight is at maximum intensity
int oang; // The angle at which the specular or spotlight effect ceases
};
</syntaxhighlight>The following Ninja light flags can be used. The ones in bold are used in SA1, and the ones crossed out are unlikely to have been used in SA1.
{| class="wikitable"
!Flags
!Flag name
!Light type
!Ambient
!Diffuse
!Specular
|-
|0x01
|NJD_AMBIENT
|Ambient
|〇
|×
|×
|-
|0x02
|NJD_DIR_LIGHT
|Directional
|×
|〇
|×
|-
|0x03
|'''NJD_LAMBERT_DIR'''
|Directional
|〇
|〇
|×
|-
|0x04
|'''NJD_POINT_LIGHT'''
|Point
|×
|〇
|×
|-
|0x05
|NJD_LAMBERT_POINT
|Point
|〇
|〇
|×
|-
|0x08
|NJD_SPOT_LIGHT
|Spot
|×
|〇
|×
|-
|0x10
|NJD_SPEC_DIR
|Directional
|×
|〇
|〇
|-
|0x13
|NJD_PHONG_DIR
|Directional
|〇
|〇
|〇
|-
|0x20
|NJD_SPEC_POINT
|Point
|×
|〇
|〇
|-
|0x25
|'''NJD_PHONG_POINT'''
|Point
|〇
|〇
|〇
|-
|0x40
|<del>NJD_USER_LIGHT</del>
|Call a custom callback function
|
|
|
|-
|0x80
|'''NJD_SIMPLE_LIGHT'''
|Simplified lighting calculations (NOT the "Simple light" described earlier)
|
|
|
|-
|0xC0
|<del>NJD_BLOCK_LIGHT</del>
|Simplified lighting calculations
|
|
|
|}
The following custom lights have some leftover code and data in SADX. These also exist in SA1 but they aren't visible normally because the models that were supposed to be lit by them are rendered with palette lighting.

# Ice Cap background light: <code>NJD_PHONG_POINT</code>, <code>LightInfo</code> structure at 00C67FA0. Uses angles.
# "Chaos underlight": <code>NJD_POINT_LIGHT</code>, <code>NJS_LIGHT</code> structure at 03D0D5B8. The light is initialized using the function <code>ChaosUnderLightInit</code> (007AD250) that has a "radius" argument which goes unused in SADX but in SA1 it should be the light range. In Chaos' main functions, the light's matrix is transformed to match Chaos' position.
# Some light in Knuckles' story cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006868F0.
# Lights in Gamma's briefing cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006F4570. The light is a leftover, but this effect was adapted to palette lighting, and palette-related functions are called here too.

=== '''Specular''' '''Lighting''' ===
The Specular calculation formula for the Ninja Lights is currently unknown for Basic models. For Chunk models (which SA1 DC doesn't use), the formula was reversed by ''Exant'' for Simple and Easy lights:
[[File:Ninja Lights 1772333955721.png|none]]

Ninja Lights

2026-03-01T03:08:57Z

PkR:

"Ninja Lights" refers to the lighting used by the Ninja library of the [[Katana SDK]].

== Ninja Lights in Sonic Adventure ==
'''Note: Ninja Lights are not implemented in the Lantern Engine mod, so the information below is irrelevant to the PC version.'''

Sonic Adventure (Dreamcast) uses two lighting systems: the palette-based [[Sonic Adventure/Lantern Engine|LANTERN system]] and the Ninja Lights. The game's model rendering functions have "Lantern" and "Ninja" variants, and depending on the function used the game can either draw the model with palette lighting or use Ninja Lights.

The SL file contains data for setting up the Ninja lights. This information consists of: light color (three floats for R/G/B), diffuse multiplier, specular power and ambient multiplier. Both diffuse and specular components are the same color. The “ignore specular” material flag disables the specular component per mesh.

=== Types of Ninja Lights Setup ===
There are three types of lights used for non-palettized models in the game:
{| class="wikitable"
!Lighting Setup
!Description
!Used by
|-
|Two Ninja Lights
|Non-palettized lighting that uses two Ninja Lights. These lights use <code>NJS_LIGHT</code> structures described in the Katana SDK. One is set up using the parameters in the SL file (let’s call it the <code>ENV</code> Light), and the other is set up in code, usually in level binaries (let’s call it the <code>DIR</code> light). The <code>ENV</code> light has one configurable color that is shared for diffuse and specular, the <code>DIR</code> light can have different diffuse and specular color (though the game doesn’t seem to use that). It can also have a different light direction.
|Common switch, Hint monitor, OEggKanban (glowing Eggman logo in Final Egg, tube parts only), Chaos puddle in some cutscenes, Aoki Switch (top)
|-
|Simple Ninja Light
|Non-palettized lighting that uses one Ninja Light using the parameters from the SL file except the color, which is always white.
|Rock bits in Red Mountain, non-Jewel Chao, Master Emerald pieces, Froggy in Gamma’s Emerald Coast
|-
|Easy Light
|Non-palettized lighting that sets up the Easy Light (not <code>NJS_LIGHT</code>) using the parameters from the SL file. The Easy light is described in the Katana SDK. It doesn’t support specular lighting.
|Snowboard, OSandSwitch (Sand Hill switch), shadow blob, Chambr (chambers with opening doors in Sky Deck), debug objects, Aoki Switch (bottom), E101’s missiles, Hedgehog Hammer targets
|}

=== Rendering Functions and their SADX Counterparts ===
In SA1, most models were rendered with palette lighting using the game's custom function, but some models were rendered by calling Ninja drawing functions directly, which made them use the Ninja lights system. There are three light setups depending on the specific variation of the Ninja draw function:
{| class="wikitable"
!Light setup
!Functions in SADX (PC, 2004)
!Comment
|-
|Regular
|<code>njDrawModel</code> (0077EF70)
|Allows to use multiple <code>NJS_LIGHT</code>s of various types (directional, point, spot). Specular is supported.
|-
|Simple
|<code>___SAnjSimpleDrawModel</code> (00408520), <code>__SAnjSimpleDrawObject</code> (0040A130)
|Only the first registered <code>NJS_LIGHT</code> can be used. It is set up as a directional light, and intensity and color settings cannot be adjusted. Specular is supported.
|-
|Easy
|<code>njEasyDrawObject</code> (0040A100), <code>njEasyDrawModel</code> (004084F0), <code>njEasyDrawMotion</code> (00406FA0), <code>njEasyDrawShapeMotion</code> (00406FE0)
|Uses one "easy" light (not <code>NJS_LIGHT</code>). Specular is not supported. From the SDK: The light vector uses the screen space coordinate system. E.g. if set up like <code>njSetEasyLight( 0.0f, 0.0f, 1.0f );</code>, the light source will always be in front of the screen. To set the light source in 3D space, they must be converted with the current matrix:<syntaxhighlight lang="cpp">
light.x = LIGHT3D_X; light.y = LIGHT3D_Y;
light.z = LIGHT3D_Z; njCalcVector( NULL, &light, &lwork );
njSetEasyLight( lwork.x, lwork.y, lworkz );
</syntaxhighlight>After this, the Easy light source will be at <code>LIGHT3D_X,</code> <code>LIGHT3D_Y, LIGHT3D_Z</code>
|}
The SADX functions are a rough match since SADX changed draw functions for a lot of objects, and all that is left is some wrapper functions that call a more generic draw function:

# The Regular functions are difficult to tell from the paletted functions, so the above table is an approximation.
# The Easy functions are mostly still there.
# The Simple functions only have two stubs which aren't called by anything other than the Chao Name Machine, which doesn't match SA1.

=== Lighting Data ===
The data sources for the lights are as follows:
{| class="wikitable"
!Light
!Type
!Direction
!Color
!Diffuse, specular, ambient intensity
|-
|Regular - light 1
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file
|-
|Regular - light 2
|Directional
|<code>njSetLightDirection</code> called in the skybox display function
|<code>njSetLightColor</code> called in the skybox display function
|<code>njSetLightIntensity</code> called in the skybox display function
|-
|Simple
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|White (in SA1 anyway)
|From the SL file
|-
|Easy
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file, no specular
|}
In addition to these lights, there can be custom lights set up by objects' code, which will affect all objects rendered with Regular functions. These custom lights can be directional, spot or point, with or without specular. The custom lights are created with the function <code>le_CreateLight</code> (0040A510 in SADX) and deleted with the function <code>le_DeleteLight</code> (0040A550 in SADX).

In the Dreamcast version, these functions use pointers to actual <code>NJS_LIGHT</code>s. In SADX, the Ninja Lights system appears to have been replaced by a system using the structure <code>LE_LIGHT_ENV</code> (what is also known as "Stage lights"). Instead of specific pointers, there is now an array of four "current stage lights" called <code>le_env</code> at 03ABD9F8. It also has a corresponding array of four Ninja light flags <code>le_env_typ</code> at 03ABDBB8. So instead of <code>NJS_LIGHT</code> pointers, the light create/delete functions manipulate data in these arrays in SADX.

Interestingly enough, the data for the light "Regular- light 2" is completely the same in SADX. It's still set up by the skybox display functions which call <code>njSetLightColor</code> etc. with the same arguments as the Dreamcast version, so basically we don't need the data from this post. However, now that these functions are redirected to modify the first entry in the <code>le_env</code> array, this data is overwritten every time a stage loads. That is happening because the function <code>le_set_env</code> (0040A95) copies over all light data from the SADX stage lights array (00900E88), which happens every time a light type is set and whenever a new level loads.

The following behavior of Ninja Lights is different from palette lighting:

<code>NJD_FLAG_IGNORE_SPECULAR</code> disables specular lighting ''completely'' (per material).

<code>NJD_FLAG_USE_FLAT</code> enables flat shading (used by Master Emerald pieces).

=== '''Custom''' '''Lights''' ===
There's a leftover function in SADX that creates custom lights associated with specific objects: <code>asSetLight</code> at 0040ADC0. It uses a <code>taskwk</code> pointer, an <code>NJS_LIGHT</code> pointer and a pointer to a structure called <code>LightInfo</code>:<syntaxhighlight lang="cpp">
struct LightInfo
{
int lsrc; // Ninja light flags
float spc;
float dif;
float amb;
NJS_ARGB argb;
NJS_POINT3 pos; // Light position (for spot and point lights)
NJS_POINT3 vec; // Light direction
float nrang; // Distance at which light source attenuation begins
float frang; // Distance to cut the effect of the light source (range)
int iang; // The angle at which the specular or spotlight is at maximum intensity
int oang; // The angle at which the specular or spotlight effect ceases
};
</syntaxhighlight>The following Ninja light flags can be used. The ones in bold are used in SA1, and the ones crossed out are unlikely to have been used in SA1.
{| class="wikitable"
!Flags
!Flag name
!Light type
!Ambient
!Diffuse
!Specular
|-
|0x01
|NJD_AMBIENT
|Ambient
|〇
|×
|×
|-
|0x02
|NJD_DIR_LIGHT
|Directional
|×
|〇
|×
|-
|0x03
|'''NJD_LAMBERT_DIR'''
|Directional
|〇
|〇
|×
|-
|0x04
|'''NJD_POINT_LIGHT'''
|Point
|×
|〇
|×
|-
|0x05
|NJD_LAMBERT_POINT
|Point
|〇
|〇
|×
|-
|0x08
|NJD_SPOT_LIGHT
|Spot
|×
|〇
|×
|-
|0x10
|NJD_SPEC_DIR
|Directional
|×
|〇
|〇
|-
|0x13
|NJD_PHONG_DIR
|Directional
|〇
|〇
|〇
|-
|0x20
|NJD_SPEC_POINT
|Point
|×
|〇
|〇
|-
|0x25
|'''NJD_PHONG_POINT'''
|Point
|〇
|〇
|〇
|-
|0x40
|<del>NJD_USER_LIGHT</del>
|Call a custom callback function
|
|
|
|-
|0x80
|'''NJD_SIMPLE_LIGHT'''
|Simplified lighting calculations (NOT the "Simple light" described earlier)
|
|
|
|-
|0xC0
|<del>NJD_BLOCK_LIGHT</del>
|Simplified lighting calculations
|
|
|
|}
The following custom lights have some leftover code and data in SADX. These also exist in SA1 but they aren't visible normally because the models that were supposed to be lit by them are rendered with palette lighting.

# Ice Cap background light: <code>NJD_PHONG_POINT</code>, <code>LightInfo</code> structure at 00C67FA0. Uses angles.
# "Chaos underlight": <code>NJD_POINT_LIGHT</code>, <code>NJS_LIGHT</code> structure at 03D0D5B8. The light is initialized using the function <code>ChaosUnderLightInit</code> (007AD250) that has a "radius" argument which goes unused in SADX but in SA1 it should be the light range. In Chaos' main functions, the light's matrix is transformed to match Chaos' position.
# Some light in Knuckles' story cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006868F0.
# Lights in Gamma's briefing cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006F4570. The light is a leftover, but this effect was adapted to palette lighting, and palette-related functions are called here too.

=== '''Specular''' '''Lighting''' ===
The Specular calculation formula for the Ninja Lights is currently unknown for Basic models. For Chunk models (which SA1 DC doesn't use), the formula was reversed by ''Exant'' for Simple and Easy lights:
[[File:Ninja Lights 1772333955721.png|none]]

PL Tool

2026-03-01T03:06:36Z

PkR:

PL Tool is an editor for Sonic Adventure lighting files (PL and SL files) used by [[Sonic Adventure/Lantern Engine|Lantern Engine]].
= Using the Editor =

<div class="figure">

[[File:Pltool.png]]

</div>
== Palette List ==

PLTool’s main window lists diffuse and specular palettes in the PL file. Click the palette to select it. Right click a palette for a list of options to edit it. You can create palettes with sliders like gradients in Photoshop, generate them like in the Preview prototype of SADX, fill them with a specific color (or a combination of colors), import and export palettes as PNG files, as well as copy and paste them. The <code>B</code> palette pair is not stored in the PL file and can be used for backing up palettes before editing them.

* Note: Color Alpha is ignored in the game.
=== Create Gradient ===

<div class="figure">

[[File:Creategrad.png]]

</div>
This window lets you create gradients from four colors and an ambient color. Click each color box to set the color and drag the sliders to adjust the position of the two colors in the middle.
=== Generate Gradient (SADX Preview) ===

<div class="figure">

[[File:Gengrad.png]]

</div>
The [https://hiddenpalace.org/Sonic_Adventure_DX_(Preview_prototype) SADX Preview prototype] has a debug menu that creates gradients. This feature is recreated in PL Tool. The gradients are generated using the following formula:

<code>Result = Ambient + CO1 * Pow((1 - Index / 256), CO1Pow / 100.0) + CO2 * Pow((Index / 256), CO2Pow / 100)</code>

* Ambient is the Ambient color R/G/B.
* CO1 is Color 1 R/G/B.
* CO2 is Color 2 R/G/B.
* CO1Pow and CO2Pow are Color 1 and Color 2 power values respectively.
* Index is the color index in the gradient (0 to 255).
== Color Selector ==

The trackbar is used to select a specific color in the palette. Its index and R/G/B values are shown on the right side of the status bar. Click the small colored box in the status bar to edit the color.

* Note: Color Alpha is ignored in the game.
== Menu bar ==

* The '''File''' menu lets you import or export the entire palette list as a single PNG file.
* The '''Options''' menu lets you set a background color for the editor to make it easier to work with light or dark palettes.
* The '''Level Select''' menu allows you to locate the PL file by selecting a stage. If you have opened a PL file previously, the tool will look for PL files in the same folder without an open file dialog.
* The '''Format''' menu allows you to toggle the Endianness of PL and SL files. Leave it on Dreamcast for the Lantern Engine mod.
* The '''Tools''' menu opens the editor for SL files (see below).
== SL Editor ==

The SL Editor lets you edit light direction and Ninja Lights configuration.

[[File:Sleditor.png]]

* The Environment Data box has the parameters for the Ninja lights. You can click the color box to select the color.
* The Light Direction box has light rotation Y and Z values. These are used to rotate the default light direction vector. This light direction is used by palette lights and Ninja lights except the DIR light which has a hardcoded light direction.
* The Free/Slave Data box has additional lighting data. This data doesn’t seem to be used by the game. It may be left over from the Saturn because a menu with similar data was found in a [https://hiddenpalace.org/News/Angels_with_Burning_Hearts:_Burning_Rangers_Prototype Burning Rangers prototype].

{{SAToolsNavbox}}

[[Category:SA1 tools]]

Ninja Lights

2026-03-01T03:06:16Z

PkR:

"Ninja Lights" refers to the lighting used by the Ninja library of the [[Katana SDK]].

== Ninja Lights in Sonic Adventure ==
'''Note: Ninja Lights are not implemented in the Lantern Engine mod, so the information below is irrelevant to the PC version.'''
Sonic Adventure (Dreamcast) uses two lighting systems: the palette-based [[Sonic Adventure/Lantern Engine|LANTERN system]] and the Ninja Lights. The game's model rendering functions have "Lantern" and "Ninja" variants, and depending on the function used the game can either draw the model with palette lighting or use Ninja Lights.

The SL file contains data for setting up the Ninja lights. This information consists of: light color (three floats for R/G/B), diffuse multiplier, specular power and ambient multiplier. Both diffuse and specular components are the same color. The “ignore specular” material flag disables the specular component per mesh.

=== Types of Ninja Lights Setup ===
There are three types of lights used for non-palettized models in the game:
{| class="wikitable"
!Lighting Setup
!Description
!Used by
|-
|Two Ninja Lights
|Non-palettized lighting that uses two Ninja Lights. These lights use <code>NJS_LIGHT</code> structures described in the Katana SDK. One is set up using the parameters in the SL file (let’s call it the <code>ENV</code> Light), and the other is set up in code, usually in level binaries (let’s call it the <code>DIR</code> light). The <code>ENV</code> light has one configurable color that is shared for diffuse and specular, the <code>DIR</code> light can have different diffuse and specular color (though the game doesn’t seem to use that). It can also have a different light direction.
|Common switch, Hint monitor, OEggKanban (glowing Eggman logo in Final Egg, tube parts only), Chaos puddle in some cutscenes, Aoki Switch (top)
|-
|Simple Ninja Light
|Non-palettized lighting that uses one Ninja Light using the parameters from the SL file except the color, which is always white.
|Rock bits in Red Mountain, non-Jewel Chao, Master Emerald pieces, Froggy in Gamma’s Emerald Coast
|-
|Easy Light
|Non-palettized lighting that sets up the Easy Light (not <code>NJS_LIGHT</code>) using the parameters from the SL file. The Easy light is described in the Katana SDK. It doesn’t support specular lighting.
|Snowboard, OSandSwitch (Sand Hill switch), shadow blob, Chambr (chambers with opening doors in Sky Deck), debug objects, Aoki Switch (bottom), E101’s missiles, Hedgehog Hammer targets
|}

=== Rendering Functions and their SADX Counterparts ===
In SA1, most models were rendered with palette lighting using the game's custom function, but some models were rendered by calling Ninja drawing functions directly, which made them use the Ninja lights system. There are three light setups depending on the specific variation of the Ninja draw function:
{| class="wikitable"
!Light setup
!Functions in SADX (PC, 2004)
!Comment
|-
|Regular
|<code>njDrawModel</code> (0077EF70)
|Allows to use multiple <code>NJS_LIGHT</code>s of various types (directional, point, spot). Specular is supported.
|-
|Simple
|<code>___SAnjSimpleDrawModel</code> (00408520), <code>__SAnjSimpleDrawObject</code> (0040A130)
|Only the first registered <code>NJS_LIGHT</code> can be used. It is set up as a directional light, and intensity and color settings cannot be adjusted. Specular is supported.
|-
|Easy
|<code>njEasyDrawObject</code> (0040A100), <code>njEasyDrawModel</code> (004084F0), <code>njEasyDrawMotion</code> (00406FA0), <code>njEasyDrawShapeMotion</code> (00406FE0)
|Uses one "easy" light (not <code>NJS_LIGHT</code>). Specular is not supported. From the SDK: The light vector uses the screen space coordinate system. E.g. if set up like <code>njSetEasyLight( 0.0f, 0.0f, 1.0f );</code>, the light source will always be in front of the screen. To set the light source in 3D space, they must be converted with the current matrix:<syntaxhighlight lang="cpp">
light.x = LIGHT3D_X; light.y = LIGHT3D_Y;
light.z = LIGHT3D_Z; njCalcVector( NULL, &light, &lwork );
njSetEasyLight( lwork.x, lwork.y, lworkz );
</syntaxhighlight>After this, the Easy light source will be at <code>LIGHT3D_X,</code> <code>LIGHT3D_Y, LIGHT3D_Z</code>
|}
The SADX functions are a rough match since SADX changed draw functions for a lot of objects, and all that is left is some wrapper functions that call a more generic draw function:

# The Regular functions are difficult to tell from the paletted functions, so the above table is an approximation.
# The Easy functions are mostly still there.
# The Simple functions only have two stubs which aren't called by anything other than the Chao Name Machine, which doesn't match SA1.

=== Lighting Data ===
The data sources for the lights are as follows:
{| class="wikitable"
!Light
!Type
!Direction
!Color
!Diffuse, specular, ambient intensity
|-
|Regular - light 1
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file
|-
|Regular - light 2
|Directional
|<code>njSetLightDirection</code> called in the skybox display function
|<code>njSetLightColor</code> called in the skybox display function
|<code>njSetLightIntensity</code> called in the skybox display function
|-
|Simple
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|White (in SA1 anyway)
|From the SL file
|-
|Easy
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file, no specular
|}
In addition to these lights, there can be custom lights set up by objects' code, which will affect all objects rendered with Regular functions. These custom lights can be directional, spot or point, with or without specular. The custom lights are created with the function <code>le_CreateLight</code> (0040A510 in SADX) and deleted with the function <code>le_DeleteLight</code> (0040A550 in SADX).

In the Dreamcast version, these functions use pointers to actual <code>NJS_LIGHT</code>s. In SADX, the Ninja Lights system appears to have been replaced by a system using the structure <code>LE_LIGHT_ENV</code> (what is also known as "Stage lights"). Instead of specific pointers, there is now an array of four "current stage lights" called <code>le_env</code> at 03ABD9F8. It also has a corresponding array of four Ninja light flags <code>le_env_typ</code> at 03ABDBB8. So instead of <code>NJS_LIGHT</code> pointers, the light create/delete functions manipulate data in these arrays in SADX.

Interestingly enough, the data for the light "Regular- light 2" is completely the same in SADX. It's still set up by the skybox display functions which call <code>njSetLightColor</code> etc. with the same arguments as the Dreamcast version, so basically we don't need the data from this post. However, now that these functions are redirected to modify the first entry in the <code>le_env</code> array, this data is overwritten every time a stage loads. That is happening because the function <code>le_set_env</code> (0040A95) copies over all light data from the SADX stage lights array (00900E88), which happens every time a light type is set and whenever a new level loads.

The following behavior of Ninja Lights is different from palette lighting:

<code>NJD_FLAG_IGNORE_SPECULAR</code> disables specular lighting ''completely'' (per material).

<code>NJD_FLAG_USE_FLAT</code> enables flat shading (used by Master Emerald pieces).

=== '''Custom''' '''Lights''' ===
There's a leftover function in SADX that creates custom lights associated with specific objects: <code>asSetLight</code> at 0040ADC0. It uses a <code>taskwk</code> pointer, an <code>NJS_LIGHT</code> pointer and a pointer to a structure called <code>LightInfo</code>:<syntaxhighlight lang="cpp">
struct LightInfo
{
int lsrc; // Ninja light flags
float spc;
float dif;
float amb;
NJS_ARGB argb;
NJS_POINT3 pos; // Light position (for spot and point lights)
NJS_POINT3 vec; // Light direction
float nrang; // Distance at which light source attenuation begins
float frang; // Distance to cut the effect of the light source (range)
int iang; // The angle at which the specular or spotlight is at maximum intensity
int oang; // The angle at which the specular or spotlight effect ceases
};
</syntaxhighlight>The following Ninja light flags can be used. The ones in bold are used in SA1, and the ones crossed out are unlikely to have been used in SA1.
{| class="wikitable"
!Flags
!Flag name
!Light type
!Ambient
!Diffuse
!Specular
|-
|0x01
|NJD_AMBIENT
|Ambient
|〇
|×
|×
|-
|0x02
|NJD_DIR_LIGHT
|Directional
|×
|〇
|×
|-
|0x03
|'''NJD_LAMBERT_DIR'''
|Directional
|〇
|〇
|×
|-
|0x04
|'''NJD_POINT_LIGHT'''
|Point
|×
|〇
|×
|-
|0x05
|NJD_LAMBERT_POINT
|Point
|〇
|〇
|×
|-
|0x08
|NJD_SPOT_LIGHT
|Spot
|×
|〇
|×
|-
|0x10
|NJD_SPEC_DIR
|Directional
|×
|〇
|〇
|-
|0x13
|NJD_PHONG_DIR
|Directional
|〇
|〇
|〇
|-
|0x20
|NJD_SPEC_POINT
|Point
|×
|〇
|〇
|-
|0x25
|'''NJD_PHONG_POINT'''
|Point
|〇
|〇
|〇
|-
|0x40
|<del>NJD_USER_LIGHT</del>
|Call a custom callback function
|
|
|
|-
|0x80
|'''NJD_SIMPLE_LIGHT'''
|Simplified lighting calculations (NOT the "Simple light" described earlier)
|
|
|
|-
|0xC0
|<del>NJD_BLOCK_LIGHT</del>
|Simplified lighting calculations
|
|
|
|}
The following custom lights have some leftover code and data in SADX. These also exist in SA1 but they aren't visible normally because the models that were supposed to be lit by them are rendered with palette lighting.

# Ice Cap background light: <code>NJD_PHONG_POINT</code>, <code>LightInfo</code> structure at 00C67FA0. Uses angles.
# "Chaos underlight": <code>NJD_POINT_LIGHT</code>, <code>NJS_LIGHT</code> structure at 03D0D5B8. The light is initialized using the function <code>ChaosUnderLightInit</code> (007AD250) that has a "radius" argument which goes unused in SADX but in SA1 it should be the light range. In Chaos' main functions, the light's matrix is transformed to match Chaos' position.
# Some light in Knuckles' story cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006868F0.
# Lights in Gamma's briefing cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006F4570. The light is a leftover, but this effect was adapted to palette lighting, and palette-related functions are called here too.

=== '''Specular''' '''Lighting''' ===
The Specular calculation formula for the Ninja Lights is currently unknown for Basic models. For Chunk models (which SA1 DC doesn't use), the formula was reversed by ''Exant'' for Simple and Easy lights:
[[File:Ninja Lights 1772333955721.png|none]]

PL Tool

2026-03-01T03:05:34Z

PkR:

PL Tool is an editor for Sonic Adventure lighting files (PL and SL files) used by [[Lantern Engine]].
= Using the Editor =

<div class="figure">

[[File:Pltool.png]]

</div>
== Palette List ==

PLTool’s main window lists diffuse and specular palettes in the PL file. Click the palette to select it. Right click a palette for a list of options to edit it. You can create palettes with sliders like gradients in Photoshop, generate them like in the Preview prototype of SADX, fill them with a specific color (or a combination of colors), import and export palettes as PNG files, as well as copy and paste them. The <code>B</code> palette pair is not stored in the PL file and can be used for backing up palettes before editing them.

* Note: Color Alpha is ignored in the game.
=== Create Gradient ===

<div class="figure">

[[File:Creategrad.png]]

</div>
This window lets you create gradients from four colors and an ambient color. Click each color box to set the color and drag the sliders to adjust the position of the two colors in the middle.
=== Generate Gradient (SADX Preview) ===

<div class="figure">

[[File:Gengrad.png]]

</div>
The [https://hiddenpalace.org/Sonic_Adventure_DX_(Preview_prototype) SADX Preview prototype] has a debug menu that creates gradients. This feature is recreated in PL Tool. The gradients are generated using the following formula:

<code>Result = Ambient + CO1 * Pow((1 - Index / 256), CO1Pow / 100.0) + CO2 * Pow((Index / 256), CO2Pow / 100)</code>

* Ambient is the Ambient color R/G/B.
* CO1 is Color 1 R/G/B.
* CO2 is Color 2 R/G/B.
* CO1Pow and CO2Pow are Color 1 and Color 2 power values respectively.
* Index is the color index in the gradient (0 to 255).
== Color Selector ==

The trackbar is used to select a specific color in the palette. Its index and R/G/B values are shown on the right side of the status bar. Click the small colored box in the status bar to edit the color.

* Note: Color Alpha is ignored in the game.
== Menu bar ==

* The '''File''' menu lets you import or export the entire palette list as a single PNG file.
* The '''Options''' menu lets you set a background color for the editor to make it easier to work with light or dark palettes.
* The '''Level Select''' menu allows you to locate the PL file by selecting a stage. If you have opened a PL file previously, the tool will look for PL files in the same folder without an open file dialog.
* The '''Format''' menu allows you to toggle the Endianness of PL and SL files. Leave it on Dreamcast for the Lantern Engine mod.
* The '''Tools''' menu opens the editor for SL files (see below).
== SL Editor ==

The SL Editor lets you edit light direction and Ninja Lights configuration.

[[File:Sleditor.png]]

* The Environment Data box has the parameters for the Ninja lights. You can click the color box to select the color.
* The Light Direction box has light rotation Y and Z values. These are used to rotate the default light direction vector. This light direction is used by palette lights and Ninja lights except the DIR light which has a hardcoded light direction.
* The Free/Slave Data box has additional lighting data. This data doesn’t seem to be used by the game. It may be left over from the Saturn because a menu with similar data was found in a [https://hiddenpalace.org/News/Angels_with_Burning_Hearts:_Burning_Rangers_Prototype Burning Rangers prototype].

{{SAToolsNavbox}}

[[Category:SA1 tools]]

Sonic Adventure/Lantern Engine

2026-03-01T03:04:35Z

PkR: Created page with "Lantern (stylized LANTERN) Engine is the internal name of the lighting system used in Sonic Adventure (Dreamcast). It is also the name of a mod that restores said lighting system in the PC version of Sonic Adventure DX. = Overview of the SA1 Lighting System = The Dreamcast version of Sonic Adventure has a lighting system (referred to internally as “LANTERN”) that consists of two modes: # Palette lighting using a series of 256-color palettes. # Lights set up by..."

Lantern (stylized LANTERN) Engine is the internal name of the lighting system used in [[Sonic Adventure]] (Dreamcast). It is also the name of a mod that restores said lighting system in the PC version of Sonic Adventure DX.

= Overview of the SA1 Lighting System =
The Dreamcast version of Sonic Adventure has a lighting system (referred to internally as “LANTERN”) that consists of two modes:

# Palette lighting using a series of 256-color palettes.
# Lights set up by the Dreamcast’s Ninja library ([[Ninja Lights|Ninja]] [[Ninja Lights|Lights]]).

Lighting information for each level is stored in a pair of files: the PL file (PL_....BIN) contains the palettes, and the SL file (SL_....bin) contains light direction and data for setting up the Ninja Lights.

The [https://github.com/michael-fadely/sadx-dc-lighting Lantern Engine mod] for Sonic Adventure DX PC is a reimplementation of palette lighting for the PC port of SADX. At the moment it does not implement the Ninja Lights.

== Palette Lighting ==

=== Brightness Index Calculation ===
The palette-based system gives each vertex in the scene a “brightness index”, which is a value in the range of 0 to 255 used to select a color in a palette to set as vertex color. The brightness index is calculated using the following formula:

<code>1 - ((dot(normal, light direction) + 1) / 2)</code>, where <code>dot</code> is dot product and <code>normal</code> is vertex normal.

The result is multiplied by 255 to get the color index in the palette. If we visualized brightness indices (from white being maximum brightness to black being completely unlit), it would look something like this:
[[File:Brightness.png|none|thumb|Brightness indices visualized: from white (fullbright) to black (fully dark).]]

=== Diffuse and Specular Lighting ===
LANTERN palettes are applied in pairs to create diffuse and specular lighting.

* Diffuse color is the color that is calculated by multiplying the original color with the color in the diffuse palette. It works like the “Multiply” blending mode in Photoshop.
* Specular color is additive, so it works like the “Add” blending mode in Photoshop.

Making the diffuse color brighter makes the result closer to the original texture’s color. Making the specular color brighter adds to the brightness of the resulting color directly, so white diffuse + black specular is effectively the same as not applying any lighting at all, and white specular would make the vertex completely white regardless of the texture and diffuse color. Normally diffuse lighting is used to give the entire model or area a “base” color, while specular lighting is used to add gloss.
[[File:Palettesample.png|none|thumb|Diffuse palette samples (image by Speeps)]]

=== Palette Selection ===
The PL file can store up to eight pairs of diffuse/specular palettes, although only up to six pairs are used normally. There are several variables the game relies on to select which palettes to apply to a specific model:

'''1. Light type'''

This is a variable set in code before rendering the model. The light type value determines which diffuse palette is used by the model:
{| class="wikitable"
!Value
!Description
!Diffuse Palette
!Specular Palette
|-
|0
|Used by the majority of models in the game except characters and bosses.
|0
|0 or 1
|-
|2
|Used by characters and cutscene models.
|2
|2 or 3
|-
|4
|Used by some bosses and for blending effects.
|4
|4 or 5
|}
The majority of models in the game outside cutscenes use the level/object light type 0. These are the palettes you see on level pieces and most objects.

Character/NPC models and models used in cutscenes generally use the character/event light type 2, although there are some exceptions. For example, Amy’s Warrior Feather and some parts of Gamma’s body that are rendered as separate models (such as the Laser Scope) use the level/object light type 0 outside cutscenes. The gameplay models in Sky Chase use the level/object light type 0 despite being character-related; however, models involving the Tornado in Sky Chase cutscenes use the character light type 2. It happens the other way around as well: some non-character objects that would normally be using level/object palettes (such as floating meteors near the end of Twinkle Park Act 1) set the character light type so they also get character lighting, but this is uncommon.

The boss light type 4 is only used by a few models in the game. Diffuse 4 and Specular 5 are used by Chaos 2, Chaos 6 and Perfect Chaos. Diffuse 4/Specular 4 and Diffuse 5/Specular 5 are also used by the transition effect in Mystic Ruins Past when the Emerald Altar is on fire. The palettes blend between each other to create a burning fire effect.

'''2. Material flags'''

Material flags influence palette selection in the following ways:

* If a mesh’s material has the “ignore lighting” flag (<code>NJD_FLAG_IGNORE_LIGHT</code>), the mesh is not palettized and the fullbright texture is used as-is. Neither the diffuse nor the specular palette is applied to the mesh, but the rest of the meshset may be palettized depending on whether or not the remaining materials have the “ignore lighting” flag.
* If the model’s first material has the “ignore specular” flag (<code>NJD_FLAG_IGNORE_SPECULAR</code>), the entire model’s specular palette index is the same as the diffuse palette index (e.g. Diffuse 0, Specular 0).
* If the model’s first material doesn’t have “ignore specular”, the specular palette index is the diffuse index + 1 (e.g. Diffuse 0, Specular 1).

Note that only the first mesh’s material in the model affects specular palette selection, and all other meshes follow it regardless of whether they have “ignore specular” or not. Specular palette selection is consistent within a single model, but if the model has child or sibling models those are processed separately unlike the light type. So it is possible to have a model (e.g. Tails) that has child models with a different specular palette (Tails’ shoes). They would still use the same diffuse palette, however, as they would have the same light type as the parent model.

Sometimes the game forcibly adds or removes the “ignore specular” flag or sets a specific light type when rendering certain models. If you want to change palette selection in these cases, you would need to change/disable the code doing that, or use Lantern API to register those models’ materials for arbitrary palette selection.

'''3. White diffuse'''

In the Dreamcast version of SA1, if a mesh in a model has a material with the “ignore lighting” flag, the remaining meshes after it may get the fullbright diffuse palette (as if they were ignoring lighting), but keep the specular palette. The Lantern Engine mod does not do this by default. Dreamcast Conversion has an option to enable white diffuse.

'''4. Palette blending'''

There are cases when the game swaps or mixes different palettes for some special effects:

* The Past fire effect creates the level/object palettes (Diffuse 0/Specular 0) by mixing Diffuse 4/Specular 4 and Diffuse 5/Specular 5 using a blending coefficient. The Lantern Engine mod blends between Diffuse 0/Specular 0 and Diffuse 5/Specular 5 instead, which are identical to Diffuse 0/Specular 0 in the PL file anyway.
* Sky Deck Acts 1 and 2 swap palettes when the Egg Carrier changes altitude. Palettes in <code>PL_60B</code> are used normally, and palettes from <code>PL_61B</code> are used when the Egg Carrier descends into the clouds. While the original game only swaps the palettes, the Lantern Engine mod actually blends between them.
* The Egg Viper boss fight blends palettes in <code>PL_M0B.BIN</code> with specific colors (white, red and cyan).
* In Casinopolis Act 1, when Sonic goes to pinball areas the character specular palette blends with white, making character lighting brighter as Sonic is floating before getting teleported to the pinball field.

'''5. Palette selection example'''

Here is a simple example of palette selection based on Emerald Coast. Color-coded specular palettes are used to tell which light type is being used by the model:
{| class="wikitable"
|+Palette masks ingame
![[File:Mask_test.png]]
![[File:Mask_edit.png|none|thumb]]
|}

=== List of PL files ===
The game loads PL/SL files using a naming scheme that roughly matches the game’s internal level list. The first number/letter after “PL_” is the level ID, the number after that is usually act number, but there are some exceptions. Here is a list of PL files and stages that load them:

==== Action Stages ====
{| class="wikitable"
!Filename
!Description
|-
|PL_10B.BIN
|Emerald Coast (all acts), Egg Carrier Outside when the Egg Carrier has sunk
|-
|PL_20B.BIN
|Windy Valley Act 1
|-
|PL_21B.BIN
|Windy Valley Act 2
|-
|PL_22B.BIN
|Windy Valley Act 3
|-
|PL_30B.BIN
|Twinkle Park Act 1
|-
|PL_31B.BIN
|Twinkle Park Act 2
|-
|PL_32B.BIN
|Twinkle Park Act 3
|-
|PL_40B.BIN
|Speed Highway Act 1
|-
|PL_41B.BIN
|Speed Highway Act 2
|-
|PL_42B.BIN
|Speed Highway Act 3
|-
|PL_50B.BIN
|Red Mountain Act 1
|-
|PL_51B.BIN
|Red Mountain Act 2
|-
|PL_52B.BIN
|Red Mountain Act 3 (Knuckles)
|-
|PL_60B.BIN
|Character select screen, Sky Deck normal (Acts 1 and 2), Sky Deck Act 3
|-
|PL_61B.BIN
|Sky Deck dark (Acts 1 and 2)
|-
|PL_70B.BIN
|Lost World Act 1
|-
|PL_71B.BIN
|Lost World Acts 2 and 3
|-
|PL_80B.BIN
|Ice Cap Act 1
|-
|PL_81B.BIN
|Ice Cap Act 2
|-
|PL_82B.BIN
|Ice Cap Act 3
|-
|PL_83B.BIN
|Ice Cap Act 4 (Big)
|-
|PL_90B.BIN
|Casinopolis Act 1
|-
|PL_91B.BIN
|Casinopolis Act 2 (Sewers)
|-
|PL_92B.BIN
|Casinopolis Act 3 (Sonic pinball)
|-
|PL_93B.BIN
|Casinopolis Act 4 (NiGHTS pinball)
|-
|PL_A0B.BIN
|Final Egg Act 1
|-
|PL_A1B.BIN
|Final Egg Act 2
|-
|PL_A2B.BIN
|Final Egg Act 3 (Sonic/Gamma)
|-
|PL_C0B.BIN
|Hot Shelter Act 1
|-
|PL_C1B.BIN
|Hot Shelter Act 2
|-
|PL_C2B.BIN
|Hot Shelter Act 3 (Gamma)
|}

==== Bosses ====
{| class="wikitable"
!Filename
!Description
|-
|PL_F0B.BIN
|Chaos 0
|-
|PL_G0B.BIN
|Chaos 2
|-
|PL_H0B.BIN
|Chaos 4
|-
|PL_I0B.BIN
|Chaos 6
|-
|PL_J0B.BIN
|Perfect Chaos (first 3 hits)
|-
|PL_J1B.BIN
|Perfect Chaos 2nd phase
|-
|PL_K0B.BIN
|Egg Hornet
|-
|PL_M0B.BIN
|Egg Viper
|-
|PL_N0B.BIN
|Zero
|-
|PL_O0B.BIN
|E-101 Beta
|-
|PL_P0B.BIN
|E-101R
|}

==== Adventure Fields ====
{| class="wikitable"
!Filename
!Description
|-
|PL_Q1B.BIN
|Station Square Evening (All acts)
|-
|PL_Q3B.BIN
|Egg Walker, Station Square Night (All acts)
|-
|PL_Q4B.BIN
|Station Square Day (All acts)
|-
|PL_T0B.BIN
|Egg Carrier Outside (before the Egg Carrier sinks)
|-
|PL_T2B.BIN
|Egg Carrier Private Room
|-
|PL_T3B.BIN
|Egg Carrier Captain’s Room
|-
|PL_T5B.BIN
|Egg Carrier Pool
|-
|PL_W0B.BIN
|Egg Carrier Ammunition Room
|-
|PL_W1B.BIN
|Egg Carrier Bridge
|-
|PL_W2B.BIN
|Egg Carrier Hedgehog Hammer Room
|-
|PL_W3B.BIN
|Egg Carrier Prison
|-
|PL_W4B.BIN
|Egg Carrier Reservoir Room
|-
|PL_W5B.BIN
|Egg Carrier Chao Garden transporter
|-
|PL_X0B.BIN
|Mystic Ruins Day (Station, Angel Island and Jungle)
|-
|PL_X1B.BIN
|Mystic Ruins Evening (Station, Angel Island and Jungle)
|-
|PL_X2B.BIN
|Mystic Ruins Night (Station, Angel Island and Jungle)
|-
|PL_X3B.BIN
|Mystic Ruins Eggman’s Base
|-
|PL_Y0B.BIN
|Past Act 1 (Echidna City)
|-
|PL_Y1B.BIN
|Past Act 2 (Emerald Altar)
|-
|PL_Y2B.BIN
|Past Act 3 (Emerald Altar on fire)
|}

==== Subgames ====
{| class="wikitable"
!Filename
!Description
|-
|PL_Z0B.BIN
|Twinkle Circuit
|-
|PL1A0B.BIN
|Sky Chase Act 1
|-
|PL1B0B.BIN
|Sky Chase Act 2
|-
|PL1C0B.BIN
|Sand Hill
|}

==== Chao ====
{| class="wikitable"
!Filename
!Description
|-
|PL1D0B.BIN
|Station Square Chao Garden
|-
|PL1E0B.BIN
|Egg Carrier Chao Garden
|-
|PL1F0B.BIN
|Mystic Ruins Chao Garden Day
|-
|PL1F1B.BIN
|Mystic Ruins Chao Garden Evening (unused in the original game, used in SADX Lantern Engine)
|-
|PL1F2B.BIN
|Mystic Ruins Chao Garden Night (unused in the original game, used in SADX Lantern Engine)
|-
|PL1G0B.BIN
|Chao Stadium
|-
|PL1G1B.BIN
|Chao Race
|}

==== Unused ====
The following files are present on the disk, but not used by the game:
{| class="wikitable"
!Filename
!Description
|-
|PL_9MB.BIN
|An alternative version of the Casinopolis sewers palette that is never applied.
It was originally supposed to be used by an object called MUD. The object would gradually change character palettes to make them darker.
|-
|PL_MRD.BIN
|Possibly alternative Mystic Ruins Day palette
|-
|PL_MRE.BIN
|Possibly alternative Mystic Ruins Evening palette
|-
|PL_MRN.BIN
|Possibly alternative Mystic Ruins Night palette
|-
|PL_T1B.BIN
|Egg Carrier related, might have been used in the early transformation cutscene
|-
|PL_T4B.BIN
|Egg Carrier related, possibly the lighting used for some endgame credits images
|-
|PL1D1B.BIN
|Possibly Station Square Chao Garden Night
|-
|PL1E1B.BIN
|Egg Carrier Chao Garden Evening
|-
|PL1E2B.BIN
|Egg Carrier Chao Garden Night
|}

== SL Files ==
SL files use the same naming scheme as the PL files. They store the following data:

* Light rotation: Y and Z rotation values that are applied to the default light direction, which is a downward facing vector (0, -1, 0).
* Lighting configuration for models that use [[Ninja Lights|Ninja]] [[Ninja Lights|Lights]] instead of palette lighting.

Ninja Lights

2026-03-01T03:03:52Z

PkR: Created page with ""Ninja Lights" refers to the lighting used by the Ninja library of the Katana SDK. == Ninja Lights in Sonic Adventure == '''Note: Ninja Lights are not implemented in the Lantern Engine mod, so the information below is irrelevant to the PC version.''' Sonic Adventure (Dreamcast) uses two lighting systems: the palette-based LANTERN system and the Ninja Lights. The game's model rendering functions have "Lantern" and "Ninja" variants, and depending on..."

"Ninja Lights" refers to the lighting used by the Ninja library of the [[Katana SDK]].

== Ninja Lights in Sonic Adventure ==
'''Note: Ninja Lights are not implemented in the Lantern Engine mod, so the information below is irrelevant to the PC version.'''
Sonic Adventure (Dreamcast) uses two lighting systems: the palette-based [[Lantern Engine|LANTERN system]] and the Ninja Lights. The game's model rendering functions have "Lantern" and "Ninja" variants, and depending on the function used the game can either draw the model with palette lighting or use Ninja Lights.

The SL file contains data for setting up the Ninja lights. This information consists of: light color (three floats for R/G/B), diffuse multiplier, specular power and ambient multiplier. Both diffuse and specular components are the same color. The “ignore specular” material flag disables the specular component per mesh.

=== Types of Ninja Lights Setup ===
There are three types of lights used for non-palettized models in the game:
{| class="wikitable"
!Lighting Setup
!Description
!Used by
|-
|Two Ninja Lights
|Non-palettized lighting that uses two Ninja Lights. These lights use <code>NJS_LIGHT</code> structures described in the Katana SDK. One is set up using the parameters in the SL file (let’s call it the <code>ENV</code> Light), and the other is set up in code, usually in level binaries (let’s call it the <code>DIR</code> light). The <code>ENV</code> light has one configurable color that is shared for diffuse and specular, the <code>DIR</code> light can have different diffuse and specular color (though the game doesn’t seem to use that). It can also have a different light direction.
|Common switch, Hint monitor, OEggKanban (glowing Eggman logo in Final Egg, tube parts only), Chaos puddle in some cutscenes, Aoki Switch (top)
|-
|Simple Ninja Light
|Non-palettized lighting that uses one Ninja Light using the parameters from the SL file except the color, which is always white.
|Rock bits in Red Mountain, non-Jewel Chao, Master Emerald pieces, Froggy in Gamma’s Emerald Coast
|-
|Easy Light
|Non-palettized lighting that sets up the Easy Light (not <code>NJS_LIGHT</code>) using the parameters from the SL file. The Easy light is described in the Katana SDK. It doesn’t support specular lighting.
|Snowboard, OSandSwitch (Sand Hill switch), shadow blob, Chambr (chambers with opening doors in Sky Deck), debug objects, Aoki Switch (bottom), E101’s missiles, Hedgehog Hammer targets
|}

=== Rendering Functions and their SADX Counterparts ===
In SA1, most models were rendered with palette lighting using the game's custom function, but some models were rendered by calling Ninja drawing functions directly, which made them use the Ninja lights system. There are three light setups depending on the specific variation of the Ninja draw function:
{| class="wikitable"
!Light setup
!Functions in SADX (PC, 2004)
!Comment
|-
|Regular
|<code>njDrawModel</code> (0077EF70)
|Allows to use multiple <code>NJS_LIGHT</code>s of various types (directional, point, spot). Specular is supported.
|-
|Simple
|<code>___SAnjSimpleDrawModel</code> (00408520), <code>__SAnjSimpleDrawObject</code> (0040A130)
|Only the first registered <code>NJS_LIGHT</code> can be used. It is set up as a directional light, and intensity and color settings cannot be adjusted. Specular is supported.
|-
|Easy
|<code>njEasyDrawObject</code> (0040A100), <code>njEasyDrawModel</code> (004084F0), <code>njEasyDrawMotion</code> (00406FA0), <code>njEasyDrawShapeMotion</code> (00406FE0)
|Uses one "easy" light (not <code>NJS_LIGHT</code>). Specular is not supported. From the SDK: The light vector uses the screen space coordinate system. E.g. if set up like <code>njSetEasyLight( 0.0f, 0.0f, 1.0f );</code>, the light source will always be in front of the screen. To set the light source in 3D space, they must be converted with the current matrix:<syntaxhighlight lang="cpp">
light.x = LIGHT3D_X; light.y = LIGHT3D_Y;
light.z = LIGHT3D_Z; njCalcVector( NULL, &light, &lwork );
njSetEasyLight( lwork.x, lwork.y, lworkz );
</syntaxhighlight>After this, the Easy light source will be at <code>LIGHT3D_X,</code> <code>LIGHT3D_Y, LIGHT3D_Z</code>
|}
The SADX functions are a rough match since SADX changed draw functions for a lot of objects, and all that is left is some wrapper functions that call a more generic draw function:

# The Regular functions are difficult to tell from the paletted functions, so the above table is an approximation.
# The Easy functions are mostly still there.
# The Simple functions only have two stubs which aren't called by anything other than the Chao Name Machine, which doesn't match SA1.

=== Lighting Data ===
The data sources for the lights are as follows:
{| class="wikitable"
!Light
!Type
!Direction
!Color
!Diffuse, specular, ambient intensity
|-
|Regular - light 1
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file
|-
|Regular - light 2
|Directional
|<code>njSetLightDirection</code> called in the skybox display function
|<code>njSetLightColor</code> called in the skybox display function
|<code>njSetLightIntensity</code> called in the skybox display function
|-
|Simple
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|White (in SA1 anyway)
|From the SL file
|-
|Easy
|Directional
|<code>(0, -1, 0)</code> rotated using <code>RY</code> and <code>RZ</code> values from the SL file
|From the SL file
|From the SL file, no specular
|}
In addition to these lights, there can be custom lights set up by objects' code, which will affect all objects rendered with Regular functions. These custom lights can be directional, spot or point, with or without specular. The custom lights are created with the function <code>le_CreateLight</code> (0040A510 in SADX) and deleted with the function <code>le_DeleteLight</code> (0040A550 in SADX).

In the Dreamcast version, these functions use pointers to actual <code>NJS_LIGHT</code>s. In SADX, the Ninja Lights system appears to have been replaced by a system using the structure <code>LE_LIGHT_ENV</code> (what is also known as "Stage lights"). Instead of specific pointers, there is now an array of four "current stage lights" called <code>le_env</code> at 03ABD9F8. It also has a corresponding array of four Ninja light flags <code>le_env_typ</code> at 03ABDBB8. So instead of <code>NJS_LIGHT</code> pointers, the light create/delete functions manipulate data in these arrays in SADX.

Interestingly enough, the data for the light "Regular- light 2" is completely the same in SADX. It's still set up by the skybox display functions which call <code>njSetLightColor</code> etc. with the same arguments as the Dreamcast version, so basically we don't need the data from this post. However, now that these functions are redirected to modify the first entry in the <code>le_env</code> array, this data is overwritten every time a stage loads. That is happening because the function <code>le_set_env</code> (0040A95) copies over all light data from the SADX stage lights array (00900E88), which happens every time a light type is set and whenever a new level loads.

The following behavior of Ninja Lights is different from palette lighting:

<code>NJD_FLAG_IGNORE_SPECULAR</code> disables specular lighting ''completely'' (per material).

<code>NJD_FLAG_USE_FLAT</code> enables flat shading (used by Master Emerald pieces).

=== '''Custom''' '''Lights''' ===
There's a leftover function in SADX that creates custom lights associated with specific objects: <code>asSetLight</code> at 0040ADC0. It uses a <code>taskwk</code> pointer, an <code>NJS_LIGHT</code> pointer and a pointer to a structure called <code>LightInfo</code>:<syntaxhighlight lang="cpp">
struct LightInfo
{
int lsrc; // Ninja light flags
float spc;
float dif;
float amb;
NJS_ARGB argb;
NJS_POINT3 pos; // Light position (for spot and point lights)
NJS_POINT3 vec; // Light direction
float nrang; // Distance at which light source attenuation begins
float frang; // Distance to cut the effect of the light source (range)
int iang; // The angle at which the specular or spotlight is at maximum intensity
int oang; // The angle at which the specular or spotlight effect ceases
};
</syntaxhighlight>The following Ninja light flags can be used. The ones in bold are used in SA1, and the ones crossed out are unlikely to have been used in SA1.
{| class="wikitable"
!Flags
!Flag name
!Light type
!Ambient
!Diffuse
!Specular
|-
|0x01
|NJD_AMBIENT
|Ambient
|〇
|×
|×
|-
|0x02
|NJD_DIR_LIGHT
|Directional
|×
|〇
|×
|-
|0x03
|'''NJD_LAMBERT_DIR'''
|Directional
|〇
|〇
|×
|-
|0x04
|'''NJD_POINT_LIGHT'''
|Point
|×
|〇
|×
|-
|0x05
|NJD_LAMBERT_POINT
|Point
|〇
|〇
|×
|-
|0x08
|NJD_SPOT_LIGHT
|Spot
|×
|〇
|×
|-
|0x10
|NJD_SPEC_DIR
|Directional
|×
|〇
|〇
|-
|0x13
|NJD_PHONG_DIR
|Directional
|〇
|〇
|〇
|-
|0x20
|NJD_SPEC_POINT
|Point
|×
|〇
|〇
|-
|0x25
|'''NJD_PHONG_POINT'''
|Point
|〇
|〇
|〇
|-
|0x40
|<del>NJD_USER_LIGHT</del>
|Call a custom callback function
|
|
|
|-
|0x80
|'''NJD_SIMPLE_LIGHT'''
|Simplified lighting calculations (NOT the "Simple light" described earlier)
|
|
|
|-
|0xC0
|<del>NJD_BLOCK_LIGHT</del>
|Simplified lighting calculations
|
|
|
|}
The following custom lights have some leftover code and data in SADX. These also exist in SA1 but they aren't visible normally because the models that were supposed to be lit by them are rendered with palette lighting.

# Ice Cap background light: <code>NJD_PHONG_POINT</code>, <code>LightInfo</code> structure at 00C67FA0. Uses angles.
# "Chaos underlight": <code>NJD_POINT_LIGHT</code>, <code>NJS_LIGHT</code> structure at 03D0D5B8. The light is initialized using the function <code>ChaosUnderLightInit</code> (007AD250) that has a "radius" argument which goes unused in SADX but in SA1 it should be the light range. In Chaos' main functions, the light's matrix is transformed to match Chaos' position.
# Some light in Knuckles' story cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006868F0.
# Lights in Gamma's briefing cutscene: <code>NJD_SIMPLE_LIGHT | NJD_LAMBERT_DIR</code>, function at 006F4570. The light is a leftover, but this effect was adapted to palette lighting, and palette-related functions are called here too.

=== '''Specular''' '''Lighting''' ===
The Specular calculation formula for the Ninja Lights is currently unknown for Basic models. For Chunk models (which SA1 DC doesn't use), the formula was reversed by ''Exant'' for Simple and Easy lights:
[[File:Ninja Lights 1772333955721.png|none]]

File:Ninja Lights 1772333955721.png

2026-03-01T02:59:17Z

PkR:

Sonic Adventure Autodemo/Restoration

2026-02-28T10:19:06Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the Sonic Adventure Autodemo was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on booting Sky Deck as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This restoration was achieved in 2024 through a collaboration of x-hax users and symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new spreadsheet of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to find missing textures in the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version, where missing textures were recreated by its developers, and Dreamcast SDKs, which surprisingly have some early SA1 textures.

Apart from making stages bootable, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, adding textures that are missing on the disc, restoring debug functionality etc.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a spreadsheet along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

The restoration was primarily discussed in a series of threads on x-hax Discord. An archive of the discussion will be available for download at a later date.

== Restoration Details ==

=== Stage Select ===

=== Debug Functionality ===

=== Ninja Lights ===

=== Practice Stages ===
It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

Practice 2 does not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Sonic Adventure/Ninja Lights|Ninja Lights]] are used instead.
[[File:Pinball mode practice.mp4|thumb]]
<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Twinkle Park ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

Sonic Adventure Autodemo/Restoration

2026-02-28T06:57:53Z

PkR:

''This page is dedicated to projects that restore content and functionality in the Autodemo prototype of Sonic Adventure (Dreamcast). For Sonic Adventure PX (PC) mods that implement Autodemo features, see [[SADX Autodemo Mods|this page]] instead.''

When the Sonic Adventure Autodemo was first dumped in 2013, it was soon discovered that it was a semi-functional build of the full game. The Autodemo was quickly hacked to unlock player controls and load stages manually so that they could be explored freely. However, many stages did not load because the binaries containing them were originally compiled for an older version of the game's main executable.

The Autodemo has been researched ever since it was dumped, and the non-functional stages were eventually extracted using [[SA Tools]] and ported to the PC version. However, being able to play them in the Autodemo itself was desirable in order to see differences in the game's code, which couldn't be exported by the tools.

Initial work on restoring Autodemo functionality ingame was done back in 2015, when the user ''evilhamwizard'' posted their findings in the [https://forums.sonicretro.org/posts/846056/ Autodemo discussion thread on Sonic Retro]. The work focused primarily on restoring the original Windy Valley, and a number of GIFs of the level running on the emulator [https://forums.sonicretro.org/posts/867245/ were posted in 2016]. Some updates were posted on booting Sky Deck as well.

In 2024, based on ''evilhamwizard''<nowiki/>'s initial research, a new restoration project was started by [[x-hax]] (primarily by ''Speeps''), aiming to make other stages bootable, as well as improving the original Windy Valley restoration. This restoration was achieved in 2024 through a collaboration of x-hax users and symbol information acquired from the leaked Xbox 360 SADX prototype. The project is [https://github.com/X-Hax/dreamcast-mods available as a GitHub repository].

==Background and Method==
The files included on the Autodemo disc come from different builds of the game that were at different stages of development. When the Autodemo was put together, only the stages that were meant to be shown in the demo were recompiled, and the other stages were left over from older builds (for most of these, textures and lighting files were also missing). We can tell which binaries were recompiled by looking at file dates on the Autodemo GD-ROM. Only the files dated October 15 work ingame as-is, and other files cause the game to crash. The crash happens because the functions in the game's updated main binary (1ST_READ.BIN) are at different memory addresses from those expected by the code in stage binaries which were compiled for the older version of the game.
{| class="wikitable mw-collapsible mw-collapsed"
!'''October 15, 1998 (working)'''
!'''October 7, 1998 (broken)'''
!'''September 24, 1998 (broken)'''
|-
|STG01 (Emerald Coast)
|AL_GARDEN01 (Egg Carrier/Beta Windy Valley Chao Garden)
|STG00 ("Practice" Stages)
|-
|STG04 (Speed Highway)
|AL_GARDEN02 (Mystic Ruins Chao Garden)
|STG02 (Windy Valley)
|-
|STG05 (Red Mountain)
|AL_RACE (Chao Race)
|STG03 (Twinkle Park)
|-
|STG08 (Ice Cap)
|
|STG06 (Sky Deck)
|-
|STG10 (Final Egg)
|
|STG07 (Lost World)
|-
|ADV00 (Station Square)
|
|STG09 (Casinopolis)
|-
|ADV00OBJ (Station Square objects)
|
|ADV02 (Mystic Ruins)
|-
|ADV0100 (Egg Carrier Outside)
|
|ADV02OBJ (Mystic Ruins objects)
|-
|ADV0130 (Egg Carries Inside)
|
|SHOOTING (Sky Chase)
|-
|ADV01OBJ (Egg Carrier objects)
|
|MINICART (Twinkle Circuit)
|-
|AL_GARDEN00 (Station Square Chao Garden)
|
|B_E101_R (E-101 MK2)
|-
|AL_MAIN (Chao)
|
|B_ROBO (ZERO)
|-
|B_CHAOS2 (Chaos 2)
|
|B_EGM1 (Egg Hornet)
|-
|
|
|B_EGM3 (Egg Viper)
|-
|
|
|SBOARD (Sand Hill)
|-
|
|
|B_CHAOS0 (Chaos 0)
|-
|
|
|B_CHAOS4 (Chaos 4)
|-
|
|
|B_CHAOS6 (Chaos 6)
|-
|
|
|B_CHAOS7 (Perfect Chaos)
|}
However, as originally demonstrated by ''evilhamwizard'', it’s possible to find the functions and data they were meant to point to by comparing the pointers to known functions and data between these files and the files that boot. In 2024, ''Speeps'' started putting together a new spreadsheet of known broken pointers and their correct counterparts. As the pointer list grew, more levels became functional when known pointers were replaced.

Early hacks by ''Speeps'' were using simple patches to the executables applied through a hex editor. To facilitate mass pointer replacement and game testing, ''PkR'' reworked his SA1-DC-HD tool (originally meant to build GDIs of the final version of SA1 with enhancements) and created the [[Dreamcast Image Builder]]. The image builder uses a "mods" system that makes it easier to replace pointers, do all sorts of patching of game binaries and build a modified game image containing all of the selected hacks. In addition, some other tools on the [https://github.com/X-Hax/sa_tools_research SA Tools Research] repository were repurposed to find missing textures in the Autodemo by matching the names in the Autodemo’s texture lists against textures in the final version, the E3 build, the Autodemo Windy Valley mod for the PC version, where missing textures were recreated by its developers, and Dreamcast SDKs, which surprisingly have some early SA1 textures.

Apart from making stages bootable, the mods include various experiments with controls, framerate, lighting, skipping the intro movie, adding textures that are missing on the disc, restoring debug functionality etc.

The exact pointer matching procedure involved in stage restoration is as follows:
#Get the address of all pointers that read the stage's file from 1ST_READ. These are the Round Manager, Background Manager, Object List and Path List.
# Using IDA's graph view, gather all pointers to 1ST_READ (8Cxxxxxx).
# Using Ghidra, identify an object (using its name string) and check if the same code exists in SADX, where its symbol information can be taken from the 360 symbols.
# For all references to broken pointers in the object, attempt to find a working reference in a functional AutoDemo stage, such as Speed Highway.
# Replace the broken pointer with the working one.
All pointers were added to a spreadsheet along with their fixed version.

For any code that didn't have a matching reference in the PC version or a functional Autodemo stage file, such as code for objects that didn't exist in the final game, the original byte difference method was used instead. Using Ghidra, the resulting pointer was checked to ensure it led to an appropriate address (The beginning of a function etc.). Any pointers "fixed" with this method were marked in the table as unsure.

Stages that were similar enough to their final counterparts to share a lot of code (Twinkle Park, Lost World) were repaired first to build the database of known pointers, as stages with larger changes (Windy Valley) consisted almost entirely of code that didn't exist in the final game.

The restoration was primarily discussed in a series of threads on x-hax Discord. An archive of the discussion will be available for download at a later date.

== Restoration Details ==

=== Stage Select ===

=== Debug Functionality ===

=== Ninja Lights ===

=== Practice Stages ===
It turned out Practice 1 could load by just removing its SET File (Object Layout) because it only references 1ST_READ through that.

Practice 2 does not load because one of the meshes is too big for the game's [[Sonic Adventure/Lantern Engine|LANTERN lighting system]] to handle. However, it boots if [[Sonic Adventure/Ninja Lights|Ninja Lights]] are used instead.<gallery mode="nolines" caption="Practice Stages with Ninja Lights (images by ''MainJP'')">
File:Practice.webp|alt=
File:Sonic Adventure Autodemo Restoration 1772203956319.png
File:Screenshot 2024-08-30 15-59-50.webp
File:Screenshot 2024-08-30 16-15-14.webp
</gallery>

=== Windy Valley ===

=== Twinkle Park ===

=== Sky Deck ===

=== Lost World ===

=== Casinopolis ===

=== Station Square ===

=== Mystic Ruins ===

File:Pinball mode practice.mp4

2026-02-28T06:54:54Z

PkR:

File:Screenshot 2024-08-30 15-59-35.webp

2026-02-28T06:47:23Z

PkR:

File:Screenshot 2024-08-30 16-15-04.webp

2026-02-28T06:47:22Z

PkR: