CObjects are objects, accessible to Lua, which have a counterpart in the C++ side of the engine.

They do not have allocated memory in the Lua side, and therefore cannot store any information.

Reference: CObject

• ColorizableObject
• FXObject
• MapObject
• PropertyObject

Attaches one object to another at a specified spot.

void CObject:Attach(object child, int spot) object child : object to be attached

int spot : spot numeric index

Changes the object's entity.

void CObject:ChangeEntity(string entity) string entity : the entity name

Clear the object's enumeration flags.

void CObject:ClearEnumFlags(int mask) int mask : mask containing the flags to be cleared.

Example:

obj:ClearEnumFlags(const.efVisible)
-- the object is now invisible

Clear the object's game flags.

void CObject:ClearGameFlags(int mask) int mask : mask containing the flags to be cleared.

Example:

obj:ClearGameFlags(const.gofAlwaysRenderable)
-- the object wont be drawn when outside the camera view

Counts object attaches based on certain criteria

int CObject:CountAttaches([string classes], [function filter], ...) string classes : an optional comma separated list of classes, to filter the attached objects. If not provided, all attaches shall be processed.

function filter : an optional function to test if an attach is to be counted. Any parameter provided after the callback, would be passed to it when called.

returns int : the count of matched attaches.

Example:

local count = obj:CountAttaches("foo, bar", function(obj) return not obj:GetVisible() end)
-- 'count' equals the number of the invisible attaches form the classes "foo" and "bar"

Destroys object attaches based on certain criteria

int CObject:DestroyAttaches([string classes], [function filter], ...) string classes : an optional comma separated list of classes, to filter the attached objects. If not provided, all attaches shall be processed.

function filter : an optional function to test if an attach is to be deleted. Any parameter provided after the callback, would be passed to it when called.

returns int : the count of matched attaches.

Example:

obj:DestroyAttaches("foo, bar", function(obj) return not obj:GetVisible() end)
-- all invisible attaches form the classes "foo" and "bar" are now destroyed

Detach an attached object from its parent.

void CObject:Detach()

Removes the object from the map. The object's position wont be valid any more.

void CObject:DetachFromMap()

Calls a function callback for each attached object from a list of classes

int CObject:ForEachAttach([string classes], function callback, ...) string classes : an optional comma separated list of classes, to filter the attached objects. If not provided, all attaches shall be processed.

function callback : a function to call for each attach. Any parameter provided after the callback, would be passed to it when called.

returns int : the count of matched attaches.

Example:

obj:ForEachAttach("foo, bar", function(obj, visible) obj:SetVisible(visible) end, false)
-- all attaches form the classes "foo" and "bar" are now invisible

Computes the linear acceleration and the time needed to reach a target position with a given final speed.

int, int CObject:GetAccelerationAndTime(point pos, int speed, [int speed0])

int, int CObject:GetAccelerationAndTime(int x, int y, int z, int speed, [int speed0]) point pos : the target position as a point

int x, y, z : the target position as coordinates

int speed : the desired final speed

int speed0 : the initial speed (optional, the current speed by default)

returns int, int : the acceleration and the time

Example:

local accel, time = obj:GetAccelerationAndTime(pos, 0)
obj:SetAcceleration(accel)
obj:SetPos(pos, time)
-- the object will slowly stop at the target position

Returns the final rotation angle of an object.

The visual angle is different from the final angle, only when the object is still rotating.

int CObject:GetAngle() returns int : final rotation angle.

Collects the attaches from given class(es). If no class is specified, then all attached objects shall be collected.

table CObject:GetAttaches([string class])

table CObject:GetAttaches([table classes]) string class : an optional class name, to filter the attached objects.

table classes : an optional class list, to filter the attached objects.

returns table : a list containing the matched attaches, or nil if none has been found.

Example:

local attaches = obj:GetAttaches("foo")
-- 'attaches' containts all attached objects form the class "foo"

Returns the rotation axis of an object.

point CObject:GetAxis() returns point : rotation axis vector as point

Returns the object's class flags. All object flags are represented as a single bit (0 or 1).

int CObject:GetClassFlags([int mask]) int mask : optional flag mask, used to check if the object contains specific flags.

