Contents

Console Objects Fields and Methods Quick Reference Part 10


This quick reference guide was taken directly out of The Game Programmer's Guide to Torque by Edward Maurina. It's an outstanding resource - a must for anyone wanting to get serious about programming in Torque.

ScriptBase Cntd.




Console Methods Cntd.


Re-Skinning

getSkinName setSkinName


getSkinName()

Purpose
Use the getSkinName method to determine which skin this shape is currently using.

Returns
Returns a string containing the name of the skin this shape is using, or if this shape is not set up to use multiple skins, it returns the NULL string.

Notes
Shapes must be skinned with specially named set of textures in order to enable re-skinning. Please see GPGT volume 1 for more details.

See Also
setSkinName



setSkinName( skinName )

Purpose
Use the setSkinName method to change the current skin for this shape.

Syntax
skinName
– A string containing a valid skin name, as set up in the shapes set of skins. If this skin name does not match any of the textures used by this object, the object will not change skins.

Returns
No return value.

Notes
Shapes must be skinned with specially named set of textures in order to enable re-skinning. Please see GPGT volume 1 for more details.

See Also
getSkinName


Damage

applyDamage applyRepair getAIRepairPoint getDamageLevel
getDamagePercent getDamageState isEnabled isDisabled
isDestroyed setDamageLevel setDamageState setDamageVector
setInvincibleMode setRepairRate


applyDamage( damage )

Purpose
Use the applyDamage method to apply the specified amount of damage to this shape.

Syntax
damage
– A floating-point value specifying a positive amount of damage to apply to this shape.

Returns
No return value.

See Also
applyRepair, getDamageLevel



applyRepair( repair )

Purpose
Use the applyRepair method to apply repair ammount or repair to shape.

Syntax
repair
– A positive number of repair points to apply to this shape.

Returns
No return value.

Notes
Before this will work, the self-repair must at least temporarily be disabled, by calling setRepairRate with an argument of 0.

See Also
applyDamage, getDamageLevel, setRepairRate



getAIRepairPoint()

Purpose
Use the getAIRepairPoint method to get the the position of a specially named mesh node: "AIRepairNode". It is used as a helper when deciding where an AI should 'stand' to repair this shape.

Returns
Returns a three-element floating-point vector containing the position of a specially named mesh node: "AIRepairNode". It is used as a helper when deciding where an AI should 'stand' to repair this shape.

Notes
If this node is not present in the shape, the position of the shape's centroid will be returned instead.



getDamageLevel()

Purpose
Use the getDamageLevel method to determine the current level of damage this shape has sustained.

