Object

This article is about the definition and format of Objects. For a list of Object types that are available in SRB2, see List of Object types.

In SRB2, an Object (or mobj) is an entity that exists in a map that is not part of the level geometry. For example: the player, enemies and rings are Objects, while sectors and linedefs are not. "Mobj", short for "map object", is an alternative name for Object that is most commonly used within the source code. Some Objects can be placed directly onto a map with a map editor; the spawn points for these are called Things. Other Objects, such as shields, projectiles, and flickies, can only be spawned indirectly by other Objects, Lua scripts, or the game itself.

Objects can be grouped into types; each Object type defines the appearance and general behavior of all Objects belonging to it in the game – i.e. all Objects of a certain type will look and behave the same. SRB2 natively includes 658 different types of Objects. Each Object type has a set of attributes (listed below) which are commonly referenced by Objects belonging to it during gameplay; however, each Object has many individual properties of its own, independent from the Object type it belongs to. For instance, the Blue Crawla (or MT_BLUECRAWLA) is an Object type, whereas each individual Blue Crawla in GFZ1 is its own Object: they may face different angles to each other, can be chasing different players to each other, and some may not be moving at all.

Objects are sometimes erroneously referred to as "Things". This is a misnomer: Things themselves are not Objects, but simply spawn points to place particular types of Objects with. Not all Objects can be placed with a Thing; likewise, not all Things are directly linked to a single Object or Object type – examples of this include special placement patterns such as the Circle of Rings, or the Hoops used in NiGHTS levels.

SOC can be used to configure the attributes for existing Object types – hence the name "Sonic Object Configuration" – or declare freeslots for custom Object types whose attributes can then be modified in the same manner.

Object properties

To do Expand this section?

Objects in-game have many different properties, which control their behavior and appearance. Some of the most important Object properties are:

• The absolute X/Y/Z coordinates the Object is located at within a map, and the absolute angle the Object is facing (0 is East, ANGLE_90 is North, ANGLE_180 is West, and ANGLE_270 is South).
• The radius and height of the Object – these form the "collision box" of the Object, which controls the range of space the Object occupies and can collide with other Objects or walls within.
• States are used to animate the Object through use of sprites, as well as running one of many available actions to control the Object's behavior when a state is called. States may also apply extra settings for an Object during run-time, such as full brightness and translucency.
• Sounds can be referenced by an Object to be played back in certain situations.
• A set of toggles known as Object flags are used to determine the Object's general properties. An Object's flags may be changed during run-time to modify these properties.
• Objects can additionally have a skin and a skin color applied.

Lua can be used to write complex custom behavior for Objects, and has access to most of the properties for an Object – see Lua/Userdata structures > mobj_t for the full list of Object properties Lua can access. Lua can also be used to create additional properties for an Object.

Object type attributes

Header

In SOC, the Object type definition block must start with Object MT_OBJECTTYPE, where MT_OBJECTTYPE is the name of the Object type, which should be a name prefixed with "MT_". This can be an existing Object type (refer to List of Object types) or a custom Object type that has been created with the use of freeslots.

States