returns int : the object's enumeration flags, masked with the mask if provided.

Example:

if obj:GetClassFlags(const.cfDecal) ~= 0 then
-- the object is a decal
end

Computes the distance from the object's final position to another position.

int CObject:GetDist(object obj)

int CObject:GetDist(box bx)

int CObject:GetDist(point pos) object obj : check distance to an object

box bx : check distance to a box

point pos : check distance to a position

returns int : the computed distance

Returns the bounding box of the current state of the object with mirroring applied, but without applying object's position, scale and orientation.

box CObject:GetEntityBBox() returns box : the bounding box of the entity.

Returns the object's enumeration flags. All object flags are represented as a single bit (0 or 1).

int CObject:GetEnumFlags([int mask]) int mask : optional flag mask, used to check if the object contains specific flags.

returns int : the object's enumeration flags, masked with the mask if provided.

Example:

if obj:GetEnumFlags(const.efVisible) ~= 0 then
-- the object is visible
end

Returns an index of a spot from a given type with no attaches

int CObject:GetFreeSpot(string spot) string spot : spot type name

returns int : the spot index, -1 if not found.

Returns the object's game flags. All object flags are represented as a single bit (0 or 1).

int CObject:GetGameFlags([int mask]) int mask : optional flag mask, used to check if the object contains specific flags.

returns int : the object's game flags, masked with the mask if provided.

Example:

if obj:GetGameFlags(const.gofAlwaysRenderable) ~= 0 then
-- the object is drawn even when outside the camera view
end

Returns the maximim object's entity radius in any of its states (animations).

int CObject:GetMaxRadius() returns int : object's max radius.

Returns the index of the nearest spot to a specified location

int CObject:GetNearestSpot(string spot, point pos)

int CObject:GetNearestSpot(string spot, object obj) string spot : spot type name

point pos : location as point

object obj : location as object

returns int : the spot index, -1 if not found.

Returns the number of valid states (animations) for current object.

int CObject:GetNumStates() returns int : number of states

Returns the object's bounding box in its current state (animation).

box CObject:GetObjectBBox() returns box : the object's bounding box.

Returns the parent object (if the current object is attached).

object CObject:GetParent() returns object : the parent object if any, nil otherwise

Returns the final map position of an object .

The visual position is different from the final position, only when the object is still moving.

point CObject:GetPos() returns point : final map position.

Same as GetPos, but returns the coordinates of the position.

int, int, int CObject:GetPosXYZ() returns int, int, int : coordinates of the final map position.

Returns the object's entity radius in its current state (animation). For objects without entity, the radius can be specified as a member 'radius' in the class definition.

int CObject:GetRadius() returns int : object's radius.

Returns the index of a random spot from a given type

int CObject:GetRandomSpot(string spot) string spot : spot type name

returns int : the spot index, -1 if not found.

Computes the world position of a point relative to an object.

point CObject:GetRelativePoint(point pos)

point CObject:GetRelativePoint(int x, int y, int z) point pos : position relative to the object as a point.

int x, y, z : position relative to the object as coordinates.

Example:

local pos = obj:GetRelativePoint(0, 0, 10*guim)
-- 'pos' is located 10 meters above the object

Returns the object's orientation as roll, pitch and yaw angles.

int CObject:GetRollPitchYaw([int time_delta]) int time_delta : optional time interval in the future, thus enabling to get a future orientation.

returns int, int, int : the object's roll, pitch and yaw angle.

Returns the object's scale (disregarding parent hierarchy).

int CObject:GetScale() returns int : the object's scale in percent (100% is the default).

Returns the rotation of the specified spot around it's rotation axis.

angle axis CObject:GetSpotAxisAngle(int spot) int spot : spot index.

returns point axis : the spot rotation axis vector as point.

returns int angle : the spot rotation.

Returns the first spot index from a given spot type for an object

int, int CObject:GetSpotBeginIndex(string spot) string spot : spot name

returns int : the spot index, -1 if not found.

Returns the last spot index from a given spot type for an object

int, int CObject:GetSpotEndIndex(string spot) string spot : spot name

