User:Monster Iestyn/Object

Notes for Object article.

Object properties

Objects in-game have many different types of attributes, which control their behavior and appearance:

• The absolute X/Y/Z coordinates the Object is located at within a map, and the absolute angle the Object's forward direction 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 hehavior when the 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 can have 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.

Map co-ordinates

All Objects that exist in-game will have a set of attributes relating to where they are located (or how they are orientated) within the current map:

The Object's X-position and Y-position determine the Object's absolute horizontal position (along the X-axis and Y-axis respectively) in fracunits, while the Z-position determines the Object's absolute vertical position (along the Z-axis) in fracunits. In all 3 dimensions, the Object's location is limited to a position between -32768 fracunits to +32768 fracunits relative to the origin (0,0,0).

The Object's angle determines the horizontal direction the Object's "front" is facing towards, measured in degrees going counter-clockwise – i.e. 0° is East, 90° is North, 180° is West, and 270° is South. While physically the Object's collision box will not be affected by the Object's angle, the sprite angle seen from another position around the Object will differ as the Object's angle changes. Sight-related behavior such with as the action A_Look may also depend on the Object's angle to determine what range of angles the Object can "see" in.

Dimensions/Collision box

A pair of attributes exist to determine an Object's physical dimensions, or the "collision box", which in turn control the range of space the Object occupies and can collide with other Objects or walls within:

The radius of an Object determines the distances from the Object's center to the edges of the collision box in both the X-axis and Y-axis directions separately. The height of an Object determines the distance between the top and bottom of the collision box. Both attributes are measured in fracunits.

A common misconception of the Object's collision box is that it takes the form of a cylinder – in reality, the Object's collision box is a cube or cuboid shape that is always oriented in the same fashion regardless of the Object's angle. This can be seen easily in-game when a player walks against a solid non-pushable Object (e.g a monitor) and attempts to slide along its sides.

Note that the Object's X/Y/Z co-cordinates correspond to the center-most point at the bottom of the Object's collision box.

Object flags

The Object flags are a series of toggles that determine an Object's general properties. They are used for a variety of different purposes, such as the Object's interaction with the level environment and other Objects as well as the type of thinker it uses. Some of them have very specific uses while others set more general options.

Animation

Most Objects are visually represented in-game by a set of sprites. The sprites used for an Object are themselves determined by a set of states, which an Object switches between in order to appear to animate; the current state an Object is using determines both the sprites it displays and the period of time in which it displays them. After this period, the state will then be switched with a pre-determined next state which assigns a new sprite and duration to display for the Object. States can be linked together in sequences in this manner to create complex animations, which may be made to eventually reach a final state that lasts indefinitely or loop back to an earlier state in the sequence.

An action can optionally be called by each state to be performed by an Object at the start of the state's duration. In nearly all cases these work only for the first instant or tic of the state's usage, and will have no effect for the rest of the time until the next state. A pair of integer variables, known as "Var1" and "Var2", can also be supplied with a state to modify the effect of the action called by it, if the action allows such modifications.

Skin colors and skins are special properties independent of states that can optionally be applied to Objects to further modify how an Object appears or behaves in-game: skin colors map a pre-determined set of colors in the palette present in the sprite to another set associated with the skin color, while skins are used with the special sprite set SPR_PLAY to switch out the default sprite set with a custom set specific to that skin. Both properties are most commonly associated with players, who utilise both features to determine the character the player uses as well as the color of the character used.

Target/tracer

An Object's target and tracer attributes refer to Objects related to the main Object itself.

Timers

Reaction time

This attribute is commonly used as a timer by a number of actions. These actions deplete the Object's reaction time each time they are called, and may perform certain behavior once it hits 0, at which point the reaction time is usually reset.

Fuse

When set to a non-zero value, this attribute determines the duration in tics before the Object performs certain behavior. This attribute will automatically deplete itself each tic until it reaches 0 – by default, an Object will switch to its XDeathState when this occurs, but may perform other effects depending on the Object type. Custom fuse effects may be configured by use of the action A_SetFuse or the Lua hook MobjFuse, both of which can override any default behavior.

Object type definition

Lua has the ability to modify existing Object type definitions or create new ones in a similar manner to SOC – with the use of an over-arching table called mobjinfo – but can also reference the attributes for specific Object type definitions if necessary (see Lua/Userdata structures > mobjinfo_t). It can additionally create additional attributes for any Object type definitions if needed.