ShapeBase¶
A scriptable, renderable shape.
- Inherit:
- GameBase
Description¶
A scriptable, renderable shape.
ShapeBase is the renderable shape from which most of the scriptable, game objects are derived, including the Player, Vehicle and Item classes. ShapeBase provides collision detection, audio channels, and animation as well as damage (and damage states), energy, and the ability to mount Images and objects.
ShapeBase objects are not normally instantiated in the scene; derived classes such as Player, WheeledVehicle, and, StaticShape are used instead. But ShapeBase (and the associated datablock, ShapeBaseData) may be used to provide functionality common to all derived objects.
A ShapeBase object consists of a DTS or DAE shape file. This file has the following requirements:
Nodes
Sequences Indicating Condition
Detail Levels
Control Object¶
Generally in a Torque game, each client is in control of a single game object (such as a Player in an FPS game, or a WheeledVehicle in a racing game). In a game where the client has control over multiple objects (such as units in an RTS), the control object may be the Camera that determines the client’s view of the world (although in general, the client’s camera object does not need to be the same as the control object).
The object controlled by the client is important for several reasons:
Energy/Damage¶
ShapeBase includes basic enery and damage systems that may be used by derived classes as required. For example, the Player class uses energy to determine whether the character is capabable of running and jumping, which can be used to mimic the character getting tired and having to rest before continuing. The Player class also uses the damage system PlayerData::onDestroyed callback to trigger a death animation. The Vehicle classes use the current damage level to trigger particle emitters, so a vehicle could progressively generate more smoke as it becomes more damaged.
ShapeBase also includes parameters to ‘blow up’ the object when it is Destroyed (damage level above ShapeBaseData::destroyedLevel). Blowing up an object can generate an explosion and debris, as well as exclude the object from rendering.
Parameters to control the object’s energy and damage functionality can be found in the ShapeBaseData datablock.
Methods¶
-
void
ShapeBase::
applyDamage
(float amount)¶ Increment the current damage level by the specified amount.
Parameters: amount – value to add to current damage level
-
bool
ShapeBase::
applyImpulse
(Point3F pos, Point3F vec)¶ Apply an impulse to the object.
Parameters: - pos – world position of the impulse
- vec – impulse momentum (velocity * mass)
Returns: true
-
void
ShapeBase::
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)
-
void
ShapeBase::
blowUp
()¶ Explodes an object into pieces.
-
bool
ShapeBase::
canCloak
()¶ Check if this object can cloak.
Returns: true
-
void
ShapeBase::
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.
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 );
-
bool
ShapeBase::
destroyThread
(int slot)¶ Destroy an animation thread, which prevents it from playing.
Parameters: slot – thread slot to destroy Returns: true if successful, false if failed
-
void
ShapeBase::
dumpMeshVisibility
()¶ Print a list of visible and hidden meshes in the shape to the console for debugging purposes.
-
Point3F
ShapeBase::
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”.
Returns: the AI repair position
-
float
ShapeBase::
getCameraFov
()¶ Returns the vertical field of view in degrees for this object if used as a camera.
Returns: ShapeBaseData::cameraDefaultFov
-
int
ShapeBase::
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.
Returns: , or 0 if this object is not controlled by any client.
-
int
ShapeBase::
getControllingObject
()¶ Get the object (if any) that controls this object.
Returns: object, or 0 if this object is not controlled by another object.
-
float
ShapeBase::
getDamageFlash
()¶ Get the damage flash level.
Returns: flash level
-
float
ShapeBase::
getDamageLevel
()¶ Get the object’s current damage level.
Returns: damage level
-
float
ShapeBase::
getDamagePercent
()¶ Get the object’s current damage level as a percentage of maxDamage.
Returns: damageLevel / datablock.maxDamage
-
string
ShapeBase::
getDamageState
()¶ Get the object’s damage state.
Returns: the damage state; one of “Enabled”, “Disabled”, “Destroyed”
-
float
ShapeBase::
getDefaultCameraFov
()¶ Returns the default vertical field of view in degrees for this object if used as a camera.
Returns: Default FOV
-
float
ShapeBase::
getEnergyLevel
()¶ Get the object’s current energy level.
Returns: energy level
-
float
ShapeBase::
getEnergyPercent
()¶ Get the object’s current energy level as a percentage of maxEnergy.
Returns: energyLevel / datablock.maxEnergy
-
Point3F
ShapeBase::
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.
Returns: the eye position for this object
-
TransformF
ShapeBase::
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
-
VectorF
ShapeBase::
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.
Returns: the eye vector for this object
-
bool
ShapeBase::
getImageAltTrigger
(int slot)¶ 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
-
bool
ShapeBase::
getImageAmmo
(int slot)¶ 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
-
bool
ShapeBase::
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
Returns: the Image’s current generic trigger state
-
bool
ShapeBase::
getImageLoaded
(int slot)¶ 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
-
string
ShapeBase::
getImageScriptAnimPrefix
(int slot)¶ 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
-
int
ShapeBase::
getImageSkinTag
(int slot)¶ 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
-
string
ShapeBase::
getImageState
(int slot)¶ 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
-
bool
ShapeBase::
getImageTarget
(int slot)¶ 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
-
bool
ShapeBase::
getImageTrigger
(int slot)¶ 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
-
string
ShapeBase::
getLookAtPoint
(float distance, int 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
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 ) );
-
float
ShapeBase::
getMaxDamage
()¶ Get the object’s maxDamage level.
Returns: datablock.maxDamage
-
string
ShapeBase::
getModelFile
()¶ Get the model filename used by this shape.
Returns: the shape filename
-
int
ShapeBase::
getMountedImage
(int slot)¶ Get the Image mounted in the specified slot.
Parameters: slot – Image slot to query Returns: datablock mounted in the slot, or 0 if no Image is mounted there.
-
int
ShapeBase::
getMountSlot
(ShapeBaseImageData image)¶ 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.
-
Point3F
ShapeBase::
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 Returns: the muzzle position, or “0 0 0” if the slot is invalid
-
VectorF
ShapeBase::
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 Returns: the muzzle vector, or “0 1 0” if the slot is invalid
-
int
ShapeBase::
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: This command retrieves the ID of the pending Image (2nd case above).
Parameters: slot – Image slot to query Returns: datablock, or 0 if none.
-
float
ShapeBase::
getRechargeRate
()¶ Get the current recharge rate.
Returns: the recharge rate (per tick)
-
float
ShapeBase::
getRepairRate
()¶ Get the per-tick repair amount.
Returns: the current value to be subtracted from damage level each tick
-
string
ShapeBase::
getShapeName
()¶ Get the name of the shape.
Returns: the name of the shape
-
string
ShapeBase::
getSkinName
()¶ Get the name of the skin applied to this shape.
Returns: the name of the skin
-
TransformF
ShapeBase::
getSlotTransform
(int slot)¶ Get the world transform of the specified mount slot.
Parameters: slot – Image slot to query Returns: the mount transform
-
int
ShapeBase::
getTargetCount
()¶ Get the number of materials in the shape.
Returns: the number of materials in the shape.
-
string
ShapeBase::
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). Returns: the name of the indexed material.
-
VectorF
ShapeBase::
getVelocity
()¶ Get the object’s current velocity. Reimplemented in Camera .
Returns: the current velocity
-
float
ShapeBase::
getWhiteOut
()¶ Get the white-out level.
Returns: white-out level
-
bool
ShapeBase::
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
Returns: true if the Image has the requested state defined.
-
bool
ShapeBase::
isCloaked
()¶ Check if this object is cloaked.
Returns: true if cloaked, false if not
-
bool
ShapeBase::
isDestroyed
()¶ Check if the object is in the Destroyed damage state.
Returns: true if damage state is “Destroyed”, false if not
-
bool
ShapeBase::
isDisabled
()¶ Check if the object is in the Disabled or Destroyed damage state.
Returns: true if damage state is not “Enabled”, false if it is
-
bool
ShapeBase::
isEnabled
()¶ Check if the object is in the Enabled damage state.
Returns: true if damage state is “Enabled”, false if not
-
bool
ShapeBase::
isHidden
()¶ Check if the object is hidden.
Returns: true if the object is hidden, false if visible.
-
bool
ShapeBase::
isImageFiring
(int slot)¶ 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.
-
bool
ShapeBase::
isImageMounted
(ShapeBaseImageData image)¶ 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.
-
bool
ShapeBase::
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
Returns: true if successful, false if failed
Example:
%player.mountImage( PistolImage, 1 ); %player.mountImage( CrossbowImage, 0, false ); %player.mountImage( RocketLauncherImage, 0, true, blue );
-
bool
ShapeBase::
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 Returns: true if successful, false if failed
-
bool
ShapeBase::
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
Returns: true if the sound was attached successfully, false if failed
-
bool
ShapeBase::
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.
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
-
void
ShapeBase::
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
-
void
ShapeBase::
setCameraFov
(float fov)¶ Set the vertical field of view in degrees for this object if used as a camera.
Parameters: fov – new FOV value
-
void
ShapeBase::
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
-
void
ShapeBase::
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.
Parameters: level – flash level (0-1)
-
void
ShapeBase::
setDamageLevel
(float level)¶ Set the object’s current damage level.
Parameters: level – new damage level
-
bool
ShapeBase::
setDamageState
(string state)¶ Set the object’s damage state.
Parameters: state – should be one of “Enabled”, “Disabled”, “Destroyed” Returns: true if successful, false if failed
-
void
ShapeBase::
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 Example:
%obj.setDamageVector( "0 0 1" );
-
void
ShapeBase::
setEnergyLevel
(float level)¶ Set this object’s current energy level.
Parameters: level – new energy level
-
void
ShapeBase::
setHidden
(bool show)¶ Add or remove this object from the scene. When removed from the scene, the object will not be processed or rendered. Reimplemented from SimObject .
Parameters: show – False to hide the object, true to re-show it
-
bool
ShapeBase::
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
Returns: the Image’s new alt trigger state
-
bool
ShapeBase::
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
Returns: the Image’s new ammo state
-
int
ShapeBase::
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
Returns: the Image’s new generic trigger state or -1 if there was a problem.
-
bool
ShapeBase::
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
Returns: the Image’s new loaded state
-
void
ShapeBase::
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
-
bool
ShapeBase::
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
Returns: the Image’s new target state
-
bool
ShapeBase::
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
Returns: the Image’s new trigger state
-
void
ShapeBase::
setInvincibleMode
(float time, float speed)¶ Setup the invincible effect. This effect is used for HUD feedback to the user that they are invincible.
Parameters: - time – duration in seconds for the invincible effect
- speed – speed at which the invincible effect progresses
-
void
ShapeBase::
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
-
void
ShapeBase::
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)
-
void
ShapeBase::
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)
-
void
ShapeBase::
setShapeName
(string name)¶ Set the name of this shape.
Parameters: name – new name for the shape
-
void
ShapeBase::
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
-
bool
ShapeBase::
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
Returns: true if successful, false if failed
-
bool
ShapeBase::
setThreadPosition
(int slot, float pos)¶ Set the position within an animation thread.
Parameters: - slot – thread slot to modify
- pos – position within thread
Returns: true if successful, false if failed
-
bool
ShapeBase::
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)
Returns: true if successful, false if failed
-
bool
ShapeBase::
setVelocity
(Point3F vel)¶ Set the object’s velocity.
Parameters: vel – new velocity for the object Returns: true
-
void
ShapeBase::
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.
Parameters: level – flash level (0-1)
-
void
ShapeBase::
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.
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
-
bool
ShapeBase::
stopAudio
(int slot)¶ 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
-
bool
ShapeBase::
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 Returns: true if successful, false if failed
-
bool
ShapeBase::
unmountImage
(int slot)¶ Unmount the mounted Image in the specified slot.
Parameters: slot – Image slot to unmount Returns: true if successful, false if failed
-
float
ShapeBase::
validateCameraFov
(float fov)¶ 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.
Fields¶
-
bool
ShapeBase::
isAIControlled
¶ Is this object AI controlled. If True then this object is considered AI controlled and not player controlled.
-
string
ShapeBase::
skin
¶ 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.