returns int : the spot index, -1 if not found.

Returns the final world position of the specified spot.

point CObject:GetSpotPos(int spot) int spot : spot index.

returns point : the spot position.

Same as GetSpotPos but the returned values are the position's coordinates.

int, int, int CObject:GetSpotPosXYZ(int spot) int spot : spot index.

returns int, int, int : the coordinates of the spot position.

Returns the first and the last spot indexes from a given spot type for an object

int, int CObject:GetSpotRange(string spot) string spot : spot name

returns int, int : the spot indexes, -1 if not found.

Gets the object's current state index (animation index).

int CObject:GetState() returns int : the state index

Returns the visual rotation angle of an object.

The visual angle is different from the final angle, only when the object is still rotating.

int CObject:GetVisualAngle() returns int : visual rotation angle.

Computes the distance from the object's visual position to another position.

int CObject:GetVisualDist(object obj)

int CObject:GetVisualDist(box bx)

int CObject:GetVisualDist(point pos) object obj : check distance to an object

box bx : check distance to a box

point pos : check distance to a position

returns int : the computed distance

Returns the visual position of an object.

The visual position is different from the final position, only when the objects is still moving.

point CObject:GetVisualPos([int time_delta = 0], [bool extrapolate = false]) int time_delta : optional parameter to specify a different moment than now.

bool extrapolate : if true and if the provided time exceeds the movement time, avoids the clamping.

returns point : visual position.

Same as GetVisualPos, but the returned position is only two dimensional.

point CObject:GetVisualPos2D([int time], [bool extrapolate = false]) returns point : visual 2D position.

Same as GetVisualPos, but the returned values are the object coordinates.

int, int, int CObject:GetVisualPosXYZ([int time_delta = 0], [bool extrapolate = false]) returns int, int, int : visual coordinates X, Y and Z.

Returns the object's current visual scale (disregarding parent hierarchy).

int CObject:GetVisualScale(int delta = 0) returns int : the object's scale in percent (100% is the default).

Returns the object's world current visual scale (considering parent hierarchy).

int CObject:GetVisualWorldScale(int delta = 0) returns int : the object's world scale in percent (100% is the default).

Same as GetVisualPos, but returns only the Z coordinate of the visual map position.

int CObject:GetVisualZ([int time_delta = 0], [bool extrapolate = false]) returns int : Z coordinate of the visual map position.

Returns the object's world scale (considering parent hierarchy).

int CObject:GetWorldScale() returns int : the object's world scale in percent (100% is the default).

Same as GetPos, but returns only the Z coordinate of the final map position, or nil if on the terrain.

int CObject:GetZ() returns int : Z coordinate of the final map position.

Checks if the object's entity has specific surfaces.

bool CObject:HasAllSurfaces(int mask, [bool hierarchical]) int mask : A mask of the surfaces in question. See the 'EntitySurfaces' global for a list of surfaces and their masks.

bool hierarchical : Checks the attached objects too.

returns bool : Returns true if the entity has all of those surfaces.

Checks if the object's entity has specific surfaces.

bool CObject:HasAnySurfaces(int mask, [bool hierarchical]) int mask : A mask of the surfaces in question. See the 'EntitySurfaces' global for a list of surfaces and their masks.

bool hierarchical : Checks the attached objects too.

returns bool : Returns true if the entity has any of those surfaces.

Checks if an object has an entity.

bool CObject:HasEntity() returns bool : true if entity is present.

Checks if an object has a given spot type.

bool CObject:HasSpot(string spot) string spot : the spot name to be checked

returns bool : true if the spot is present.

Checks if the object's entity has a given state (animation).

bool CObject:HasState(string name)

bool CObject:HasState(int index) string name : the state name to check for

int index : the state index to check for

returns bool : Returns true if the state is present

Intersects object's bounding box in its current state/animation with a given box or point.

int CObject:IntersectBBox(box/point, b2D = false) returns int/bool : intersection result.

Returns if the current phase is the last anim phase

int CObject:IsAnimEnd([int channel = 1]) int channel : optional animation channel

returns bool : true if the current phase is the last anim phase

Checks if any of the source points can reach any of the approach points.

