Shapebaseimagedata {documentation scripting advanced}
|
Represents geometry to be mounted to a ShapeBase object. Unlike other datablocks, ShapeBaseImageData does not have a base class associated with it. Instead, this datablock is an abstraction of geometry that can only be mounted to a ShapeBase object and is only used by a ShapBase object. The most common use for ShapeBaseImageData objects (referred to as Images hereafter) is for weapons carried by a Player or Vehicle object, and much of the functionality provided by the Image is aimed at that use-case. Images include a powerful state machine to control animations, sounds, script callbacks, and state transitions. This state system is downloaded to the client so that clients can predict state changes and animate accordingly. The following example - a grenade launcher weapon - demonstates the flexibility of the system. The weapon includes states and transitions to handle the normal ready->fire->reload->ready loop as well as noammo->dryfire for firing when the weapon is out of ammo. 
Images are mounted into a slot on the target ShapeBase derrived object as shown below.
The DTS or DAE model used for the Image has the following requirements:
When the Image is used as a weapon, a sequence can be added to display a muzzle flash when the weapon is fired (if stateSequenceRandomFlash is set to true for the firing state). The name of the muzzle flash sequence is the same as the state sequence (eg. fire), but with '_vis' appended (eg. fire_vis). In the example below, the muzzle flash is made up of three quads; one facing the player, and two crossed quads pointing out of the weapon so viewers perpendicular to the player will also see the flash.  The visibility of the muzzle flash mesh is animated on for 1 frame then off for 1 frame as shown below, but any Torque supported animation method could be used as well. For example, the node the quads are attached to could be rotated or scaled, or the mesh Material could be animated (UV or frame) to provide further variation.  The ShapeBaseImageData supports an optional shape that is displayed when the player is in a first person view. This shape is defined using the shapeFileFP property. You also must set an eyeOffset or make use of an eye mount node for this shape to be used in a first person view. Having this second shape defined provides for more flexibility between 3rd person (and what other players see) and 1st person views. In a typical first person shooter the 3rd person weapon is not as detailed and supports a limited number of animation sequences. Just enough for the other players in the game to get a sense of what the player is doing. Then the 1st person weapon has a lot more detail, such as moving parts, etc. It may also have some arms and hands incldued that are animated when reloading the weapon and other actions. Only the player holding the weapon sees all of this. There are a number of things to keep in mind if you make use of shapeFileFP:
Starting with T3D 1.2 control is now given over transitioning from one image state's sequence to another state's sequence. The new state "stateSequenceTransitionIn" and "stateSequenceTransitionOut" flags dictate if the current state's sequence should be transitioned into when changing to the current state, or transitioned out of when switching to a new state. However, there are times when you don't want to do an animation sequence transition regardless of which state you are coming from. An example of this is the traditional "Fire" state. A Fire state should play immediately and not be transitioned into. In these cases a state may set the "stateSequenceNeverTransition" flag. With that set a state's sequence will begin to play immediately. When it comes to choosing what sequence to play on the mounted image there are now some new rules. Under 1.1 when an image state requested a named sequence that is found on the mounted image and played -- its action sequence. This still occurs under 1.2. However, it is now possible to modify the name of the sequence to play based on some prefixes. PlayerData now has two additional, optional fields: imageAnimPrefix and imageAnimPrefixFP. Just like how these same fields on ShapeBaseImageData can modify when sequences are played on the player based on what is mounted (see Player class documentation), these two PlayerData fields can modify what sequence is played on the mounted image based on the mounting player. This becomes especially useful when combined with 1st person arms -- although here we're just talking about weapons/mounted images. Let's suppose we have two types of player: Soldier and Alien. We may want each type of player to use the same weapon slightly differently (or even radically differently, such as the Alien holding the weapon upside down). We use the "Soldier" anim prefix in the soldier's datablock and the "Alien" prefix in the alien's datablock. Now when looking up the sequence for a weapon's fire state -- usually called "fire" by convention -- the appropriate prefix is added first. And if that prefixed sequence is not found, then we fall back to the standard sequence name. So the soldier's sequence name search looks like this:
and the alien's sequence name search looks like this:
This gives the artist greater control over how the weapons look. And because there are separate prefixes possible on PlayerData for 1st person and 3rd person you can mix and match as appropriate. So you could set a prefix for 1st person, but leave it blank for 3rd person (don't do anything special in 3rd person). Another way that an image state's sequence name could be modified is through the new ShapeBase::setImageScriptAnimPrefix() method. This allows you to insert an additional prefix into the name look up. The current scripts pass along the player's current pose name, but anything could be passed in based on game play. This can be even more useful with the 1st person arms. You could then have a weapon idle state when swimming that moves the weapon (and 1st person arms) in a gentle swim motion. When you combine the PlayerData prefix with the script anim prefix and finally with the image state sequence name, you end up with the following sequence name search pattern (the first found is used):
Whenever ShapeBase::setImageScriptAnimPrefix() is called there is a transition from the currently playing state sequence into the new script prefixed animation sequence. In our example, this allows for a transition from walking to swimming for the weapon. The new ShapeBaseImageData scriptAnimationTransitionTime controls how long to take for this transition. As with 1.1 the placement of the 1st person image may be set with the eyeOffset parameter. Now with 1.2 the 1st person image may be placed based on a node in the 1st person DTS/DAE shape, the "eyeMount" node. When the ShapeBaseImageData's useEyeNode parameter is made true, the image is effectively mounted to the 3rd person player's "eye" node, locking it into place. This allows the artist in their 3D application to precisely place the 1st person weapon in view when their 3D app's camera is placed on the eyeMount node and has the same field of view as Torque. This is very handy when animating the 1st person weapon, especially with 1st person arms. Also with 1.2 an image that is placed with the eyeMount node may have an "eye" node defined. When found the player's camera is mounted to the image's "eye" node rather than the 3rd person player's "eye" node. This allows for animating the camera such as during a fire sequence. Allowing for this much control does have a potential down side. In order for a weapon to fire correctly on the server it needs to have its muzzle point at the correct location. If a weapon's root pose (without animation) doesn't have its muzzle point at roughly the same location as when the weapon is fired, then the new ShapeBaseImageData "animateOnServer" flag should be set. When set the server will perform all state machine animation to ensure the muzzle point is at the correct location when required. This puts an extra strain on the server. If care is taken when building the weapons such that the root pose is close enough to the fire pose, then you can safely leave the "animateOnServer" flag off and not have to worry about the extra server load. Starting with 1.2 there are now a number of new triggers that may be set for a ShapeBaseImageData's state machine to react to. These provide greater game play control over an image's state flow. The first are the "stateTransitionOnMotion" and "stateTransitionOnNoMotion" triggers. This trigger occurs whenever the mounting ShapeBase (usually a Player) has x, y or z motion applied through the Move structure. From a Player perspective this means whenever the user moves their player forwards, backwards or strafes. That has been used to provide weapons a slight bobbing appearance (using an animation sequence) when the weapon is idle. Fire and Reload states don't usually make use of these triggers to keep those actions solid. There has always been a target trigger for ShapeBaseImageData but under 1.1 it was not possible to set it, nor was it used. Starting with 1.2 you can now set the target trigger in script using ShapeBase::setImageTargetState() and use stateTransitionOnTarget and stateTransitionOnNoTarget for whatever game play reasons are required. Finally, there are four new generic triggers that may be set from script and used for whatever purpose the game play imposes. These are "stateTransitionGeneric0In", "stateTransitionGeneric1In", etc. and "stateTransitionGeneric0Out", "stateTransition1Out" etc. The FPS Tutorial weapons use the first generic trigger to indicate that the player is sprinting and switch to a Sprint state to prevent firing of the weapon. Other possible uses are for iron sights. The client and server move through a ShapeBaseImageData's state machine independantly according to various triggers, timeouts, etc. The client is not normally told to move to a specific state when the server does. However, there are three instances where the client is told by the server to immediately jump to a given state. This ensures that the client's experience matches the server at key moments. As such, only one of each of these states may exist in a single ShapeBaseImageData state machine at a time. The fire state is the first such state. It is indicated by setting the state's "stateFire" flag to true. This is the state immediately jumped to when the weapon begins to fire. The alternate fire state is the second forced jump point (new in 1.2). It is indicated by setting the state's "stateAlternateFire" flag to true. Not all weapons have an alternate fire state. In fact most games treat a weapon's alternate fire as a separate weapon altogether. The reload state is the last special state (new in 1.2). It is indicated by setting the state's "stateReload" flag to true. This state is triggered if the weapon makes use of the new 1.2 ammo clip system and the weapon is reloading a clip, either automatically or manually triggered by the client.
Called when the Image is first mounted to the object.
Called when the Image is unmounted from the object.
Flag to control whether the Image's aim is automatically converged with the crosshair. Currently unused. Indicates that all shapes should be animated in sync. When multiple shapes are defined for this image datablock, each of them are automatically animated in step with each other. This allows for easy switching between between shapes when some other condition changes, such as going from first person to third person, and keeping their look consistent. If you know that you'll never switch between shapes on the fly, such as players only being allowed in a first person view, then you could set this to false to save some calculations. There are other circumstances internal to the engine that determine that only the current shape should be animated rather than all defined shapes. In those cases, this property is ignored.
Indicates that the image should be animated on the server. In most cases you'll want this set if you're using useEyeNode. You may also want to set this if the muzzlePoint is animated while it shoots. You can set this to false even if these previous cases are true if the image's shape is set up in the correct position and orientation in the 'root' pose and none of the nodes are animated at key times, such as the muzzlePoint essentially remaining at the same position at the start of the fire state (it could animate just fine after the projectile is away as the muzzle vector is only calculated at the start of the state). You'll also want to set this to true if you're animating the camera using the image's 'eye' node -- unless the movement is very subtle and doesn't need to be reflected on the server.
Amplitude of the camera shaking effect.
Frequency of the camera shaking effect.
DebrisData datablock to use for ejected casings.
Whether this Image can be cloaked. Currently unused. If true, verify that the CRC of the client's Image matches the server's CRC for the Image when loaded by the client. Flag to adjust the aiming vector to the eye's LOS point. Flag to adjust the aiming vector to the eye's LOS point when in 1st person view.
Flag to adjust the aiming vector to the camera's LOS point when in 3rd person view.
Whether to enable environment mapping on this Image.
"X Y Z" translation offset from the ShapeBase model's eye node. When in first person view, this is the offset from the eye node to place the gun. This gives the gun a fixed point in space, typical of a lot of FPS games.
Set to true to render the image in first person.
Passed along to the mounting shape to modify animation sequences played in third person. [optional].
Passed along to the mounting shape to modify animation sequences played in first person. [optional]. The color of light this Image emits.
Duration in SimTime of Pulsing and WeaponFire type lights.
Radius of the light this Image emits.
The type of light this Image emits.
Mass of this Image. This is added to the total mass of the ShapeBase object. Maximum number of sounds this Image can play at a time. Any value <= 0 indicates that it can play an infinite number of sounds. Minimum Image energy for it to be operable.
Mount node # to mount this Image to. This should correspond to a mount# node on the ShapeBase derived object we are mounting to.
The projectile fired by this Image.
The amount of time to transition between the previous sequence and new sequence when the script prefix has changed. When setImageScriptAnimPrefix() is used on a ShapeBase that has this image mounted, the image will attempt to switch to the new animation sequence based on the given script prefix. This is the amount of time it takes to transition from the previously playing animation sequence tothe new script prefix-based animation sequence.
Flag indicating whether the camera should shake when this Image fires.
The DTS or DAE model to use for this Image.
The DTS or DAE model to use for this Image when in first person. This is an optional parameter that also requires either eyeOffset or useEyeNode to be set. If none of these conditions is met then shapeFile will be used for all cases. Typically you set a first person image for a weapon that includes the player's arms attached to it for animating while firing, reloading, etc. This is typical of many FPS games.
Vector direction to eject shell casings.
Variance (in degrees) from the shellExitDir vector to eject casings.
Speed at which to eject casings.
If false, other Images will temporarily be blocked from mounting while the state machine is executing the tasks in this state. For instance, if we have a rocket launcher, the player shouldn't be able to switch out while firing. So, you'd set stateAllowImageChange to false in firing states, and true the rest of the time. The first state with this set to true is the state entered by the client when it receives the 'altFire' event.
Direction of the animation to play in this state. True is forward, false is backward.
If true, a shell casing will be ejected in this state. Emitter to generate particles in this state (from muzzle point or specified node).
Name of the node to emit particles from.
How long (in seconds) to emit particles on entry to this state.
Amount of energy to subtract from the Image in this state. Energy is drained at stateEnergyDrain units/tick as long as we are in this state.
The first state with this set to true is the state entered by the client when it receives the 'fire' event. If set to true, and both ready and loaded transitions are true, the ready transition will be taken instead of the loaded transition. A state is 'ready' if pressing the fire trigger in that state would transition to the fire state. Set the loaded state of the Image.
Name of this state. Type of recoil sequence to play on the ShapeBase object on entry to this state.
The first state with this set to true is the state entered by the client when it receives the 'reload' event. If true, the timeScale of the stateSequence animation will be adjusted such that the sequence plays for stateTimeoutValue seconds. If true, the timeScale of the first person stateSequence animation will be adjusted such that the sequence plays for stateTimeoutValue seconds. Indicates if the sequence to be played on the mounting shape should be scaled to the length of the state.
Method to execute on entering this state. Scoped to this image class name, then ShapeBaseImageData. The script callback function takes the same arguments as the onMount callback.
Name of the sequence to play on entry to this state. Never allow a transition to this sequence. Often used for a fire sequence. If true, the muzzle flash sequence will be played while in this state. The name of the muzzle flash sequence is the same as stateSequence, with "_vis" at the end. Do we transition to the state's sequence when we enter the state? Do we transition to the new state's sequence when we leave the state? The time to transition in or out of a sequence.
Name of the sequence that is played on the mounting shape.
Sound to play on entry to this state. Controls how fast the 'spin' animation sequence will be played in this state.
Time in seconds to wait before transitioning to stateTransitionOnTimeout. Name of the state to transition to when the generic trigger 0 state changes to true. Name of the state to transition to when the generic trigger 0 state changes to false. Name of the state to transition to when the generic trigger 1 state changes to true. Name of the state to transition to when the generic trigger 1 state changes to false. Name of the state to transition to when the generic trigger 2 state changes to true. Name of the state to transition to when the generic trigger 2 state changes to false. Name of the state to transition to when the generic trigger 3 state changes to true. Name of the state to transition to when the generic trigger 3 state changes to false. Name of the state to transition to when the alt trigger state of the Image changes to false (alt fire button up). Name of the state to transition to when the alt trigger state of the Image changes to true (alt fire button down).
Name of the state to transition to when the ammo state of the Image changes to true.
Name of the state to transition to when the loaded state of the Image changes to 'Loaded'.
Name of the state to transition to when the Player moves.
Name of the state to transition to when the ammo state of the Image changes to false. Name of the state to transition to when the Player stops moving. Name of the state to transition to when the Image loses a target. Name of the state to transition to when the loaded state of the Image changes to 'Empty'.
Name of the state to transition to when the Image exits the water.
Name of the state to transition to when the Image gains a target.
Name of the state to transition to when we have been in this state for stateTimeoutValue seconds. Name of the state to transition to when the trigger state of the Image changes to false (fire button released). Name of the state to transition to when the trigger state of the Image changes to true (fire button down).
Name of the state to transition to when the Image enters the water. If false, this state ignores stateTimeoutValue and transitions immediately if other transition conditions are met. Mount image using image's eyeMount node and place the camera at the image's eye node (or at the eyeMount node if the eye node is missing). When in first person view, if an 'eyeMount' node is present in the image's shape, this indicates that the image should mount eyeMount node to Player eye node for image placement. The Player's camera should also mount to the image's eye node to inherit any animation (or the eyeMount node if the image doesn't have an eye node).
If true, allow multiple timeout transitions to occur within a single tick (useful if states have a very small timeout). Flag indicating whether this Image uses energy instead of ammo. The energy level comes from the ShapeBase object we're mounted to.
|