ShapeBase

bool isAIControlled 

string skin 

Public Functions

applyDamage(float amount)

Increment the current damage level by the specified amount.

Parameters:

amount

value to add to current damage level

applyImpulse(Point3F pos, Point3F vec)

Apply an impulse to the object.

Parameters:

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

applyRepair(float amount)

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)

blowUp()

Explodes an object into pieces.

canCloak()

Check if this object can cloak.

note:

Not implemented as it always returns true.

changeMaterial(string mapTo, Material oldMat, Material newMat)

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

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

destroyThread(int slot)

Destroy an animation thread, which prevents it from playing.

Parameters:

slot	thread slot to destroy

dumpMeshVisibility()

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

note:

Only in a SHIPPING build.

getAIRepairPoint()

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".

getCameraFov()

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

getControllingClient()

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

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

getControllingObject()

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

getDamageFlash()

Get the damage flash level.

getDamageLevel()

Get the object's current damage level.

getDamagePercent()

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

getDamageState()

Get the object's damage state.

getDefaultCameraFov()

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

getEnergyLevel()

Get the object's current energy level.

getEnergyPercent()

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

getEyePoint()

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.

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.

getEyeVector()

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.

getImageAltTrigger(int slot)

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

Parameters:

slot	Image slot to query

getImageAmmo(int slot)

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

Parameters:

slot	Image slot to query

getImageGenericTrigger(int slot, int trigger)

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

Parameters:

slot	Image slot to query
trigger	Generic trigger number

getImageLoaded(int slot)

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

Parameters:

slot	Image slot to query

getImageScriptAnimPrefix(int slot)

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

Parameters:

slot	Image slot to query

getImageSkinTag(int slot)

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

Parameters:

slot	Image slot to query

getImageState(int slot)

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

Parameters:

slot	Image slot to query

getImageTarget(int slot)

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

Parameters:

slot	Image slot to query

getImageTrigger(int slot)

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

Parameters:

slot	Image slot to query

getLookAtPoint(float distance, uint typeMask)

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

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

getMaxDamage()

Get the object's maxDamage level.

getModelFile()

Get the model filename used by this shape.

getMountedImage(int slot)

Get the Image mounted in the specified slot.

Parameters:

slot	Image slot to query

getMountSlot(ShapeBaseImageData image)

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

Parameters:

image

ShapeBaseImageData datablock to query

getMuzzlePoint(int slot)

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

getMuzzleVector(int slot)

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

getPendingImage(int slot)

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

getRechargeRate()

Get the current recharge rate.

getRepairRate()

Get the per-tick repair amount.

getShapeName()

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.

getSkinName()

Get the name of the skin applied to this shape.

getSlotTransform(int slot)

Get the world transform of the specified mount slot.

Parameters:

slot	Image slot to query

getTargetCount()

Get the number of materials in the shape.

getTargetName(int index)

Get the name of the indexed shape material.

Parameters:

index

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

getVelocity()

Get the object's current velocity.

getWhiteOut()

Get the white-out level.

hasImageState(int slot, string state)

Check if the given state exists on the mounted Image.

Parameters:

slot	Image slot to query
state	Image state to check for

isCloaked()

Check if this object is cloaked.

isDestroyed()

Check if the object is in the Destroyed damage state.

isDisabled()

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

isEnabled()

Check if the object is in the Enabled damage state.

isHidden()

Check if the object is hidden.

isImageFiring(int slot)

Check if the current Image state is firing.

Parameters:

slot	Image slot to query

isImageMounted(ShapeBaseImageData image)

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

Parameters:

image

ShapeBaseImageData datablock to query

mountImage(ShapeBaseImageData image, int slot, bool loaded, string skinTag)

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

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

pauseThread(int slot)

Pause an animation thread.

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

slot	thread slot to stop

playAudio(int slot, SFXTrack track)

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

playThread(int slot, string name)

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.

%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

setAllMeshesHidden(bool hide)

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

setCameraFov(float fov)

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

Parameters:

fov	new FOV value

setCloaked(bool cloak)

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

setDamageFlash(float level)

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)

setDamageLevel(float level)

Set the object's current damage level.

Parameters:

level

new damage level

setDamageState(string state)

Set the object's damage state.

Parameters:

state

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

setDamageVector(Point3F vec)

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

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

setEnergyLevel(float level)

Set this object's current energy level.

Parameters:

level

new energy level

setHidden(bool show)

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

setImageAltTrigger(int slot, bool state)

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

setImageAmmo(int slot, bool 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

setImageGenericTrigger(int slot, int trigger, bool 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

setImageLoaded(int slot, bool state)

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

setImageScriptAnimPrefix(int slot, string prefix)

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

setImageTarget(int slot, bool state)

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

setImageTrigger(int slot, bool 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

setMeshHidden(string name, bool hide)

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

setRechargeRate(float rate)

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)

setRepairRate(float rate)

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)

setShapeName(string name)

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

setSkinName(string name)

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

setThreadDir(int slot, bool fwd)

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

setThreadPosition(int slot, float pos)

Set the position within an animation thread.

Parameters:

slot	thread slot to modify
pos	position within thread

setThreadTimeScale(int slot, float scale)

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)

setVelocity(Point3F vel)

Set the object's velocity.

Parameters:

vel	new velocity for the object

setWhiteOut(float level)

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)

startFade(int time, int delay, bool fadeOut)

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

stopAudio(int slot)

Stop a sound started with playAudio.

Parameters:

slot	audio slot index (started with playAudio)

stopThread(int slot)

Stop an animation thread.

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

slot	thread slot to stop

unmountImage(int slot)

Unmount the mounted Image in the specified slot.

Parameters:

slot	Image slot to unmount