The function makes a single path finding call. In order to work correctly, all pass tunnels have to be symetrical (no one way tunnels).

bool CObject:IsReachableFrom(table sources, int pfclass = 0, int restrict_dist = 150*guim) table sources : Table with points or objects or a single object

int pfclass : Optional pfclass

int restrict_dist : Optional restrict distance

Returns the value of the sound mute flag for an object.

void CObject:IsSoundMuted()

Checks if an object is present on the map

bool CObject:IsValidPos() returns bool : returns true, if the object has a position on the map.

Checks if the object position has a valid Z coordinate. Objects with invalid Z are always drawn on the terrain surface.

bool CObject:IsValidZ() returns bool : returns true, if the object has a valid Z coordinate.

Similar to SetState, but waits until the state animation is played before returning.

void CObject:PlayState(string name, [int count = 1, int flags = 0, int crossfade = -1])

void CObject:PlayState(int index, [int count = 1, int flags = 0, int crossfade = -1]) string name : the state name to check for

string index : the state index to check for

int count : optional count of animation replays (for looped animations only)

int flags : optional animation control flags (see object documentation for details)

int crossfade : optional animation crossfade time (see object documentation for details)

Called when a cobject having a Lua reference is being destroyed. The method isn't overriden by child classes, but instead all implementations are called starting from the topmost parent.

void CObject:RemoveLuaReference()

Sets linear acceleration as easing function when moving the object.

void CObject:SetAcceleration(int accel) int accel : the linear acceleration value

Smoothly changes the object's rotation angle over the specified time.

void CObject:SetAngle(int angle, [int time = 0]) int angle : the new angle (in minutes, 1 degree equals 60 minutes)

int time : the time (ms) to change the axis (optional)

Advance the object's animation to a specific moment (phase). For nonlooping animations, the phase is clamped between 0 and the normal duration of the animation (without considering any speed modifications).

void CObject:SetAnimPhase(int channel, int phase) int channel : animation channel index (first channel is 1)

int phase : the animation time to set.

Example:

local duration = obj:SetState("step")
obj:SetAnimPhase(1, duration - 1)
-- the object animation is forced to advance to its last frame

Sets the new object's animation channel speed.

The channel speed is a property of the animation channel alone and doesn't affect the animations played on other channels.

void CObject:SetAnimSpeed(int channel, int speed, [int time = 0]) int channel : animation channel (the first channel is 1)

int speed : the new speed to set in promilles

int time : the time we want the animation to reach smoothly the given speed (optional)

Sets the new object's animation speed modifier.

The speed modifier is a property of the object and affects all animation channels.

void CObject:SetAnimSpeedModifier(int speed) int speed : the new speed modifier to set in promilles

Specifies the angle for the rotation offset when the object is attached.

void CObject:SetAttachAngle(int angle) int angle : attach rotation angle

Specifies the axis for the rotation offset when the object is attached.

void CObject:SetAttachAxis(point axis)

void CObject:SetAttachAxis(int dx, int dy, int dz) point axis : attach rotation axis vector as point

int dx, dy, dz : the axis vector as coordinates

Specifies a linear offset when the object is attached.

void CObject:SetAttachOffset(point offset)

void CObject:SetAttachOffset(int dx, int dy, int dz) point offset : offset vector from the spot position as point

int dx, dy, dz : the offset vector as coordinates

Smoothly changes the object's rotation axis over the specified time.

void CObject:SetAxis(point axis, [int time = 0])

void CObject:SetAxis(int dx, int dy, int dz, [int time = 0]) point axis : the new rotation axis vector as point

int dx, dy, dz : the new rotation axis vector as coordinates

int time : the time (ms) to change the axis (optional).

Smoothly turns the object to the given axis and angle for the specified time. This method ensures proper interpolation avoiding discontinuities.

void CObject:SetAxisAngle(point axis, int angle, [int time = 0])

void CObject:SetAxisAngle(int axis_x, int axis_y, int axis_z, int angle, [int time = 0])

void CObject:SetAxisAngle(object other, [int time = 0])

Modifies the colorization of the entire object.

