UINT32 – Unsigned 32-bit integer; for technical reasons, this is treated as identical to INT32 in Lua.

Derived numerical

fixed_t – same as INT32; this indicates that the integer is a fixed-point value, and so should be a multiple of FRACUNIT unless otherwise stated. Note that the minimum and maximum limits for this type can be expressed as -32768*FRACUNIT and (32768*FRACUNIT)-1. See also Lua/Functions > Fixed-point math.

angle_t – same as UINT32; this indicates that the integer is an angle value, and so should be used with the ANG*/ANGLE_* constants unless otherwise stated. Note that ANGLE_180 and larger (including ANGLE_MAX) will be negative numbers due to being confined to INT32 limits in Lua. See also Lua/Functions > Angle math.

tic_t – same as UINT32; this indicates that the integer is a time in tics, unless otherwise stated. For a time in seconds expressed in tics, multiply the number of seconds by TICRATE (35 tics = TICRATE = 1 second).

Other

enum (prefix) – An enumerated type integer. This is intended to accept or return specific integers from a list represented by constants, but can still hold any kind of integer even outside the list. prefix displays the common prefix for the relevant group of constants that should be assigned or returned to this variable, and links to the article containing them.

type array – This a table containing multiple entries; type is the variable type of the returned value of entries within the table. The type of variables accepted as keys may be given in the Description/Misc notes column.

General

mobj_t

General

Accessibility

Read+Write

Allows custom variables

Yes

(Example uses will use mobj as the mobj_t variable here, with mobj.var to point to any of the mobj_t variables.)

mobj_t structure

Name

Type

Accessibility

Description/Misc notes

valid

boolean

Read-only

Returns true if the Object is valid (i.e., still exists), returns false otherwise.

x

fixed_t

Read-only

The Object's absolute x-position in the map. To modify this value, use a function such as P_TeleportMove rather than editing it directly.

y

fixed_t

Read-only

The Object's absolute y-position in the map. To modify this value, use a function such as P_TeleportMove rather than editing it directly.

The current sprite prefix the Object is displaying. Each time an Object switches states, it is reset to the new state's sprite prefix; this can be modified to be anything else at any time keeping this in mind.

frame

UINT32

Read+Write

The current sprite frame the Object is displaying, plus additional state info such as full brightness, animation, and translucency. Each time an Object switches states, it is reset to the new state's sprite frame; this can be modified to be anything else at any time keeping this in mind.

anim_duration

UINT16

Read+Write

If mobj.frame currently has the frame flag FF_ANIMATE, this is the duration in tics between each frame in the state's animation. Otherwise, this has no effect on the Object's animation. By default this is set to the current state's Var2 value.

The current subsector the Object is in. To obtain the sector the Object is in, use mobj.subsector.sector, though mobj.subsector will be nil for Objects currently being removed.

floorz

fixed_t

Read-only

The absolute "floor" position for the Object, i.e the height that it considers to be the floor. This will change if the Object is for instance above a solid FOF or solid Object, or has just moved to a different sector. For reverse gravity Objects however, this does not switch to ceilings.

ceilingz

fixed_t

Read-only

The absolute "ceiling" position for the Object, i.e the height that it considers to be the ceiling. This will change if the Object is for instance below a solid FOF or solid Object, or has just moved to a different sector. For reverse gravity Objects however, this does not switch to floors.

radius

fixed_t

Read+Write

The current radius of the Object. When the Object's scale is modified, this is reset to the default radius for the Object type the Object belongs to, adjusted according to the new scale. Otherwise this is freely adjustable (minimum limit is 0).

height

fixed_t

Read+Write

The current height of the Object. When the Object's scale is modified, this is reset to the default height for the Object type the Object belongs to, adjusted according to the new scale. Otherwise this is freely adjustable (minimum limit is 0). For players however, note that this is continuously corrected/modified to be either the default height or a set misc. height such as the "spinning" height.

momx

fixed_t

Read+Write

The Object's current x-axis momentum. +ve values shift the Object to the East, -ve values to the West. To modify this property properly with respect to an angle, this should be set to the full horizontal speed multiplied by cos(angle), angle being the absolute horizontal plane angle expressed as angle_t. For speeds also involving the z-axis, this should be also multiplied by cos(v-angle), v-angle being the vertical plane angle (assuming v-angle of 0 faces completely horizontal).

momy

fixed_t

Read+Write

The Object's current y-axis momentum. +ve values shift the Object to the North, -ve values to the South. To modify this property properly with respect to an angle, this should be set to the full speed multiplied by sin(angle), angle being the absolute horizontal plane angle expressed as angle_t. For speeds also involving the z-axis, this should be also multiplied by cos(v-angle), v-angle being the vertical plane angle (assuming v-angle of 0 faces completely horizontal).

momz

fixed_t

Read+Write

The Object's current z-axis momentum. +ve values shift the Object upwards, -ve values downwards. To modify this property properly with respect to a vertical plane angle, this should be set to the full speed multiplied by sin(v-angle), v-angle being the vertical horizontal plane angle expressed as angle_t (assuming angle of 0 faces completely horizontal). For completely horizontal movement this should just be 0.

pmomz

fixed_t

Read+Write

The Object's "platform" z-axis momentum, i.e., the z-momentum from the platform the Object is currently standing on.

tics

INT32

Read+Write

The current value of the Object's state timer, which goes down by 1 each tic until it reaches 0 (when the Object will switch to a new state). Each time an Object switches states, it is reset to the new state's tic duration; this can be modified to be anything else at any time keeping this in mind. A value of -1 will make the current state have infinite duration.

The current state number of the Object. When the value of this is changed, Lua will automatically switch the current state to the new value. mobj.sprite, mobj.frame, mobj.tics will be changed to the new state's sprite, frame and tics values respectively. Additional adjustments may be made for player Objects specifically however (such as player animation speeds and switching to superform states). Switching to the state S_NULL will make the Object disappear, but this cannot be used on player Objects.

