Increment the current damage level by the specified amount.

Parameters:

amount

value to add to current damage level

Apply an impulse to the object.

Parameters:

	pos	world position of the impulse
	vec	impulse momentum (velocity * mass)

Returns:

true

Repair damage by the specified amount.

Note that the damage level is only reduced by repairRate per tick, so it may take several ticks for the total repair to complete.

Parameters:

amount

total repair value (subtracted from damage level over time)

Check if this object can cloak.

Returns:

true

Note:

Not implemented as it always returns true.

Change one of the materials on the shape.

This method changes materials per mapTo with others. The material that is being replaced is mapped to unmapped_mat as a part of this transition.

Note:

Warning, right now this only sort of works. It doesn't do a live update like it should.

Parameters:

	mapTo	the name of the material target to remap (from getTargetName)
	oldMat	the old Material that was mapped
	newMat	the new Material to map

Example:

// remap the first material in the shape
%mapTo = %obj.getTargetName( 0 );
%obj.changeMaterial( %mapTo, 0, MyMaterial );

Destroy an animation thread, which prevents it from playing.

Parameters:

slot

thread slot to destroy

Returns:

true if successful, false if failed

See also:

playThread

Print a list of visible and hidden meshes in the shape to the console for debugging purposes.

Note:

Only in a SHIPPING build.

Get the position at which the AI should stand to repair things.

If the shape defines a node called "AIRepairNode", this method will return the current world position of that node, otherwise "0 0 0".

Returns:

the AI repair position

Returns the vertical field of view in degrees for this object if used as a camera.

Returns:

current FOV as defined in ShapeBaseData::cameraDefaultFov

Get the client (if any) that controls this object.

The controlling client is the one that will send moves to us to act on.

Returns:

the ID of the controlling GameConnection, or 0 if this object is not controlled by any client.

See also:

GameConnection

Get the object (if any) that controls this object.

Returns:

the ID of the controlling ShapeBase object, or 0 if this object is not controlled by another object.

Get the damage flash level.

Returns:

flash level

See also:

setDamageFlash

Get the object's current damage level.

Returns:

damage level

See also:

setDamageLevel()

Get the object's current damage level as a percentage of maxDamage.

Returns:

damageLevel / datablock.maxDamage

See also:

setDamageLevel()

Get the object's damage state.

Returns:

the damage state; one of "Enabled", "Disabled", "Destroyed"

See also:

setDamageState()

Returns the default vertical field of view in degrees for this object if used as a camera.

Returns:

Default FOV

Get the object's current energy level.

Returns:

energy level

See also:

setEnergyLevel()

Get the object's current energy level as a percentage of maxEnergy.

Returns:

energyLevel / datablock.maxEnergy

See also:

setEnergyLevel()

Get the position of the 'eye' for this object.

If the object model has a node called 'eye', this method will return that node's current world position, otherwise it will return the object's current world position.

Returns:

the eye position for this object

See also:

getEyeVector

getEyeTransform

Get the 'eye' transform for this object.

If the object model has a node called 'eye', this method will return that node's current transform, otherwise it will return the object's current transform.

Returns:

the eye transform for this object

See also:

getEyeVector

getEyePoint

Get the forward direction of the 'eye' for this object.

If the object model has a node called 'eye', this method will return that node's current forward direction vector, otherwise it will return the object's current forward direction vector.

Returns:

the eye vector for this object

See also:

getEyePoint

getEyeTransform

Get the alt trigger state of the Image mounted in the specified slot.

Parameters:

slot

Image slot to query

Returns:

the Image's current alt trigger state

Get the ammo state of the Image mounted in the specified slot.

Parameters:

slot

Image slot to query

Returns:

the Image's current ammo state

Get the generic trigger state of the Image mounted in the specified slot.

Parameters:

	slot	Image slot to query
	trigger	Generic trigger number

Returns:

the Image's current generic trigger state

Get the loaded state of the Image mounted in the specified slot.

Parameters:

slot

Image slot to query

Returns:

the Image's current loaded state

Get the script animation prefix of the Image mounted in the specified slot.

Parameters:

slot

Image slot to query

Returns:

the Image's current script animation prefix

Get the skin tag ID for the Image mounted in the specified slot.

Parameters:

slot

Image slot to query

Returns:

the skinTag value passed to mountImage when the image was mounted

Get the name of the current state of the Image in the specified slot.

Parameters:

slot

Image slot to query

Returns:

name of the current Image state, or "Error" if slot is invalid

Get the target state of the Image mounted in the specified slot.

Parameters:

slot

Image slot to query

Returns:

the Image's current target state

Get the trigger state of the Image mounted in the specified slot.

Parameters:

slot

Image slot to query

Returns:

the Image's current trigger state

Get the world position this object is looking at.

Casts a ray from the eye and returns information about what the ray hits.

Parameters:

	distance	maximum distance of the raycast
	typeMask	typeMask of objects to include for raycast collision testing

Returns:

look-at information as "Object HitX HitY HitZ [Material]" or empty string for no hit

Example:

%lookat = %obj.getLookAtPoint();
echo( "Looking at: " @ getWords( %lookat, 1, 3 ) );

Get the object's maxDamage level.

Returns:

datablock.maxDamage

Get the model filename used by this shape.

Returns:

the shape filename

Get the Image mounted in the specified slot.

Parameters:

slot

Image slot to query

Returns:

ID of the ShapeBaseImageData datablock mounted in the slot, or 0 if no Image is mounted there.

Get the first slot the given datablock is mounted to on this object.

Parameters:

image

ShapeBaseImageData datablock to query

Returns:

index of the first slot the Image is mounted in, or -1 if the Image is not mounted in any slot on this object.

Get the muzzle position of the Image mounted in the specified slot.

If the Image shape contains a node called 'muzzlePoint', then the muzzle position is the position of that node in world space. If no such node is specified, the slot's mount node is used instead.

Parameters:

slot

Image slot to query

Returns:

the muzzle position, or "0 0 0" if the slot is invalid

Get the muzzle vector of the Image mounted in the specified slot.

If the Image shape contains a node called 'muzzlePoint', then the muzzle vector is the forward direction vector of that node's transform in world space. If no such node is specified, the slot's mount node is used instead.

If the correctMuzzleVector flag (correctMuzzleVectorTP in 3rd person) is set in the Image, the muzzle vector is computed to point at whatever object is right in front of the object's 'eye' node.

Parameters:

slot

Image slot to query

Returns:

the muzzle vector, or "0 1 0" if the slot is invalid

Get the Image that will be mounted next in the specified slot.

Calling mountImage when an Image is already mounted does one of two things:

1. Mount the new Image immediately, the old Image is discarded and whatever state it was in is ignored.
2. If the current Image state does not allow Image changes, the new Image is marked as pending, and will not be mounted until the current state completes. eg. if the user changes weapons, you may wish to ensure that the current weapon firing state plays to completion first.

This command retrieves the ID of the pending Image (2nd case above).

Parameters:

slot

Image slot to query

Returns:

ID of the pending ShapeBaseImageData datablock, or 0 if none.

Get the current recharge rate.

Returns:

the recharge rate (per tick)

See also:

setRechargeRate()

Get the per-tick repair amount.

Returns:

the current value to be subtracted from damage level each tick

See also:

setRepairRate

Get the name of the shape.

Note:

This is the name of the shape object that is sent to the client, not the DTS or DAE model filename.

Returns:

the name of the shape

See also:

setShapeName()

Get the name of the skin applied to this shape.

Returns:

the name of the skin

See also:

skin

setSkinName()

Get the world transform of the specified mount slot.

Parameters:

slot

Image slot to query

Returns:

the mount transform

Get the number of materials in the shape.

Returns:

the number of materials in the shape.

See also:

getTargetName()

Get the name of the indexed shape material.

Parameters:

index

index of the material to get (valid range is 0 - getTargetCount()-1).

Returns:

the name of the indexed material.

See also:

getTargetCount()

Get the object's current velocity.

Returns:

the current velocity

Reimplemented in Camera.

Get the white-out level.

Returns:

white-out level

See also:

setWhiteOut

Check if the given state exists on the mounted Image.

Parameters:

	slot	Image slot to query
	state	Image state to check for

Returns:

true if the Image has the requested state defined.

Check if this object is cloaked.

Returns:

true if cloaked, false if not

See also:

setCloaked()

Check if the object is in the Destroyed damage state.

Returns:

true if damage state is "Destroyed", false if not

See also:

isDisabled()

isEnabled()

Check if the object is in the Disabled or Destroyed damage state.

Returns:

true if damage state is not "Enabled", false if it is

See also:

isDestroyed()

isEnabled()

Check if the object is in the Enabled damage state.

Returns:

true if damage state is "Enabled", false if not

See also:

isDestroyed()

isDisabled()

Check if the object is hidden.

Returns:

true if the object is hidden, false if visible.

Check if the current Image state is firing.

Parameters:

slot

Image slot to query

Returns:

true if the current Image state in this slot has the 'stateFire' flag set.

Check if the given datablock is mounted to any slot on this object.

Parameters:

image

ShapeBaseImageData datablock to query

Returns:

true if the Image is mounted to any slot, false otherwise.

Mount a new Image.