void CObject:SetColorModifier(int color, [int time = 0, bool recursive = false]) int color : the modification color in integer format. Each color component ranges between 0 and 255. For values above 100 the color component's value is being increased, while for values below, it's being reduced. To disable any modification, use RGB(100, 100, 100).

int time : optional parameter allowing to make the modification smoothly over an interval of time.

bool recursive : optional parameter indicating to set the color to all the attaches too.

Example:

obj:SetColorModifier(RGB(200, 100, 50))
-- the object is now with increased red color, reduced blue color and unchanged green
obj:SetColorModifier(RGB(100, 100, 100))
-- the object's true colors are now restored

Specifies object's material properties.

void CObject:SetColorizationMaterial(int idx, int color, int roughness, int metallic)

void CObject:SetColorizationMaterial(object other) int idx : colorization index, depends on the number of colorization masks available in the object's entity

int color : the material color to be used, in RGB format represented as an unsigned integer (one byte per color component).

int roughness : the material roughness, represented as an integer between -128 and 127

int metallic : the metallic degree, represented as an integer between -128 and 127

object other : copy the colorization from another object

Changes the object's dust visuals. Has an effect only if the entity has a dust mask.

void CObject:SetDust(int value, int material, int color) int value : the degree of dust, ranging from 0 to 255

int material : material index, can be 0 (exterior) or 1 (interior)

Sets the object's enumeration flags.

void CObject:SetEnumFlags(int mask) int mask : mask containing the flags to be set.

Example:

obj:SetEnumFlags(const.efVisible)
-- the object is now visible

Sets the object's game flags.

Example:

obj:SetGameFlags(const.gofAlwaysRenderable)
-- the object is now drawn even when outside the camera view

void CObject:SetGameFlags(int mask) int mask : mask containing the flags to be set.

Sets gravity acceleration as easing function when moving the object.

void CObject:SetGravity([int gravity = 980]) int gravity : the gravity acceleration value (optional)

Specifies the the object entity should be mirrored.

void CObject:SetMirrored(bool mirrored) bool mirrored : true if mirrored

Sets the current object opacity.

void CObject:SetOpacity(int opacity, [int time = 0, bool recursive = false]) int opacity : 0 for full transparency; 100 for full opacity

int time : time for smooth transition (optional)

int recursive : if true, apply to attached objects too (optional)

Smoothly changes the object's position over the specified time.

The map position of the object is changed immediately, but its visual position will change over the given interval of time.

void CObject:SetPos(point pos, [int time = 0])

void CObject:SetPos(int x, int y, int z, [int time = 0]) point pos : the new position as a point

int x, y, z : the new position as three coordinates.

int time : the time (ms) to change the position (optional).

Smoothly moves and turns the object to the given pos, axis and angle for the specified time. It is better to use this method instead of invoking the interpolations separately.

void CObject:SetPosAxisAngle(point pos, point axis, int angle, [int time = 0])

void CObject:SetPosAxisAngle(int pos_x, int pos_y, int pos_z, int axis_x, int axis_y, int axis_z, int angle, [int time = 0])

void CObject:SetPosAxisAngle(object other, [int time = 0])

Sets the object's orientation via roll, pitch and yaw angles.

