[!NOTE] This is developer documentation! If you only intend on editing existing objects, you can ignore this page entirely.

(just like every other page, this one's also a big WIP!-)

Object Definitions (or "obj defs" for short) are files that tell SonLVL-RSDK how to display objects. They control not only how the object appears, but the various properties that appear in the properties window when selecting an object, as well.

Object definitions are contained within the SonLVLObjDefs folder, contained either next to the project file, or next to a mod's mod.ini. Inside the SonLVLObjDefs folder are object definition database INI files, where object definitions are mapped to RSDK object scripts.

(Figure out how to format this, whether we wanna talk about tags first or the sprites and properties themselves, as well as how to properly talk about listing objects in the first place)

There are three different types of object definitions, each suited for different complexities:

• Basic ini object definitions, for objects that only need to display a single sprite and have no additional properties.
• XML object definitions, for higher-level objects that display several sprites or contain additional object properties.
• C# object definitions for complex objects that require code to properly represent themselves in the editor.

Before getting into the nitty-gritty of it, there are a few general tags that are worth noting first:

Hidden

The hidden tag is used to mark objects that should not appear in the editor’s normal object lists. This tag is typically used for objects that should not be placed into scenes. For example, in Sonic 1, there is no purpose to placing a Motobug Exhaust object into the scene, so that object type is hidden by default. This hides it from both the Object Palette as well as the Add Object form, though it can still be spawned in a scene manually through changing an object’s type if needed.

Debug

The debug tag is used to mark objects as debug objects. The sole purpose of this tag is to hide objects when exporting maps with the Hide Debug Objects setting checked. For example, Invisible Block objects normally don’t appear in-game and can only be seen when in Debug Mode, so they are marked with the debug tag.

Basic INI Object Definitions

Basic INI Object Definitions are best suited for objects that only display one sprite and have nothing else to them at all. If an object has more than one sprite, or any custom properties, then you may want to consider moving to an [XML object definition](XML Object Definitions).

Defining the Sprite

Using SpriteFrames

First off, you need to assign a sprite to the object. You can either specify a spritesheet and a SpriteFrame (akin to normal game scripts), or you can specify a .ani file to load instead. For a spritesheet, the format is as follows:

sheet=[path to spritesheet gif]
frame=[SpriteFrame numbers)

For example, if a Ring's script is as follows:

LoadSpriteSheet("Global/Items.gif")
SpriteFrame(-8, -8, 16, 16, 1, 1)

Then the object definition frame data for it would look like:

sheet=Global/Items.gif
frame=-8, -8, 16, 16, 1, 1

Using Animation Files

Alternatively, you can also load a sprite from an animation file, instead. The format for doing so is simply:

anim=[animation file]:[animation number]:[frame number]

For example, take the following:

anim=Sonic.ani:10:2

This would load the 3rd frame (or ID: 2) from the 11th animation (or ID: 10) in the Data/Animations/Sonic.ani animation file.

Additional Tags

Beyond the sprite, there are also the aforementioned hidden and debug tags, which can be added as follows:

hidden=true
debug=true

If these lines are not included, they will simply default to false.

XML Object Definitions

For cases where basic ini defs can't do enough, such as for objects that display several sprites or have custom properties, XML Object Definitions can be used. XML files can be assigned to objects through the xmlfile tag in the object definition database ini. For example, assigning the XML file located at "SonLVLObjDefs/Global/Spring.xml" to the script "Scripts/Global/Spring.txt" would look like:

[Global/Spring.txt]
xmlfile=Global/Spring.xml

C# Object Definitions

In cases where XML does not satisfy an object's needs, such as objects C# code can instead be used to create object definitions.