Parameters:

	image	the Image to mount
	slot	Image slot to mount into (valid range is 0 - 3)
	loaded	initial loaded state for the Image
	skinTag	tagged string to reskin the mounted Image

Returns:

true if successful, false if failed

Example:

%player.mountImage( PistolImage, 1 );
%player.mountImage( CrossbowImage, 0, false );
%player.mountImage( RocketLauncherImage, 0, true, 'blue' );

See also:

unmountImage()

getMountedImage()

getPendingImage()

isImageMounted()

Pause an animation thread.

If restarted using playThread, the animation will resume from the paused position.

Parameters:

slot

thread slot to stop

Returns:

true if successful, false if failed

See also:

playThread

Attach a sound to this shape and start playing it.

Parameters:

	slot	Audio slot index for the sound (valid range is 0 - 3)
	track	SFXTrack to play

Returns:

true if the sound was attached successfully, false if failed

See also:

stopAudio()

Start a new animation thread, or restart one that has been paused or stopped.

Parameters:

	slot	thread slot to play. Valid range is 0 - 3)
	name	name of the animation sequence to play in this slot. If not specified, the paused or stopped thread in this slot will be resumed.

Returns:

true if successful, false if failed

Example:

%obj.playThread( 0, "ambient" );      // Play the ambient sequence in slot 0
%obj.setThreadTimeScale( 0, 0.5 );    // Play at half-speed
%obj.pauseThread( 0 );                // Pause the sequence
%obj.playThread( 0 );                 // Resume playback
%obj.playThread( 0, "spin" );         // Replace the sequence in slot 0

See also:

pauseThread()

stopThread()

setThreadDir()

setThreadTimeScale()

destroyThread()

Set the hidden state on all the shape meshes.

This allows you to hide all meshes in the shape, for example, and then only enable a few.

Parameters:

hide

new hidden state for all meshes

Set the vertical field of view in degrees for this object if used as a camera.

Parameters:

fov

new FOV value

Set the cloaked state of this object.

When an object is cloaked it is not rendered.

Parameters:

cloak

true to cloak the object, false to uncloak

See also:

isCloaked()

Set the damage flash level.

Damage flash may be used as a postfx effect to flash the screen when the client is damaged.

Note:

Relies on the flash postFx.

Parameters:

level

flash level (0-1)

See also:

getDamageFlash()

Set the object's current damage level.

Parameters:

level

new damage level

See also:

getDamageLevel()

getDamagePercent()

Set the object's damage state.

Parameters:

state

should be one of "Enabled", "Disabled", "Destroyed"

Returns:

true if successful, false if failed

See also:

getDamageState()

Set the damage direction vector.

Currently this is only used to initialise the explosion if this object is blown up.

Parameters:

vec

damage direction vector

Example:

%obj.setDamageVector( "0 0 1" );

Set this object's current energy level.

Parameters:

level

new energy level

See also:

getEnergyLevel()

getEnergyPercent()

Add or remove this object from the scene.

When removed from the scene, the object will not be processed or rendered.

Parameters:

show

False to hide the object, true to re-show it

Reimplemented from SimObject.

Set the alt trigger state of the Image mounted in the specified slot.

Parameters:

	slot	Image slot to modify
	state	new alt trigger state for the Image

Returns:

the Image's new alt trigger state

Set the ammo state of the Image mounted in the specified slot.

Parameters:

	slot	Image slot to modify
	state	new ammo state for the Image

Returns:

the Image's new ammo state

Set the generic trigger state of the Image mounted in the specified slot.

Parameters:

	slot	Image slot to modify
	trigger	Generic trigger number
	state	new generic trigger state for the Image

Returns:

the Image's new generic trigger state or -1 if there was a problem.

Set the loaded state of the Image mounted in the specified slot.

Parameters:

	slot	Image slot to modify
	state	new loaded state for the Image

Returns:

the Image's new loaded state

Set the script animation prefix for the Image mounted in the specified slot.

This is used to further modify the prefix used when deciding which animation sequence to play while this image is mounted.

Parameters:

	slot	Image slot to modify
	prefix	The prefix applied to the image

Set the target state of the Image mounted in the specified slot.

Parameters:

	slot	Image slot to modify
	state	new target state for the Image

Returns:

the Image's new target state

Set the trigger state of the Image mounted in the specified slot.

Parameters:

	slot	Image slot to modify
	state	new trigger state for the Image

Returns:

the Image's new trigger state

Setup the invincible effect.

This effect is used for HUD feedback to the user that they are invincible.

Note:

Currently not implemented

Parameters:

	time	duration in seconds for the invincible effect
	speed	speed at which the invincible effect progresses

Set the hidden state on the named shape mesh.

Parameters:

	name	name of the mesh to hide/show
	hide	new hidden state for the mesh