Note that changing the value of mobj.state directly in Lua will cause the new state's action to be called automatically. To avoid this, the function P_SetMobjStateNF should be used instead.

flags

UINT32

Read+Write

The current primary flags the Object has. When the Object is first spawned, this is automatically set to the flags attribute for the Object type the Object belongs to, but can freely be adjusted afterwards. (Use MF_* constants)

The current skin applied to the Object. For Objects with mobj.sprite set to SPR_PLAY, this will change the appearance of the Object's sprites to that of the character the skin is associated with. This is most commonly used by players; however, Extra Life Monitors, Level End Signs, ghost trails, and player thok trails will also apply a skin when needed.

color

UINT8

Read+Write

The current skin color applied to the Object (SKINCOLOR_* constants are to be used). When modifying this for regular Objects, this will by default re-map the green range of colors (palette color #s 160–175) to the specified range for the color name given. However, for Objects using SPR_PLAY this can use the current skin's startcolor parameter instead to set the range of colors to color remap.

The current Object type number of the Object. It is possible to modify this variable, though this is not usually needed in most circumstances; note that mobj.info will automatically be modified at the same time to give the attributes for the new Object type.

Important note: for Objects spawned on the map via a Thing, modifying mobj.type to an Object type without a corresponding Thing type (i.e., mobj.info.doomednum has a value of -1) will cause the Object and its Thing to not be linked properly for players joining a netgame. This is because, when creating the $$$.sav file, the networking code incorrectly assumes Objects of these types will never have a corresponding Thing, regardless of the value of mobj.spawnpoint for any particular Object. This results in mobj.spawnpoint for such an Object becoming nil for any players joining the netgame.

This allows access to the attributes for the Object type the Object belongs to (used as a shortcut for mobjinfo[mobj.type]). mobj.info itself cannot be modified directly; if mobj.type is modified however, mobj.info will automatically be modified to give the attributes for the new Object type instead.

health

INT32

Read+Write

The Object's current health point amount. When the Object is first spawned, this is automatically set to the spawnhealth attribute for the Object type the Object belongs to, but can freely be adjusted afterwards. For Objects that don't necessarily need a health value, this can be used for miscellaneous purposes if needed.

movedir

angle_t

Read+Write

Used to indicate movement direction for A_Chase and related, using the DI_* constants. Otherwise, this can be used for any miscellaneous purpose whatsoever.

movecount

INT32

Read+Write

Used as a timer before the Object changes direction (usually if mobj.movecount == 0) for A_Chase and related. Otherwise, this can be used for any miscellaneous purpose whatsoever.

Generally used as a "target" Object for enemies and similar to chase towards/fire at. Projectiles (Objects with MF_MISSILE) should set this to the Object that fired them, so they cannot harm/crash into the firer. Otherwise, this can be used to link any related Object at all if needed.

reactiontime

INT32

Read+Write

Used as a timer to delay certain behavior such as attacks (usually if mobj.reactiontime == 0) for a number of actions, including A_Chase and related. When the Object is first spawned, this is automatically set to the reactiontime attribute for the Object type the Object belongs to, but can freely be adjusted afterwards. For players, this is used by some types of teleports to prevent the them from moving until it has reached 0. Otherwise, this can be used for any miscellaneous purpose whatsoever.

threshold

INT32

Read+Write

Used as a timer before switching targets (usually if mobj.threshold == 0) for A_Chase and related. Otherwise, this can be used for any miscellaneous purpose whatsoever.

For player Objects, this points to the player's properties (e.g, mobj.player.pflags or mobj.player.powers[pw_invulnerability]). It is recommended mobj.player.mo is not used as this just points back to mobj itself, which is redundant. For regular Objects mobj.player will return nil.

lastlook

INT32

Read+Write

Used to store the player # of the last player targeted for A_Chase and related. Otherwise, this can be used for any miscellaneous purpose whatsoever.

For Objects that have been spawned on the map via a Thing (or "spawn point"), this points to the Thing that spawned it by default. If one doesn't exist, this returns nil. However, this variable can be adjusted to point to a different Thing if needed, or to not point to any Thing at all by using mobj.spawnpoint = nil.

Important notes:

if an Object belongs to an Object type that does not have a corresponding Thing type number (i.e., mobj.info.doomednum has a value of -1), modifying mobj.spawnpoint to a non-nil value will cause the Object and its Thing to not be linked properly for players joining a netgame. This is because, when creating the $$$.sav file, the networking code incorrectly assumes the Object will never have a corresponding Thing, regardless of the value of mobj.spawnpoint. This results in mobj.spawnpoint for such an Object becoming nil for any players joining the netgame.

it is recommended not to make multiple Objects point to the same Thing; for players joining a netgame, $$$.sav will edit mobj.spawnpoint.mobj for all Objects with a mobj.spawnpoint value (except for Object types with no corresponding Thing type; see note above) to point back to mobj, assuming it is the Object that the Thing (mobj.spawnpoint) originally spawned. As mobj.spawnpoint.mobj can only point to one Object at a time, this may result in it pointing to a different Object for players who have just joined the game.

Generally used as a secondary "target" Object when mobj.target. is not available/taken up. For players this is often used to link players to the next waypoint to move towards, or the Object the player is being carried by currently. Otherwise, this can be used to link any related Object at all if needed.

friction

fixed_t

Read+Write

The Object's current "friction" value. Contrary to real-life friction physics, this is used as a multiplier for mobj.momx and mobj.momy to slow down/speed up the Object when touching the ground, so in a sense the higher the value of mobj.friction the less sludgy/more slippery the floor surface becomes to the Object.In general:

mobj.friction values smaller than FRACUNIT will slow down the Object on the ground.

mobj.friction values greater than FRACUNIT will speed up the Object on the ground.

mobj.friction values equal to FRACUNIT will not slow down nor speed up the Object at all.

The default mobj.friction value for most Objects is 59392 (hexadecimal: 0xe800), or 0.90625 * FRACUNIT, or 29/32 * FRACUNIT (29*FRACUNIT/32 should be used if you want to set this yourself)

movefactor

fixed_t

Read+Write

The Object's current "movefactor" value. Formerly may have been used for friction-related purposes, but is currently used only for miscellaneous purposes instead.

fuse

INT32

Read+Write

Commonly used as a timer before the Object disappears or does something else, which automatically goes down by 1 each tic until it reaches 0. This is also used for miscellaneous purposes, but this has to be kept the same value always for this to work.

watertop

fixed_t

Read+Write

Absolute "water top" position for the Object, i.e., the top height of the water FOF currently touching the Object. This will change if the Object has just moved to a different water block or is not in a water block at all (defaults to mobj.z - 1000*FRACUNIT in this situation).

waterbottom

fixed_t

Read+Write

Absolute "water bottom" position for the Object, i.e., the bottom height of the water FOF currently touching the Object. This will change if the Object has just moved to a different water block or is not in a water block at all (defaults to mobj.z - 1000*FRACUNIT in this situation).

mobjnum

N/A

None

Unusable by Lua – this is a networking thing used for $$$.sav and so shouldn't be available for Lua usage.

scale

fixed_t

Read+Write

The Object's current scale, normal scale is FRACUNIT. When this is modified by Lua with mobj.scale = newvalue, this will automatically use P_SetScale(mobj, newvalue) internally to adjust the Object's radius and height, but will also change mobj.destscale to match. This means using P_SetScale itself directly is not redundant as it does not affect mobj.destscale internally, allowing gradual scale changes (rather than instantaneous) to be possible.

destscale

fixed_t

Read+Write

The Object's destination scale; if the Object is not currently this scale, it will gradually change mobj.scale's value to match this value.

scalespeed

fixed_t

Read+Write

The Object's scale-changing speed, for when the Object is gradually changing scale to reach mobj.destscale's value. The default value used for most cases is FRACUNIT/12, but this can be adjusted to speed up/slow down scaling if needed.

extravalue1

INT32

Read+Write

An extra variable for Objects to use in SRB2's source code. This is freely available for any Object to use for any purpose whatsoever, though some regular SRB2 Objects may already use this.

extravalue2

INT32

Read+Write

An extra variable for Objects to use in SRB2's source code. This is freely available for any Object to use for any purpose whatsoever, though some regular SRB2 Objects may already use this. Mind that A_Repeat in particular currently uses this internally to set the repeat count.

cusval

INT32

Read+Write

The Object's current "custom value" variable, ported from the v2.0 modification SRB2Morphed. This is intended to be used by the numerous Actions also implemented for this and mobj.cvmem (such as A_CheckCustomValue or A_CusValAction), though can be freely used for any purpose whatsoever.

cvmem

INT32

Read+Write

The Object's "custom value" variable saved in memory, ported from the v2.0 modification SRB2Morphed. This is intended to be used by the numerous Actions also implemented for this and mobj.cusval (such as A_CheckCustomValue or A_CusValAction), though can be freely used for any purpose whatsoever.

Points to the player's mobj_t properties (such as x/y/z position and angle).

Note: By default player.mo is a pre-determined Object of the type MT_PLAYER; however, player.mo can be changed to Objects of any type (but cannot be set to nil). It is not recommended to use non-MT_PLAYER Objects though – the sprites for the player's character will still appear when walking, running, etc. regardless of the Object's type, and the player may also not behave properly when using particular special map effects if they are not using an MT_PLAYER Object.

The player's absolute viewing height (or viewing Z position) used in 1st person camera mode. The game will automatically update this variable every tic; the exact calculation used depends on the player's gravity direction:

In both cases, (bobbing displacement) is a displacement value calculated using player.bob, which causes the player's view to appear to "bob" up and down as they walk. If the player is not on the ground, or not currently using the 1st person camera, then this extra value will not be added on regardless of the player's walking speed.

Note: If not modified by Lua, this value is only calculated by the game for local players, and thus isn't network safe. Use at your own risk.

viewheight

fixed_t

Read+Write

The player's relative viewing height used in 1st person camera mode. This normally set to the value of the console variable VIEWHEIGHT (scaled to the player's current scale), though sometimes it may be reduced for effects such as landing on the ground – in these cases, player.deltaviewheight is used to gradually return player.viewheight to its normal value.