void CObject:SetRollPitchYaw(int roll, int pitch, int yaw, [int time_delta]) int roll : roll angle (Rotation around the object's front-to-back axis)

int pitch : pitch angle (Rotation around the object's side-to-side axis)

int yaw : yaw angle (Rotation around the object's vertical axis)

int time_delta : optional time interval in the future, thus enabling smooth interpolation from the current orientation.

Sets the current self illumination modulation.

void CObject:SetSIModulation(int modulation) int modulation : 0 for no self illumination; 100 for max self illumination

Changes the object's scale.

void CObject:SetScale(int scale) int scale : the object's scale in percent (100% is the default).

int time : interpolation delta (0 by default).

Associates a sound to be played from this object.

void CObject:SetSound(string sound, [string type, int volume, int crossfade, bool looping]) string sound : a sound name (sound bank) or a sound filename.

string type : a sound type name, indicating that a sound file is provided, instead of a sound name.

int volume : forces the volume of the sound between 0 and 1000 (the sound bank volume is used by default).

int crossfade : optional cross-fade time if changing the sound state.

bool looping : specifies if the sound should be looping (uses the sound bank flag by default).

Sets or resets the sound mute flag for an object.

void CObject:SetSoundMute(int volume, bool bMute) bool bMute : mutes the sounds from the object if set

Changes the sound volume for an object.

void CObject:SetSoundVolume(int volume, [int time = 0]) int volume : specifies the volume of the sound between 0 and 1000.

int time : optional time for smooth change.

Changes the object's state (animation).

int CObject:SetState(string name, [int flags = 0, int crossfade = -1, int speed = 1000, bool change_only])

int CObject:SetState(int index, [int flags = 0, int crossfade = -1, int speed = 1000, bool change_only]) string name : the state name to check for

string index : the state index to check for

int flags : optional animation control flags (see object documentation for details)

int crossfade : optional animation crossfade time (see object documentation for details)

int speed : optional animation speed in promilles

bool change_only : will early-out if the state is already the requested one

Stops the sound of an object.

void CObject:StopSound([int time = 0]) int time : optional time for smoothly muting the sound.

Returns remaining time to the end of currently played animation of the object (the result is depending on the current animation speed).

int CObject:TimeToAnimEnd([int channel = 1]) int channel : optional animation channel

returns int : the time remaining

Returns the bounding box of an entity in a given state.

box GetEntityBBox(string entity, string state)

box GetEntityBBox(string entity, int state) string entity : entity name

string state : state name

int state : state idx

returns box : the bounding box of the entity.

Returns the number of valid states (animations) for a given entity.

int GetNumStates(string entity) string entity : the entity name

returns int : number of states

Returns the first spot index from a given spot type for an entity in a given state

int, int GetSpotBeginIndex(string entity, string state, string spot)

int, int GetSpotBeginIndex(string entity, int state, string spot) string entity : entity name

string state : state name

int state : state index

string spot : spot name

returns int : the spot index, -1 if not found.

Returns the last spot index from a given spot type for an entity in a given state

int, int GetSpotEndIndex(string entity, string state, string spot)

int, int GetSpotEndIndex(string entity, int state, string spot) string entity : entity name

string state : state name

int state : state index

string spot : spot name

returns int : the spot index, -1 if not found.

Returns the first and the last spot indexes from a given spot type for an entity in a given state

int, int GetSpotRange(string entity, string state, string spot)

int, int GetSpotRange(string entity, int state, string spot) string entity : entity name

string state : state name

int state : state index

string spot : spot name

returns int, int : the spot indexes, -1 if not found.

Returns the topmost parent, if attached, or the object itself otherwise.

object GetTopmostParent(object obj [, string class = false]) object obj : the object

string class : optional class name as filter

returns object : the topmost parent

Checks if an entity has specific surfaces.

bool HasAllSurfaces(string entity, int mask) string entity : The entity name.

int mask : A mask of the surfaces in question. See the 'EntitySurfaces' global for a list of surfaces and their masks.

returns bool : Returns true if the entity has all of those surfaces.

Checks if an entity has specific surfaces.

bool HasAnySurfaces(string entity, int mask) string entity : The entity name.

int mask : A mask of the surfaces in question. See the 'EntitySurfaces' global for a list of surfaces and their masks.

returns bool : Returns true if the entity has any of those surfaces.

Checks if an entity has a given spot type in a specified state.

bool HasSpot(string entity, string state, string spot) string entity : the entity name

#param string state - the state to check

string spot : the spot name to be checked

returns bool : true if the spot is present.

Checks if an entity has a given state (animation).

bool HasState(string entity, string name)

bool HasState(string entity, int index) string entity : the entity name

string name : the state name to check for

int index : the state index to check for

returns bool : Returns true if the state is present

Returns if the given param is an object in the process of being destroyed.

bool IsBeingDestructed(object obj) object obj : the object to be tested

returns bool : true if the object is being destroyed

Returns if the given param is a valid, non yet destroyed object.

bool IsValid(object obj) object obj : the object to be tested

returns bool : true if the object is valid

(insert footer.md.html here)