Set the recharge rate.

The recharge rate is added to the object's current energy level each tick, up to the maxEnergy level set in the ShapeBaseData datablock.

Parameters:

rate

the recharge rate (per tick)

See also:

getRechargeRate()

Set amount to repair damage by each tick.

Note that this value is separate to the repairRate field in ShapeBaseData. This value will be subtracted from the damage level each tick, whereas the ShapeBaseData field limits how much of the applyRepair value is subtracted each tick. Both repair types can be active at the same time.

Parameters:

rate

value to subtract from damage level each tick (must be > 0)

See also:

getRepairRate()

Set the name of this shape.

Note:

This is the name of the shape object that is sent to the client, not the DTS or DAE model filename.

Parameters:

name

new name for the shape

See also:

getShapeName()

Apply a new skin to this shape.

'Skinning' the shape effectively renames the material targets, allowing different materials to be used on different instances of the same model.

Parameters:

name

name of the skin to apply

See also:

skin

getSkinName()

Set the playback direction of an animation thread.

Parameters:

	slot	thread slot to modify
	fwd	true to play the animation forwards, false to play backwards

Returns:

true if successful, false if failed

See also:

playThread()

Set the position within an animation thread.

Parameters:

	slot	thread slot to modify
	pos	position within thread

Returns:

true if successful, false if failed

See also:

playThread

Set the playback time scale of an animation thread.

Parameters:

	slot	thread slot to modify
	scale	new thread time scale (1=normal speed, 0.5=half speed etc)

Returns:

true if successful, false if failed

See also:

playThread

Set the object's velocity.

Parameters:

vel

new velocity for the object

Returns:

true

Set the white-out level.

White-out may be used as a postfx effect to brighten the screen in response to a game event.

Note:

Relies on the flash postFx.

Parameters:

level

flash level (0-1)

See also:

getWhiteOut()

Fade the object in or out without removing it from the scene.

A faded out object is still in the scene and can still be collided with, so if you want to disable collisions for this shape after it fades out use setHidden to temporarily remove this shape from the scene.

Note:

Items have the ability to light their surroundings. When an Item with an active light is fading out, the light it emits is correspondingly reduced until it goes out. Likewise, when the item fades in, the light is turned-up till it reaches it's normal brightntess.

Parameters:

	time	duration of the fade effect in ms
	delay	delay in ms before the fade effect begins
	fadeOut	true to fade-out to invisible, false to fade-in to full visibility

Stop a sound started with playAudio.

Parameters:

slot

audio slot index (started with playAudio)

Returns:

true if the sound was stopped successfully, false if failed

See also:

playAudio()

Stop an animation thread.

If restarted using playThread, the animation will start from the beginning again.

Parameters:

slot

thread slot to stop

Returns:

true if successful, false if failed

See also:

playThread

Unmount the mounted Image in the specified slot.

Parameters:

slot

Image slot to unmount

Returns:

true if successful, false if failed

See also:

mountImage()

Called on the server when the client has requested a FOV change.

When the client requests that its field of view should be changed (because they want to use a sniper scope, for example) this new FOV needs to be validated by the server. This method is called if it exists (it is optional) to validate the requested FOV, and modify it if necessary. This could be as simple as checking that the FOV falls within a correct range, to making sure that the FOV matches the capabilities of the current weapon.

Following this method, ShapeBase ensures that the given FOV still falls within the datablock's cameraMinFov and cameraMaxFov. If that is good enough for your purposes, then you do not need to define the validateCameraFov() callback for your ShapeBase.

Parameters:

fov

The FOV that has been requested by the client.

Returns:

The FOV as validated by the server.

See also:

ShapeBaseData

Is this object AI controlled.

If True then this object is considered AI controlled and not player controlled.

The skin applied to the shape.

'Skinning' the shape effectively renames the material targets, allowing different materials to be used on different instances of the same model. Using getSkinName() and setSkinName() is equivalent to reading and writing the skin field directly.

Any material targets that start with the old skin name have that part of the name replaced with the new skin name. The initial old skin name is "base". For example, if a new skin of "blue" was applied to a model that had material targets base_body and face, the new targets would be blue_body and face. Note that face was not renamed since it did not start with the old skin name of "base".

To support models that do not use the default "base" naming convention, you can also specify the part of the name to replace in the skin field itself. For example, if a model had a material target called shapemat, we could apply a new skin "shape=blue", and the material target would be renamed to bluemat (note "shape" has been replaced with "blue").

Multiple skin updates can also be applied at the same time by separating them with a semicolon. For example: "base=blue;face=happy_face".

Material targets are only renamed if an existing Material maps to that name, or if there is a diffuse texture in the model folder with the same name as the new target.