Note: If not modified by Lua, this value is only calculated by the game for local players, and thus isn't network safe. Use at your own risk.

deltaviewheight

fixed_t

Read+Write

The value to re-adjust player.viewheight by the next tic when it has moved away from the normal height (e.g., when landing on the ground, the viewheight dips a bit then rises back up – both the lowering and rising is done by player.deltaviewheight).

Note: If not modified by Lua, this value is only calculated by the game for local players, and thus isn't network safe. Use at your own risk.

bob

fixed_t

Read+Write

The current range of the player's "bobbing" displacement used in 1st person camera mode, relative to the base viewing height. The value of this variable normally depends on the player's current speed:

The actual bobbing displacement calculated for player.viewz oscillates between -(player.bob/2) and +(player.bob/2). The maximum value for player.bob itself is 16*FRACUNIT.

Note: If not modified by Lua, this value is only calculated by the game for local players, and thus isn't network safe. Use at your own risk.

aiming

angle_t

Read+Write

The player's current vertical viewing angle; player.aiming = 0 would be facing directly forward, player.aiming > 0 would face upwards, and player.aiming < 0 would face downwards. If player.pflags has the flag PF_FLIPCAM, the value of player.aiming will be flipped whenever the player is given reverse gravity or reverts back to normal gravity.

Note: This value is limited to a maximum of ANGLE_90 -1 in either direction; however, the Software renderer limits what is seen in-game to ANGLE_90 - ANG10.

health

INT32

Read+Write