These attributes are reserved for anchoring references to special states, also known as "anchor states", that Objects of this type can switch to during gameplay for certain situations. The most important of these is SpawnState, which for all Object types determines the initial state an Object of that type will be in when spawned on the map. These anchors can be set to stand-alone states, the starting state of a long state sequence, or S_NULL if the Object is intended to disappear (or the anchor state isn't used anyway). Occasionally these attributes can be used to refer to other properties, such as Object types to spawn as projectiles.

For the vast majority of Object types however, only a few of these attributes have any use at all – the type of Object and the actions used by an Object (as well as hardcoded and Lua-scripted events) can affect which of these attributes are referenced and used. Listed below are the eight anchor states and their most common usages:

• SpawnState is the state that an Object calls when it is spawned. Its Duration may not be 0. If the SpawnState has an action, it will not be performed when the Object is first spawned unless the MF_RUNSPAWNFUNC flag is set on the Object. If the SpawnState is called again after that, however, the action will be performed even without the flag. This is the only anchor state that is used for the same purpose by all Objects that use it.
• SeeState is usually used by Objects that interact with the player. It is called once the Object spots a player, which can be done with the action A_Look and certain actions that are made specifically for some of SRB2's specific enemies.
• PainState is the state that Objects with the flag MF_BOSS or MF_ENEMY go to when they are damaged but not yet dead. Enemies with a SpawnHealth of 1 automatically die upon being hit and therefore do not use this state.
• MeleeState is the first of two designated "attack" states. Actions such as A_Chase call this or MissileState when the Object should attack. For other actions, this state may be used for miscellaneous purposes instead.
• MissileState is the second of two designated "attack" states. Actions such as A_Chase call this or MeleeState when the Object should attack. For other actions, this state may be used for miscellaneous purposes instead.
• DeathState is the state that Objects go to when they are destroyed, i.e. have no health points left. For regular enemies, this state or the sequence of states following it should eventually point to S_NULL, which is used to automatically remove the Object from existance.
• XDeathState is usually used as the fleeing state for bosses. It is called by the action A_BossDeath. For other actions, this may be used for miscellaneous purposes instead.
• RaiseState is used for miscellaneous purposes. A_ShootBullet, A_DropMine and A_JetgShoot all spawn Objects with this state. In this case, the RaiseState value refers to an Object instead of a state.

With the exception of PainState, an Object can switch to any of the states given by these attributes with the use of special auxiliary states to switch to these, regardless of Object type: S_SPAWNSTATE, S_SEESTATE, S_MELEESTATE, S_MISSILESTATE, S_DEATHSTATE, S_XDEATHSTATE, S_RAISESTATE.

Sounds

These attributes are reserved for anchoring references to special sound effects, also known as "anchor sounds", that can be played back when needed by an Object of this type for certain situations. Just as with anchor states, these conditions depending on the type of Object and the actions it uses. Some of these attributes correspond to one of the anchor states, and as such these sounds are often, but not always, called simultaneously with the corresponding states. There are also specific actions that can be used to play back these sounds. Listed below are the five sound attributes and their most common usages:

• SeeSound is usually played when the SeeState is executed. A_PlaySeeSound is made specifically to call this sound.
• AttackSound is usually played by certain attack actions for enemies. The action A_PlayAttackSound is made specifically to call this sound.
• PainSound is usually played when the PainState is executed. The action A_Pain is made specifically to call this sound.
• DeathSound is usually played when the DeathState is executed. The action A_Scream is made specifically to call this sound.
• ActiveSound is used for miscellaneous sounds that are part of an Object's animation. A_PlayActiveSound is made specifically to call this sound.

Object spawning

These attributes are used for determining basic properties a particular type of Object starts with when spawned, or determining how it is spawned in the game. Usually all of these attributes are mandatory, and should be set for all Object types.

• MapThingNum determines the Thing type number to use in map editors to place this Object type. Because of how Thing type numbers are handled, using any number beyond 4095 will result in the Object type being impossible to place. Use "-1" if the Object type should not be be placed directly on maps via a Thing. Enemies will also use this attribute to determine the flicky released when they are destroyed – see the Flickies article for more details.
• SpawnHealth determines the starting amount of health points an Object of this type has when spawned. Each hit subtracts one health point. When no health points are left, the Object enters its DeathState. Most enemies have this at 1, while the Crawla Commander has it at 2 and most bosses have it at 8. Some types of Objects in SRB2, such as scenery, cannot be damaged at all; in these cases, SpawnHealth's value is meaningless and is usually set to an arbitrary high value such as 1000 (it is advised not to set it to 0 however, as this may cause certain behavior not to function properly). Sometimes this is used for other purposes; for example, Objects with the MF_AMBIENT flag use this to determine the interval in tics between each playing of SeeSound.
• Radius determines the default and initial radius an Object of this type will be spawned with, or how far out from an Object's center a wall or another Object can collide with it. Due to the way collisions are handled in SRB2, however, collision boxes for Objects are in fact always square-shaped, with an Object's "radius" being the shortest distance from the center of the Object to the border of its collision box. This attribute should be given as the desired radius in fracunits multiplied by the constant FRACUNIT.
• Height determines the default and initial height an Object of this type will be spawned with. This attribute should be given as the desired height in fracunits multiplied by the constant FRACUNIT.
• Flags determines which of the primary Object flags an Object of this type will be spawned with. The primary Object flags for an Object are stored in a 32-bit integer where every bit represents a flag, i.e. 0 means "disabled" and 1 means "enabled". To set several flags at once, the bitwise OR operator (|) has to be performed on them. For example, to give all Objects of a particular type the primary flags MF_SPECIAL, MF_ENEMY and MF_RUNSPAWNFUNC, one would write Flags = MF_SPECIAL|MF_ENEMY|MF_RUNSPAWNFUNC in the corresponding Object SOC block.

Other attributes

These are miscellaneous attributes used for a variety of purposes. Most of these are used only by certain Object types and have no purpose for others. In these cases, their value is irrelevant and can be set to anything. Note that nearly all the names of these attributes are holdovers from Doom and do not always correspond to their purpose in SRB2.

• ReactionTime determines the starting "reaction time" value an Object of this type will be spawned with – this is a timer used and controlled by certain actions for delaying special behavior such as attacks. These actions deplete the timer each time they are called and only execute once it hits 0, at which point the timer is usually reset to the value of ReactionTime or an alternative value. Some Object types and actions may use this attribute for other purposes.
• PainChance is used for miscellaneous purposes. Most Object types do not use this attribute.
• Speed is used by various movement actions to determine the Object's speed, measured in fracunits/tic. Depending on which actions are used, or other factors, the wanted speed may be required to be given as an integer or as a multiple of the constant FRACUNIT. Some Object types and actions may use this attribute for other purposes.
• DispOffset determines the display offset for sprites of any Objects of this type. For instance, the shield orbs all have this set to 1, which means they are always displayed in front of the player when both are in the exact same position. Any integer value can be used here, including negative values; SRB2's Object types only use values up to 2, so anything above that will make sprites for this Object type take precedence over all of SRB2's native Object types. For most Object types, this can be set to 0.
• Mass, despite what its name may imply, is primarily used to determine the damage type of Objects with the primary flags MF_PAIN or MF_MISSILE. If an Object has MF_FIRE, the value of this attribute will be ignored and the damage type will always be DMG_FIRE. In the case of Object types without MF_PAIN or MF_MISSILE, such as enemies, the type of damage dealt will not be determined by this attribute, and instead it can be used for any miscellaneous purpose whatsoever. Most Object types do not use this attribute.
• Damage is used for miscellaneous purposes. Most Object types do not use this attribute.

SOC definition

This is an example of an Object type definition written with SOC and the syntax it uses.

Object MT_PLAYER
MapThingNum = -1
SpawnState = S_PLAY_STND
SpawnHealth = 1
SeeState = S_PLAY_RUN1
SeeSound = sfx_None
ReactionTime = 0
AttackSound = sfx_thok
PainState = S_PLAY_PAIN
PainChance = MT_THOK
PainSound = sfx_None
MeleeState = S_NULL
MissileState = S_PLAY_ATK1
DeathState = S_PLAY_DIE
XDeathState = S_NULL
DeathSound = sfx_None
Speed = 1
Radius = 16*FRACUNIT
Height = 48*FRACUNIT
DispOffset = 0
Mass = 1000
Damage = MT_THOK
ActiveSound = sfx_None
Flags = MF_SOLID|MF_SHOOTABLE
RaiseState = MT_THOK

Lua definition

This is an example of an Object type definition written with Lua. Note that "doomednum" is used in place of MapThingNum, while all other attributes are written in all-lowercase.

mobjinfo[MT_PLAYER] = {
        doomednum = -1,
        spawnstate = S_PLAY_STND,
        spawnhealth = 1,
        seestate = S_PLAY_RUN1,
        seesound = sfx_None,
        reactiontime = 0,
        attacksound = sfx_thok,
        painstate = S_PLAY_PAIN,
        painchance = MT_THOK,
        painsound = sfx_None,
        meleestate = S_NULL,
        missilestate = S_PLAY_ATK1,
        deathstate = S_PLAY_DIE,
        xdeathstate = S_NULL,
        deathsound = sfx_None,
        speed = 1,
        radius = 16*FRACUNIT,
        height = 48*FRACUNIT,
        dispoffset = 0,
        mass = 1000,
        damage = MT_THOK,
        activesound = sfx_None,
        flags = MF_SOLID|MF_SHOOTABLE,
        raisestate = MT_THOK
}