Returns
Returns a floating point value between 0.0 and maxDamage (as specified in the shape's datablock). 0.0 is equal to 'no damage'.

See Also
applyDamage, applyRepair, getDamagePercent, getDamageState



getDamagePercent()

Purpose
Use the getDamagePercent method to get a relative percentage of damage for this shape, where the equation for this precent is currentDamage / maxDamage.

Returns
Returns a floating point value between 0.0 (0%) and 1.0 (100%).

See Also
applyDamage, applyRepair, getDamageLevel, getDamageState



getDamageState()

Purpose
Use the getDamageState method to determine this shape's current damage state.

Returns
Returns a string specifying the current damage state for this shape:

Enabled – Damage < Disabled Level
Disabled – Disabled Level less than or equal to Damage < Destroyed Level
Destroyed – DestroyedLevel less than or equal to Damage

See Also
applyDamage, applyRepair, getDamageLevel, getDamagePercent



isEnabled()

Purpose
Use the isEnabled method to determine if this shape's damage is less than its disabled level.

Returns
Returns true as long as this shape's damage level is less than its disabled level.

See Also
getDamageLevel, getDamagePercent, getDamageState, isDisabled



isDisabled()

Purpose
Use the isDisabled method to determine if this shape's damage is greater than or equal to its disabled level.

Returns
Returns true as long as this shape's damage level is greather than or equal to its disabled level.

See Also
getDamageLevel, getDamagePercent, getDamageState, isEnabled



isDestroyed()

Purpose
Use the isDestroyed method to determine if this shape's damage is greater than or equal to its destroyed level.

Returns
Returns true as long as this shape's damage level is greather than or equal to its destoyed level.

See Also
getDamageLevel, getDamagePercent, getDamageState, isEnabled, isDisabled



setDamageLevel( level )

Purpose
Use the setDamageLevel method to set the shape's damage to a new level.

Syntax
level
– A floating-point value between 0.0 and inf.0, representing this shape's new damage level.

Returns
No return value.

Notes
If level is greater than this shape's maxDamage, the damage level will be capped at maxDamage. Setting this value will also update the shape's damage state.

See Also
getDamageLevel, getDamagePercent, getDamageState



setDamageState( state )

Purpose
Use the setDamageState method to change this shape's damage state.

Syntax
state
– A string containing one of the allowed damage states: enabled, disabled, or destroyed.

Returns
Returns true on success, false otherwise.

Notes
Setting this value will NOT affect the shape's damage level, furthermore the next time this shape's damage level is updated, the shape's damage state will change to match it.

See Also
setDamageLevel



setDamageVector( damageOrigin )

Purpose
Use the setDamageVector method to establish the direction from which to be applied damage will be coming. This will subsequently be used to correctly setup any explosion or debris scatter that occcurs as a result of the damage.

Syntax
damageOrigin
– An XYZ vector specifying the direcion from which some to be applied damage originated.

Returns
No return value.

Notes
Generally, this should be done before applying damage, but it can be done afterward. However results may vary.

See Also
applyDamage



setInvincibleMode( time , speed )

Purpose
Use the setInvincibleMode method to temporarily make this shape invincible. i.e. Not able to take damage. While the player is invincible, the screen will flicker blue with a varying rate and a varying intensity.

Syntax
time
– A floating-point value specifying the time in seconds for this shape to remain invincible.
speed – A floating-point value between 0.0 and 1.0 controlling the rate at which the blue flickering effect occurs.

Returns
No return value.

Notes
The flickering effect is used to indicated to a player that his (or her) avatar is invincible. Furthermore, this flicker rate will change and the flicker will become increasingly translucent as the time elapses. If speed set to 1.0, the flickering is a bit obscene. Generally, lower values are nicer.


Damage Flashes & Whiteouts

getDamageFlash getWhiteOut setDamageFlash setWhiteOut


getDamageFlash()

Purpose
Use the getDamageFlash method to get the current level of damage flash occuring, if any.

Returns
Returns a floating-point value between 0.0 and 1.0 specifying the current level of damage flash occuring.

Notes
A damage flash is a translucent red overlay that can be used to inform the player that their avatar has taken damage. When a damage flas is applied, it will fade slowly over time. This method merely lets us know how far along that fade has progressed.

See Also
setDamageFlash



getWhiteOut( )

Purpose
Use the getWhiteOut method to get the current level of whiteout occuring, if any.

Returns
Returns a floating-point value between 0.0 and 1.0 specifying the current level of whiteout occuring.

Notes
A whiteout is a translucent white overlay that can be used to temporarily blind the player. Usually this is done as a response to the player viewing a bright light of some sort, but it must be done manually if we want this effect.

See Also
setWhiteOut



setDamageFlash( level )

Purpose
Use the setDamageFlash method to set the current damage flash level. When this level is > 0.0 the screen is rendered with an an additive red overlay, which is limited to 76% regardless of level. The value of level is auto-decremented over a few seconds.

Syntax
level
– A floating-point value specifying the level of damage flash to apply. This value can be between 0.0 (0%) and 1.0 (100%).

Returns
No return value.

Notes
A damage flash is a translucent red overlay that can be used to inform the player that their avatar has taken damage.

See Also
getDamageFlash



setWhiteOut( level )

Purpose
Use the setWhiteOut method to set the current whiteout level. When this level is > 0.0 the screen is rendered with an additive white overlay. At 1.0, rendering is saturated and the screen is entirely white. i.e. it is whited out. The value of level is auto-decremented over a few seconds.

Syntax
level
– A floating-point value specifying the level of whiteout to apply. This value can be between 0.0 (0%) and 1.0 (100%).

Returns
No return value.

Notes
A whiteout is a translucent white overlay that can be used to temporarily blind the player.

See Also
getWhiteOut


Energy

getRechargeRate getEnergyLevel getEnergyPercent setRechargeRate
setEnergyLevel


getRechargeRate()

Purpose
Use the getRechargeRate method to get the current rechargeRate setting for this shape.

Returns
Returns a floating-point value between 0.0 and inf.0, equivalent to the number of energy points this shape will auto-recharge every tick, where a tick is by default 1/32 of a second.

See Also
setRechargeRate



getEnergyLevel()

Purpose
Use the getEnergyLevel method to return the current energy level of this shape.

Returns
Returns a floating-point value between 0.0 and maxEnergy.

See Also
getEnergyPercent, setEnergyPercent



getEnergyPercent()

Purpose
Use the getEnergyPercent method to return the current energy level as a percentage.

Returns
Returns a floating-point value between 0.0 (0%) and 1.0 (100%), where this percentage is calculated as: currentEnergy / maxEnergy.

See Also
getEnergyPercent, setEnergyLevel



setRechargeRate( rate )

Purpose
Use the setRechargeRate method to enable auto-recharing at rate points per tick.

Syntax
rate
– A floating-point value between 0.0 and inf.0 equivalent to the number of energy points to recharge this shape by each tick, where a tick is by default 1/32 of a second.

Returns
No return value.

Notes
Having auto-rechage enabled does not prevent manual application of recharge values, as is the case with auto-repair and manual repairs.

See Also
getRechargeRate



setEnergyLevel( level )

Purpose
Use the setEnergyLevel method to set the shape's current energy level to a value between 0.0 and maxEnergy.

Syntax
level
– A floating-point value between 0.0 and maxEnergy.

Returns
No return value.

Notes
If level is greater than maxEnergy, maxEnergy is used instead.

See Also
getEnergyLevel


Eye Transform and Vectors

getEyePoint getEyeTransform getEyeVector


getEyePoint()

Purpose
Use the getEyePoint method to get the positions of this shape's 'eye' node.

Returns
If this shape has a node in it's mesh named 'eye', the position of that node will be returned as a three-element floating-point vector. If no 'eye' node is present in this shape's mesh, the position of the shape's centroid is returned instead.

See Also
getEyeTransform, getEyeVector



getEyeTransform()

Purpose
Use the getEyeTransform method to get the transform of this shape's 'eye' node.

Returns
Returns a transform, "posX posY posZ rotX rotY rotZ rotTheta", representative of a shape's eye postion, orientation vector, and the rotation about that vector in radians. If not 'eye' node is present in this shape's mesh, the transform of the shape itself is returned.

See Also
getEyePoint, getEyeVector



getEyeVector()

Purpose
Use the getEyeVector method to retrieve a vector representing the direction the shape's 'eye' node is facing.

Returns
Returns a vector representing the direction a shape is looking. If this shape's mesh contains no 'eye' node, the shape's forward vector will be returned instead.

Notes
Unless this shape is being observed through (i.e. the camera is hooked up to this shape and using its transforms for viewing), this will default to getForwardVector().

See Also
getEyePoint, getEyeTransform


Image/Weapons Specifics

getImageAmmo getImageLoaded getImageSkinTag getImageState
getImageTrigger getMuzzlePoint getMuzzleVector getPendingImage
isImageFiring setImageAmmo getImageLoaded setImageTrigger


getImageAmmo( slot )

Purpose
Use the getImageAmmo method to determine if the image mounted at slot has ammo.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Returns
Returns true if there is an image mounted at slot and it has ammo, false otherwise.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

See Also
setImageAmmo



getImageLoaded( slot )

Purpose
Use the getImageLoaded method to determine if the image mounted at slot is loaded.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

Returns
Returns true if there is an image mounted at slot and it is loaded, false otherwise.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

See Also
setImageLoaded



getImageSkinTag( slot )

Purpose
Use the getImageSkinTag method to get the skin tag for the image mounted at slot on this shape.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Returns
Returns an integer representing the tag number for the texture the image mounted at slot is using.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.
Skin tags are selected when mounting an image to a shape.

See Also
mountImage



getImageState( slot )

Purpose
Use the getImageState method to determine state name that an image mounted in slot is at. i.e. If an image is mounted in slot, what state is its state-machine currently in?

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Returns
Returns a string representing the state name that the image mounted at slot is currently at. If there is not state machine defined for the image at slot, or if there no image at slot, or if slot is > 7, this method returns “Error”.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.



getImageTrigger( slot )

Purpose
Use the getImageTrigger method to get the trigger value for the image mounted at slot.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Returns
Returns a boolean value specifying wether the trigger for the image at slot is active (true), or inactive (false). If no image is mounted at slot or if slot is > 7, this method returns 0.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

See Also
setImageTrigger



getMuzzlePoint( slot )

Purpose
Use the getMuzzlePoint method to get the position of the 'muzzlePoint' node for the image mounted at slot.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

Returns
If an image is mounted at slot, and if it specifies the node 'muzzlePoint', this method will return the XYZ position of the node. If there is an image mounted at slot, and that image does not contain a 'muzzlePoint' node, this method returns the position of the image's centroid. In all other cases, this method returns “0 0 0”.

See Also
getMuzzleVector



getMuzzleVector( slot )

Purpose
Use the getMuzzleVector method to get the direction the 'muzzlePoint' node for the image mounted at slot is pointing.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Returns
If an image is mounted at slot, and if it specifies the node 'muzzlePoint', this method will return the XYZ pointing vector of the node. If there is an image mounted at slot, and that image does not contain a 'muzzlePoint' node, this method returns the equivalent of a forward vector for the weapon itself. In all other cases, this method returns “0 0 0”.

The returned vector can be modified by setting the image.correctMuzzleVector field. If this value is set to true, the vector will point from its origin to the position the player's eye is looking, otherwise, it will point in the true direction the weapon or weapon's muzzlePoint is facing, which may not be exactly where the player is looking.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

See Also
getMuzzlePoint



getPendingImage( slot )

Purpose
Use the getPendingImage method to determine if any images are pending for the specified slot.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Returns
Returns 0 if no images are pending or an integer represending the image datablock ID if an image is pending.

Notes
A pending image is an image that is waiting to mount a slot but is prevented from doing so by the presence of another 'blocking' image.

Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.



isImageFiring( slot )

Purpose
Use the isImageFiring method to determine if this image's state machine is currently in a state with the stateFire field set to true.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.

Returns
Returns true if this image's state machine is currently in a state with the stateFire field set to true, false otherwise.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

See Also
getImageState



setImageAmmo( slot , hasAmmo )

Purpose
Use the setImageAmmo method to give an image in slot ammo, or to remove ammo from an image in slot.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.
hasAmmo – A boolean value. If set to true, this image is set has having ammo, otherwise it is set as not having ammo.

Returns
Returns true on success, and false on failure.

Notes
Weapons support both 'ammo' and 'loaded' as distinct concepts.

Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

See Also
setImageLoaded



setImageLoaded( slot , loaded )

Purpose
Use the setImageLoaded method to set an image in slot as loaded or unloaded.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.
hasAmmo – A boolean value. If set to true, this image is set has being loaded, otherwise it is set as not being loaded.

Returns
Returns true on success, and false on failure.

Notes
Weapons support both 'ammo' and 'loaded' as distinct concepts.

Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.

See Also
setImageAmmo



setImageTrigger( slot , triggered )

Purpose
Use the setImageTrigger method to set the trigger state for an image in slot.

Syntax
slot
– An integer value between 0 and 7 representing a mount slot on this shape.
triggered – A boolean value. If set to true, this image is triggered (firing), otherwise it is un-triggered (not firing).

Returns
Returns true on success, and false on failure.

Notes
Do not confuse slots with mount nodes. A shape can have up to 32 mount nodes, but only has eight mount slots. Mount nodes are points on the mesh used by the shape while slots are used to track how many objects and images are mounted to a shape.


Table of Contents || Part 1 || Part 2 || Part 3 || Part 4 || Part 5 || Part 6 || Part 7 || Part 8 || Part 9 || Part 11 || Part 12 || Part 13 || Part 14 || Part 15