A copy of the player's current health to display on the HUD. Modifying this does not affect the player's actual health; to do that you would need to use player.mo.health instead of player.health. (However, player.health should nevertheless be updated as well to match player.mo.health's value)

Note: the actual "RINGS" value displayed on the HUD is normally calculated as player.health - 1.

pity

SINT8

Read+Write

The player's "pity" hit counter for Match/CTF modes; normally when player.pity reaches 3 or above, this will spawn a Pity Shield around the player and player.pity will be reset to 0.

currentweapon

INT32

Read+Write

The weapon the player currently has selected to be fired (use WEP_* constants)

ringweapons

INT32

Read+Write

Contains all the weapons the player is currently able to use, stored as flags (use RW_* constants)

powers[powername]

UINT16 array

Table: Read-onlyTable entries: Read+Write

A table containing the current values for all powers for the player, where powername is an integer expected to be one of the pw_* constants. The table itself cannot be directly reassigned, but entries in it can be accessed or modified. Use of the values depends on the power selected – see the A_CustomPower article for more information on each power.

The player's current animation – in the source code, this variable is frequently used as a shortcut in place of explicitly checking a range of states for each player animation (e.g., PA_WALK covers states S_PLAY_RUN1 to S_PLAY_RUN8). This can also be modified to allow for custom states to act as if they were the animation for certain extra effects to work with them. Do note that player.panim is corrected every time the player's state is changed.

flashcount

UINT16

Read+Write

Amount of time the player is set to the palette set by player.flashpal. P_FlashPal can be used to set this along with player.flashpal.

flashpal

UINT16

Read+Write

Sets the palette number displayed on the screen for the player. player.flashcount also has to be set for this to have any affect when modified. P_FlashPal can be used to set this along with player.flashcount.

skincolor

UINT8

Read+Write

The player's "normal" skin color (SKINCOLOR_* constants are to be used). In Single Player, this is basically a copy of the prefcolor set for the player's character; in multiplayer, it is the player's chosen skin color selected in the Player Setup menu or through the console variable COLOR. Values above SKINCOLOR_GOLD should not be used for this variable.

It is important to note that player.skincolor is not the actual skin color displayed in-game (which would be player.mo.color), but a backup skin color variable for player.mo.color to reference – this is useful for when the player has turned Super or collected a power-up that changes their skin color (e.g., the Fire Flower, or Mario mode's invincibility), where player.skincolor can then be used to restore the player's "normal" skin color when they are no longer Super or have lost the power-up.

For instance, when the player has collected a Fire Flower powerup, player.mo.color is changed to SKINCOLOR_WHITE, while player.skincolor remains the original skin color the player had before. Afterwards, if the player lost this power-up, player.mo.color is re-set to the value of player.skincolor, restoring the player's original skin color.

score

UINT32

Read+Write

The player's current score. In most cases, this should be modified using P_AddPlayerScore to account for limits, extra life bonuses, team gametypes and NiGHTS mode.

dashspeed

fixed_t

Read+Write

The thrust speed currently charged up for the player's spindash. Normally, this has a value of zero; while the Spin key control is being held down, however, it will slowly increase its value. During the latter phase, player.mindash and player.maxdash are the minimum and maximum values that player.dashspeed can possibly have. When the Spin key is released, player.dashspeed becomes the final speed the player's spindash is released at; after this occurs, player.dashspeed itself is reset to zero.

dashtime

INT32

Read+Write

The time the player has been charging up spin in tics, used to determine when to play the spindash charging sound.

normalspeed

fixed_t

Read+Write

The player's current normalspeed value for the character skin used. This is a copy of the skin's actual normalspeed value from the S_SKIN (multiplied by FRACUNIT) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

runspeed

fixed_t

Read+Write

The player's current runspeed value for the character skin used. This is a copy of the skin's actual runspeed value from the S_SKIN (multiplied by FRACUNIT) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

thrustfactor

UINT8

Read+Write

The player's current thrustfactor value for the character skin used. This is a copy of the skin's actual thrustfactor value from the S_SKIN and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

accelstart

UINT8

Read+Write

The player's current accelstart value for the character skin used. This is a copy of the skin's actual accelstart value from the S_SKIN and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

acceleration

UINT8

Read+Write

The player's current acceleration value for the character skin used. This is a copy of the skin's actual acceleration value from the S_SKIN and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

charability

UINT8

Read+Write

The player's current ability value for the character skin used (CA_* constants should be used). This is a copy of the skin's actual ability value from the S_SKIN and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

charability2

UINT8

Read+Write

The player's current ability2 value for the character skin used (CA2_* constants should be used). This is a copy of the skin's actual ability2 value from the S_SKIN and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

charflags

UINT32

Read+Write

The player's current flags value for the character skin used (SF_* constants should be used, combined together as flags). This is a copy of the skin's actual flags value from the S_SKIN and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

The player's current thokitem value for the character skin used. This is a copy of the skin's actual thokitem value from the S_SKIN (unless it was set to -1, which will default to MT_THOK) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

The player's current spinitem value for the character skin used. This is a copy of the skin's actual spinitem value from the S_SKIN (unless it was set to -1, which will default to MT_THOK) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

The player's current revitem value for the character skin used. This is a copy of the skin's actual revitem value from the S_SKIN (unless it was set to -1, which will default to MT_THOK) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

actionspd

fixed_t

Read+Write

The player's current actionspd value for the character skin used. This is a copy of the skin's actual actionspd value from the S_SKIN (multiplied by FRACUNIT) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

mindash

fixed_t

Read+Write

The player's current mindash value for the character skin used. This is a copy of the skin's actual mindash value from the S_SKIN (multiplied by FRACUNIT) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

maxdash

fixed_t

Read+Write

The player's current maxdash value for the character skin used. This is a copy of the skin's actual maxdash value from the S_SKIN (multiplied by FRACUNIT) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

jumpfactor

fixed_t

Read+Write

The player's current jumpfactor value for the character skin used. This is a copy of the skin's actual jumpfactor value from the S_SKIN (multiplied by FRACUNIT) and can be modified freely, keeping in mind it will be reset whenever the skin is switched.

lives

SINT8

Read+Write

The player's current lives count.

continues

SINT8

Read+Write

The player's current continues count.

xtralife

SINT8

Read+Write

The ring extra life bonus counter, used to check how many extra lives have been given from collecting 100 rings so that it can stop rewarding them after a certain amount (set by MaxXtraLife in the MainCfg block).

gotcontinue

UINT8

Read+Write

Used in NiGHTS special stages to signify whether the player has collected a continue or not from the current map. This is used as a boolean despite being defined as an integer.

speed

fixed_t

Read+Write

The absolute "real" speed the player is currently moving at in any direction. This is calculated using player.rmomx and player.rmomy normally – however, when playing as NiGHTS Super Sonic this is handled completely differently. Modifying this will not change the player's actual speed (modify player.mo.momx and player.mo.momy to do this).

jumping

boolean

Read+Write

Determines whether the player's jump can be cut or not when the jump button is released; when player.jumping is set to true jump momentum cutting can be done, false if not.

secondjump

UINT8

Read+Write

Used by some abilities (Float, Slow fall and Air drill) to set what state in using an ability during a jump the player is in:

CA_AIRDRILL: Increases when spin button is held to speed up falling down during use of the ability.

fly1

UINT8

Read+Write

Used by CA_FLY/CA_SWIM abilities (the non-multiability versions) to boost the player up for as long as player.fly1 is not 0.

scoreadd

UINT8

Read+Write

The player's combo bonus counter. Goes up by one every time an enemy is hurt, the higher this gets the greater the score bonus for destroying enemies given. Normally resets to 0 when the player is touching the ground (unless invincibility is being used) or climbing a wall.

glidetime

tic_t

Read+Write

The player's glide timer, the amount of time the player has been gliding for. Used to gradually speed up the horizontal gliding thrust over time.

climbing

UINT8

Read+Write

Used by the climbing ability to determine what state of climbing the player is currently in:

player.climbing == 0: not climbing

player.climbing == 1: climbing

player.climbing > 1: the player thrusts in the direction they are facing to press against the wall, and player.climbing decreases until it reaches 1

deadtimer

INT32

Read+Write

The player's death timer, the amount of time the player has been dead for. Used to automatically trigger effects after some time such as respawning, switching to the continue screen, changing back to the map's usual music, or just ending the game.

exiting

tic_t

Read+Write

The player's "exiting" timer, or the amount of time left in tics until the level automatically ends. By default player.exiting is set to 0, to mark that the player is not currently "exiting" the level. When it is set to a non-zero value, the following effects occur:

The player becomes invincible but unable to move.

The camera moves to a larger distance away from the player (except when playing as NiGHTS Super Sonic).

If playing as NiGHTS Super Sonic in a NiGHTS level, the player will rise up towards the ceiling and rotate constantly.

Lastly, player.exiting itself will automatically decrease over time until it reaches the value 2, after which the level will automatically be finished.

In multiplayer, however, the last of these effects differ depending on the value of PLAYERSFOREXIT – if set to ONE, all living players are required to be in an "exiting" state (i.e., they must all have a non-zero player.exiting value) before the level can end; if set to ALL, the level will automatically finish for everyone regardless.

For reference, P_DoPlayerExit by default sets player.exiting to a value of (14*TICRATE)/5 + 1 (99 tics, or about 2.8 seconds). If the gametype is Race or Competition and all players have finished, a value of 3*TICRATE (105 tics, or 3 seconds) is given instead.

homing

UINT8

Read+Write

The player's homing timer, for CA_HOMINGTHOK. This will decrease until it reaches 0. For as long as player.homing is > 0 the player will be able to home in on a set target enemy, but once player.homing reaches 0 this will stop.

skidtime

tic_t

Read+Write

The player's skidding timer, for when the player skids to slow down or land from gliding. This will decrease until it reaches 0. For as long as player.skidtime is > 0 the skidding sound is played and skid particles will be spawned behind the player, and for regular skidding this will freeze the state to one of the walking states, but once player.skidtime reaches 0 this will stop.

cmomx

fixed_t

Read+Write

The player's "conveyor" momx, i.e., the x-momentum from conveyor belts, wind, or currents.

cmomy

fixed_t

Read+Write

The player's "conveyor" momy, i.e., the y-momentum from conveyor belts, wind, or currents.

rmomx

fixed_t

Read+Write

The player's "real" momx, i.e., the x-momentum from the player themselves (player.mo.momx - player.cmomx). Modifying this will not change the player's actual x-momentum (modify player.mo.momx to do this).

rmomy

fixed_t

Read+Write

The player's "real" momy, i.e., the y-momentum from the player themselves (player.mo.momy - player.cmomy). Modifying this will not change the player's actual y-momentum (modify player.mo.momy to do this).

numboxes

INT16

Read+Write

Competition mode counter for the number of monitors the player has broken.

totalring

INT16

Read+Write

Competition mode counter for the number of rings the player has collected in total during the level. (When rings are lost this is not affected)

realtime

tic_t

Read+Write

The "real" time displayed in the player's HUD. In most gametypes, there is normally no difference between the values of this and leveltime (i.e., player.realtime == leveltime). However, in Race and Competition modes, the 4-second pre-timer means this variable has to start at zero 4 seconds after the level has loaded (i.e., player.realtime == leveltime - 4*TICRATE instead).

Note that when the player has finished the level, player.realtime will stop increasing, marking the time the player finished the level at. This final value is then used by the game for awards or bonuses, depending on the game mode or gametype:

The player's weapon delay timer; the player cannot shoot again until this has fallen back to 0. This is set whenever a player has fired a weapon to cap the player's firing rate.

tossdelay

INT32

Read+Write

The player's flag/emerald toss delay timer; the player cannot toss or collect flags/emeralds again until this has fallen back to 0. This is set whenever a player tosses a flag or emeralds, to prevent the player from accidentally collecting them again as soon as they are thrown.

starpostx

INT16

Read+Write

The saved x-position for the last checkpoint the player has touched, to be used when the player respawns at the checkpoint after dying.

starposty

INT16

Read+Write

The saved y-position for the last checkpoint the player has touched, to be used when the player respawns at the checkpoint after dying.

starpostz

INT16

Read+Write

The saved z-position for the last checkpoint the player has touched, to be used when the player respawns at the checkpoint after dying.

starpostnum

INT32

Read+Write

The saved starpost number for the last checkpoint the player has touched. Used to prevent the player from skipping starposts in Circuit mode maps, as they need to touch every single starpost number in order before completing a lap.

starposttime

tic_t

Read+Write

The saved level time for the last checkpoint the player has touched, to be used for resetting the level time to a particular time when the player respawns at a starpost after dying.

starpostangle

angle_t

Read+Write

The saved angle for the last checkpoint the player has touched, to be used when the player respawns at the checkpoint after dying.

angle_pos

angle_t

Read+Write

Used in NiGHTS mode for getting the current angle between the player and the axis the player is circling around.

old_angle_pos

angle_t

Read+Write

Used in NiGHTS mode for getting the previous angle between the player and the axis the player is circling around.

Used in NiGHTS mode as a pointer to the second of 2 axis transfer points the player is travelling between.

bumpertime

tic_t

Read+Write

The player's bumper timer, for when the player has just hit a NiGHTS Bumper. This will decrease until it reaches 0. This is used to prevent the player from continuously touching the same bumper, so the player can be sprung away from it.

flyangle

INT32

Read+Write

Used in NiGHTS mode to determine the player's current horizontal flying angle (values will range from 0 to 359). This is also used by CA_AIRDRILL to determine the thrust angle, eventually pointing downwards for falling down.

drilltimer

tic_t

Read+Write

Used in NiGHTS mode as a drilling timer, mainly for handling which drilling sound to use and when. This will decrease towards 0 whenever the player is drilling, but may not necessarily be at 0 when not drilling.

linkcount

INT32

Read+Write

Used in NiGHTS mode to count the number of links the player has achieved in a chain, so that more points are awarded the longer the link chain is. This resets back to 0 if player.linktimer gets to 0 before the next link however.

linktimer

tic_t

Read+Write

Used in NiGHTS mode as the link timer; the player must touch another hoop, ring or wing logo before player.linktimer reaches 0, otherwise the whole link chain will be broken.

anotherflyangle

INT32

Read+Write

Used in NiGHTS mode to determine the player's current vertical flying angle (values will range from 0 to 359). This also determines which set of states the player uses for flying or drilling.

nightstime

tic_t

Read+Write

Used in NiGHTS mode as the timer before the player returns back to normal gameplay from NiGHTS gameplay. This will decrease until it reaches 0.

drillmeter

INT32

Read+Write

Used in NiGHTS mode for the drilling meter, the amount of drilling power the player has left. For as long as this value isn't 0 the player will still be able to drill when NiGHTS Super Sonic.

drilldelay

tic_t

Read+Write

Used in NiGHTS mode as the drilling delay timer. This will decrease until it reaches 0. This is used to prevent the player from drilling again immediately after the player has stopped drilling.

bonustime

boolean

Read+Write

Used in NiGHTS mode to determine whether the player is in "bonus time" mode or not. This will be false normally, but will be true after the player has destroyed the capsule, allowing the player to be rewarded with more points for links before finishing the mare/level.

Used in NiGHTS mode to store the highest link count obtained by the player.

texttimer

UINT8

Read+Write

Used in NiGHTS mode as a timer before displayed text disappears from the screen. This will decrease until it reaches 0. This is also used to gradually fade away the text on the screen during the last half-second.

textvar

UINT8

Read+Write

Used in NiGHTS mode to determine the text displayed on the screen, for as long as player.texttimer has not reached 0:

4 = Ending bonuses: "RINGS: (rings)" "BONUS: (rings * 50)" "(score)"; in special stages "ORBS" replaces "RINGS"; in NiGHTS attack mode "* NEW RECORD *" may also be displayed if a new record was obtained.

lastsidehit

INT16

Read+Write

Used to store the number of the sidedef a character with CA_GLIDEANDCLIMB is currently climbing on. If not currently climbing this is set to -1.

lastlinehit

INT16

Read+Write

Used to store the number of the linedef a character with CA_GLIDEANDCLIMB is currently climbing on. If not currently climbing this is set to -1.

losstime

tic_t

Read+Write

The player's ring loss timer, used for determining how far spilled rings will be flung depending on how many times within a given period the player has been hit. This will decrease until it reaches 0, but whenever the player's rings are spilled this is increased by 10*TICRATE each time.

timeshit

UINT8

Read+Write

The counter for the number of times the player has been hurt by something; used for the Guard Bonus at the end of boss levels.

onconveyor

INT32

Read+Write

When the player is in a sector with either the Wind/Current or Conveyor Belt specials, player.onconveyor will be set to 2 or 4 respectively. player.onconveyor is then used to determine when and whether to set player.cmomx and player.cmomy to 0 or not.

Pointer to the player's current alternate view camera Object, this will be the viewpoint of the player for as long as player.awayviewtics has not reached 0.

awayviewtics

INT32

Read+Write

The player's alternate view camera timer. This will decrease until it reaches 0. Otherwise when player.awayviewtics is set, player.awayviewmobj is the viewpoint of the player. if player.awayviewmobj is not already set when player.awayviewtics is set, this will auto-set player.awayviewmobj to the player itself (player.mo).

awayviewaiming

angle_t

Read+Write

The player's alternate view camera vertical aiming angle. Similar to player.aiming except this applies to the alternative view point rather than the actual player's camera for when the camera switches back.

spectator

boolean

Read+Write

Returns true if the player is a spectator, otherwise this will return false.

2 – The player is a bot player currently controlled by Player 2 controls

jointime

tic_t

Read+Write

The amount of time the player has been in-game, and even counts up when the game is paused.

fovadd

fixed_t

Read+Write

The amount to add to the FOV in the OpenGL renderer. This is automatically corrected every tic so you will need to set this continually for any real effect.

Note: If not modified by Lua, this value is only calculated by the game locally if the OpenGL renderer is being used and GR_FOVCHANGE is turned on (otherwise, it is set to zero), and thus isn't network safe. Use at your own risk.

ticcmd_t

General

Accessibility

Read+Write

Allows custom variables

No

(Example uses will use cmd as the ticcmd_t variable here, with cmd.var to point to any of the ticcmd_t variables.)

ticcmd_t structure

Name

Type

Accessibility

Description/Misc notes

forwardmove

SINT8

Read+Write

Value related to forwards/backwards buttons; positive values move the player forward, negative values move the player backwards. Ranges from -50 to 50.

sidemove

SINT8

Read+Write

Value related to strafe left/right buttons; positive values move the player right, negative values move the player left. Ranges from -50 to 50.

angleturn

INT16

Read+Write

Value related to turn left/right buttons; to use as angle_t this needs to be shifted up by 16 bits (cmd.angleturn<<16 or cmd.angleturn*65536).

aiming

INT16

Read+Write

Value related to look up/down buttons; to use as angle_t this needs to be shifted up by 16 bits (cmd.aiming<<16 or cmd.aiming*65536).

A table containing all of the corresponding sound numbers for all skinsound slots for the skin, where SKSNAME is an integer that is expected to be one of the SKS* constants. For example, skins["sonic"].soundsid[SKSTHOK] returns sfx_thok, the default sound for the SKSTHOK skinsound slot; for custom characters who may have a custom sound set for any of the skin sounds, this returns the sound number for the custom sound instead.

SpawnState: The state that this type of 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_RUNSPAWNFUNCflag is set on the Object. If the SpawnState is called again after that, however, the action will be performed even without the flag.

DeathState: The state that Objects go to when they are destroyed, i.e., have no health points left. For regular enemies, this sequence of states should eventually point to S_NULL, which is used for Objects that have disappeared.

DeathSound: Usually played when the DeathState is executed. The action A_Scream is made specifically to call this sound.

speed

fixed_t

Read+Write

Speed: Usage depends on situation; can be just a regular number in some cases, other cases this needs to be a multiple of FRACUNIT

radius

fixed_t

Read+Write

Radius: The initial value for the radius variable for mobj_t. This may also be referenced when an Object's scale is modified.

height

fixed_t

Read+Write

Height: The initial value for the height variable for mobj_t. This may also be referenced when an Object's scale is modified.

dispoffset

INT32

Read+Write

DispOffset: Used to resolve ordering conflicts when drawing sprites that are in the same position in Software rendering. Sprites with a higher display offset are always drawn in front of sprites with a lower display offset. 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 Objects only use values up to 2, so anything above that will make the Object take precedence over all of SRB2's default Objects. For most Objects, this can be set to 0.

mass

INT32

Read+Write

Mass: Used for miscellaneous purposes and will be unused for most Objects. It has no relation to the heaviness of an Object.

damage

INT32

Read+Write

Damage: Used for miscellaneous purposes and will be unused for most Objects.

SpriteFrame: Frame number of the sprite used for the state; also contains full brightness/translucency information. (See tr_* and FF_* constants)

tics

INT32

Read+Write

Duration: Duration of the state, in tics. -1 is infinite, 0 is instantaneous.

action

function

Read+Write

Action: The action used by the state, run when an Object switches to the state. Can be set to a pre-existing action, or a custom one created using Lua, or be just nil if none is set. The return value is the function the action calls.

var1

INT32

Read+Write

Var1: The Var1 value built-in to be used by state.action, when an Object first switches to the state.

var2

INT32

Read+Write

Var2: The Var2 value built-in to be used by state.action, when an Object first switches to the state

Next: The next state number to go to after the state has finished being used. A state.nextstate of S_NULL will make the Object using the current state be removed from the map when about to switch to the new state.

sfxinfo_t

The name of the sound following the sfx_ prefix, e.g., S_sfx[sfx_thok].name would return "thok".

singular

boolean

Read+Write

Singular: Determines whether only one of the sound can be played at a time (true) or not (false).

priority

INT32

Read+Write

Priority: The priority of the sound, i.e., this determines how important it is to play this sound; if a sound with a higher priority is playing this sound will be drowned out, otherwise if vice versa this sound will drown out the other instead. Usually a value between 0 and 255.

flags

INT32

Read+Write

Flags: (Known as "pitch" in the source code) Sets/returns the sound flags set for the sound. (use SF_* constants, not to be confused with skin flags)

skinsound

INT32

Read-only

Skin sound id number; for sounds that are not changable by the skin this will be -1. (See SKS* constants)

The angle the map Thing is facing, in degrees. For some Object types this is used for other purposes; mapthing.angle can be a value from -32768 to 32767. For most purposes though this is usually a value from 0 to 359 – 0 is East, 90 is North, 180 is West and 270 is South.

type

UINT16

Read+Write

The map Thing number of the Object (or otherwise) to spawn with the map Thing. Does not include the multiples of 4096 added on by the map (see mapthing.extrainfo).

Returns true if the sector is valid (i.e., it exists), returns false otherwise.

floorheight

fixed_t

Read+Write

The sector's absolute floor height z-position in the map.

ceilingheight

fixed_t

Read+Write

The sector's absolute ceiling height z-position in the map.

floorpic

string

Read+Write

The name of the sector's floor flat texture.

ceilingpic

string

Read+Write

The name of the sector's ceiling flat texture.

lightlevel

INT16

Read+Write

The brightness level of the sector. This should be a value between 0 and 255.

special

INT16

Read+Write

The total of the sector's sector special values in all 4 sections given to the sector (section1 + section2<<4 + section3<<8 + section4<<12). Use GetSecSpecial(sector.special, n) to get the sector special set in a particular section n.

tag

INT16

Read+Write

The tag number set for the sector; due to the way this is set up, all tags from 32768 to 65535 (seen when using map editors) are in fact -32768 to -1, although either can be used for assigning a new tag value (it will be automatically converted to the latter version anyway). Changing the value of sector.tag will have the same effect as changing it with Linedef type 409 or Linedef type 410.

thinglist()

function

Read-only

To be used in an iterator function, e.g., for mobj in sector.thinglist(). This iterates through all the Objects within the sector, returning a mobj_t variable for use within the loop's contents.

The tag number set for the linedef; due to the way this is set up, all tags from 32768 to 65535 (seen when using map editors) are in fact -32768 to -1, although either can be used for assigning a new tag value (it will be automatically converted to the latter version anyway).

sidenum[i]

UINT16 array

Read-only

This is a small table containing the sidedef numbers for both the front sidedef (line.sidenum[0]) and the back sidedef if one exists (line.sidenum[1]). To get the sidedef userdata for these, use sides[line.sidenum[i]], i being either 0 (front) or 1 (back). To check if either sidedef is valid, use line.sidenum[i].valid, which will return either true or false.

The previous FOF in the target sector's FOF list. (This is nil if the FOF is the first in the list)

alpha

INT32

Read+Write

The FOF's alpha/translucency level. This should be a value between 1 and 256.

pslope_t

General

Accessibility

Read+Write

Allows custom variables

No

(Example uses will use slope as the pslope_t variable here, with slope.var to point to any of the pslope_t variables.)

pslope_t structure

Name

Type

Accessibility

Description/Misc notes

valid

boolean

Read-only

Returns true if the slope is valid (i.e., it exists), returns false otherwise.

o

vector3_t

Userdata: Read+WriteUserdata variables: Read-only

The slope's origin vector.

For sector-based slopes, the origin's X/Y position is placed a fixed horizontal distance (known as the "extent" internally) away from the middle point of the linedef that defines the slope, at an angle of xydistance. The Z position is set as the un-sloped height of the floor or ceiling plane the slope is created for.

Currently, the only way to modify this variable is by assigning to it a custom table with x, y and z fields, such as below:

slope.o={"x"=1*FRACUNIT,"y"=2*FRACUNIT,"z"=3*FRACUNIT}-- change the origin's position to (1, 2, 3)

Unless SL_NODYNAMIC is set in the slope's flags, the origin's Z position (slope.o.z) will be automatically corrected accordingly with the sector heights or vertices used to create the slope. This means that slope.o.z cannot be modified by Lua unless the flag is not set.

d

vector2_t

Read-only

The slope's 2D (X,Y) direction vector. Used to determine distance from the origin in 2D mapspace. The values are normalised, i.e.: they are equivalent to a thrust of FRACUNIT, though in the opposite direction to the angle xydirection.

zdelta

fixed_t

Read+Write

The rate at which Z changes based on distance from the origin.

For sector-based slopes, this is calculated as the un-sloped height of the sector plane on the other side of the linedef that defines the slope's plane, minus the un-sloped height of the slope's own plane, and divided by the slope's "extent" value (see o for explanation). (i.e.: zdelta = (plane2-plane1)/ extent)

Unless SL_NODYNAMIC is set in the slope's flags, this value will be automatically corrected accordingly with the sector heights or vertices used to create the slope. This means that this value cannot be modified by Lua unless the flag is not set. Otherwise, modifying this value will also automatically update zangle and normal accordingly.

normal

vector3_t

Read-only

The normal vector of the slope's plane. It intended to point upward out of the plane, but it instead follows the direction of it (only true for sector slopes?[confirm? – discuss]). Currently unused.

Unless SL_NODYNAMIC is set in the slope's flags, this value will be automatically corrected accordingly with the sector heights or vertices used to create the slope.

zangle

fixed_t

Read+Write

The vertical angle of the slope's plane, going up from the ground (i.e. a "flat" slope plane would have a zangle of 0).

Unless SL_NODYNAMIC is set in the slope's flags, this value will be automatically corrected accordingly with the sector heights or vertices used to create the slope. This means that this value cannot be modified by Lua unless the flag is not set. Otherwise, modifying this value will also automatically update zdelta and normal accordingly.

ANGLE_90 and ANGLE_270 are not accepted as values for this variable; the game will print an error message if you attempt to assign them to it.

xydirection

angle_t

Read+Write

The horizontal angle of the slope's plane.

Modifying this value will also automatically update d and normal accordingly.

Current subsector the camera is in. To obtain the sector the camera is in, use camera.subsector.sector.

floorz

fixed_t

Read-only

Absolute "floor" position for the camera, i.e the height that it considers to be the floor. This will change if the camera is for instance above a solid FOF, or has just moved to a different sector.

ceilingz

fixed_t

Read-only

Absolute "ceiling" position for the camera, i.e the height that it considers to be the ceiling. This will change if the camera is for instance below a solid FOF, or has just moved to a different sector.

radius

fixed_t

Read-only

The current radius of the camera. By default this is 20*FRACUNIT, but will automatically scale accordingly with the corresponding player if their scale was modified.

height

fixed_t

Read-only

The current height of the camera. By default this is 16*FRACUNIT, but will automatically scale accordingly with the corresponding player if their scale was modified.

momx

fixed_t

Read-only

The camera's current x-axis momentum. +ve values shift the camera to the East, -ve values to the West.

momy

fixed_t

Read-only

The camera's current y-axis momentum. +ve values shift the camera to the North, -ve values to the South.