ShapeBaseImageData Class Reference
[Game Objects]

Represents geometry to be mounted to a ShapeBase object. More...

Inheritance diagram for ShapeBaseImageData:

Public Member Functions
Callbacks

void	onMount (ShapeBase obj, int slot, float dt)
	Called when the Image is first mounted to the object.
void	onUnmount (ShapeBase obj, int slot, float dt)
	Called when the Image is unmounted from the object.
Public Attributes
bool	accuFire
	Flag to control whether the Image's aim is automatically converged with the crosshair.
Point3F	camShakeAmp
	Amplitude of the camera shaking effect.
Point3F	camShakeFreq
	Frequency of the camera shaking effect.
DebrisData	casing
	DebrisData datablock to use for ejected casings.
bool	cloakable
	Whether this Image can be cloaked.
bool	computeCRC
	If true, verify that the CRC of the client's Image matches the server's CRC for the Image when loaded by the client.
bool	correctMuzzleVector
	Flag to adjust the aiming vector to the eye's LOS point.
bool	emap
	Whether to enable environment mapping on this Image.
MatrixPosition	eyeOffset
	"X Y Z" translation offset from the ShapeBase model's eye node.
MatrixRotation	eyeRotation
	"X Y Z ANGLE" rotation offset from the ShapeBase model's eye node.
bool	firstPerson
	This flag must be set for the adjusted LOS muzzle vector to be computed.
float	lightBrightness
	Brightness of the light this Image emits.
ColorF	lightColor
	The color of light this Image emits.
int	lightDuration
	Duration in SimTime of Pulsing and WeaponFire type lights.
float	lightRadius
	Radius of the light this Image emits.
ShapeBaseImageLightType	lightType
	The type of light this Image emits.
float	mass
	Mass of this Image.
int	maxConcurrentSounds
	Maximum number of sounds this Image can play at a time.
float	minEnergy
	Minimum Image energy for it to be operable.
int	mountPoint
	Mount node # to mount this Image to.
MatrixPosition	offset
	"X Y Z" translation offset from this Image's mountPoint node to attach to.
ProjectileData	Projectile
	The projectile fired by this Image.
MatrixRotation	rotation
	"X Y Z ANGLE" rotation offset from this Image's mountPoint node to attach to.
bool	shakeCamera
	Flag indicating whether the camera should shake when this Image fires.
filename	shapeFile
	The DTS or DAE model to use for this Image.
Point3F	shellExitDir
	Vector direction to eject shell casings.
float	shellExitVariance
	Variance (in degrees) from the shellExitDir vector to eject casings.
float	shellVelocity
	Speed at which to eject casings.
bool	stateAllowImageChange [31]
	If false, other Images will temporarily be blocked from mounting while the state machine is executing the tasks in this state.
bool	stateDirection [31]
	Direction of the animation to play in this state.
bool	stateEjectShell [31]
	If true, a shell casing will be ejected in this state.
ParticleEmitterData	stateEmitter [31]
	Emitter to generate particles in this state (from muzzle point or specified node).
string	stateEmitterNode [31]
	Name of the node to emit particles from.
float	stateEmitterTime [31]
	How long (in seconds) to emit particles on entry to this state.
float	stateEnergyDrain [31]
	Amount of energy to subtract from the Image in this state.
bool	stateFire [31]
	The first state with this set to true is the state entered by the client when it receives the 'fire' event.
bool	stateIgnoreLoadedForReady [31]
	If set to true, and both ready and loaded transitions are true, the ready transition will be taken instead of the loaded transition.
ShapeBaseImageLoadedState	stateLoadedFlag [31]
	Set the loaded state of the Image.
caseString	stateName [31]
	Name of this state.
ShapeBaseImageRecoilState	stateRecoil [31]
	Type of recoil sequence to play on the ShapeBase object on entry to this state.
bool	stateScaleAnimation [31]
	If true, the timeScale of the stateSequence animation will be adjusted such that the sequence plays for stateTimeoutValue seconds.
caseString	stateScript [31]
	Method to execute on entering this state.
string	stateSequence [31]
	Name of the sequence to play on entry to this state.
bool	stateSequenceRandomFlash [31]
	If true, a random frame from the muzzle flash sequence will be displayed each frame.
SFXTrack	stateSound [31]
	Sound to play on entry to this state.
ShapeBaseImageSpinState	stateSpinThread [31]
	Controls how fast the 'spin' animation sequence will be played in this state.
float	stateTimeoutValue [31]
	Time in seconds to wait before transitioning to stateTransitionOnTimeout.
string	stateTransitionOnAltTriggerDown [31]
	Name of the state to transition to when the alt trigger state of the Image changes to false (alt fire button up).
string	stateTransitionOnAltTriggerUp [31]
	Name of the state to transition to when the alt trigger state of the Image changes to true (alt fire button down).
string	stateTransitionOnAmmo [31]
	Name of the state to transition to when the ammo state of the Image changes to true.
string	stateTransitionOnLoaded [31]
	Name of the state to transition to when the loaded state of the Image changes to 'Loaded'.
string	stateTransitionOnNoAmmo [31]
	Name of the state to transition to when the ammo state of the Image changes to false.
string	stateTransitionOnNoTarget [31]
	Name of the state to transition to when the Image loses a target.
string	stateTransitionOnNotLoaded [31]
	Name of the state to transition to when the loaded state of the Image changes to 'Empty'.
string	stateTransitionOnNotWet [31]
	Name of the state to transition to when the Image exits the water.
string	stateTransitionOnTarget [31]
	Name of the state to transition to when the Image gains a target.
string	stateTransitionOnTimeout [31]
	Name of the state to transition to when we have been in this state for stateTimeoutValue seconds.
string	stateTransitionOnTriggerDown [31]
	Name of the state to transition to when the trigger state of the Image changes to false (fire button released).
string	stateTransitionOnTriggerUp [31]
	Name of the state to transition to when the trigger state of the Image changes to true (fire button down).
string	stateTransitionOnWet [31]
	Name of the state to transition to when the Image enters the water.
bool	stateWaitForTimeout [31]
	If false, this state ignores stateTimeoutValue and transitions immediately if other transition conditions are met.
bool	useRemainderDT
	If true, allow multiple timeout transitions to occur within a single tick (useful if states have a very small timeout).
bool	usesEnergy
	Flag indicating whether this Image uses energy instead of ammo. The energy level comes from the ShapeBase object we're mounted to.

Detailed Description

Represents geometry to be mounted to a ShapeBase object.

Unlike other datablocks, ShapeBaseImageData does not have an associated xBase 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.

Example:

datablock ShapeBaseImageData( GrenadeLauncherImage )
{
   // Initial start up state
   stateName[0] = "Preactivate";
   stateTransitionOnLoaded[0] = "Activate";
   stateTransitionOnNoAmmo[0] = "NoAmmo";

   // Activating the gun.
   // Called when the weapon is first mounted and there is ammo.
   stateName[1] = "Activate";
   stateTransitionOnTimeout[1] = "Ready";
   stateTimeoutValue[1] = 0.6;
   stateSequence[1] = "Activate";

   // Ready to fire, just waiting for the trigger
   stateName[2] = "Ready";
   stateTransitionOnNoAmmo[2] = "NoAmmo";
   stateTransitionOnTriggerDown[2] = "CheckWet";
   stateSequence[2] = "Ready";

   // Fire the weapon. Calls the fire script which does the actual work.
   stateName[3] = "Fire";
   stateTransitionOnTimeout[3] = "PostFire";
   stateTimeoutValue[3] = 0.4;
   stateFire[3] = true;
   stateAllowImageChange[3] = false;
   stateSequence[3] = "Fire";
   stateScript[3] = "onFire";
   stateSound[3] = GrenadeLauncherFireSound;

   // Check ammo
   stateName[4] = "PostFire";
   stateTransitionOnAmmo[4] = "Reload";
   stateTransitionOnNoAmmo[4] = "NoAmmo";

   // Play the reload animation, and transition into
   stateName[5] = "Reload";
   stateTransitionOnTimeout[5] = "Ready";
   stateTimeoutValue[5] = 0.2;
   stateAllowImageChange[5] = false;
   stateSequence[5] = "Reload";
   stateEjectShell[5] = false; // set to true to enable shell casing eject
   stateSound[5] = GrenadeLauncherReloadSound;

   // No ammo in the weapon, just idle until something shows up.
   // Play the dry fire sound if the trigger iS pulled.
   stateName[6] = "NoAmmo";
   stateTransitionOnAmmo[6] = "Reload";
   stateSequence[6] = "NoAmmo";
   stateTransitionOnTriggerDown[6] = "DryFire";

   // No ammo dry fire
   stateName[7] = "DryFire";
   stateTimeoutValue[7] = 1.0;
   stateTransitionOnTimeout[7] = "NoAmmo";
   stateSound[7] = GrenadeLauncherFireEmptySound;

   // Check if wet
   stateName[8] = "CheckWet";
   stateTransitionOnWet[8] = "WetFire";
   stateTransitionOnNotWet[8] = "Fire";

   // Wet fire
   stateName[9] = "WetFire";
   stateTransitionOnTimeout[9] = "PostFire";
   stateTimeoutValue[9] = 0.4;
   stateFire[9] = true;
   stateAllowImageChange[9] = false;
   stateSequence[9] = "Fire";
   stateScript[9] = "onWetFire";
   stateSound[9] = GrenadeLauncherFireSound;
};

Images are mounted into a slot on the target ShapeBase derrived object as shown below.

Example:

$WeaponSlot = 0;

...

// Use a weapon by mounting it onto the given ShapeBase derrived object.
// %data is the weapon whose .image member points to its ShapeBaseImageData datablock
// %obj is the object to mount the weapon on
function Weapon::onUse( %data, %obj )
{
   // Default behavior for all weapons is to mount it into the object's weapon
   // slot, as defined by $WeaponSlot here, and is usually slot 0.  We begin by
   // checking if the requested weapon is already mounted.
   if ( %obj.getMountedImage($WeaponSlot) != %data.image.getId() )
   {
      // The requested weapon is not mounted on $WeaponSlot so mount it now.
      %obj.mountImage( %data.image, $WeaponSlot );
   }
}

The DTS or DAE model used for the Image has the following requirements:

ejectPoint node: Node from which shell casings are emitted
muzzlePoint node: Node used to fire projectiles and particles
retractionPoint node: Nearest point to use as muzzle when up against a wall (and muzzle node is inside wall). This node is optional.
mountPoint node: Where to attach to on this object. If not present the origin of the model will be used.
ambient sequence: Cyclic sequence to play while Image is mounted. This sequence is optional.
spin sequence: Cyclic sequence to play while Image is mounted. This sequence is optional. See ShapeBaseImageSpinState.

Member Function Documentation

void ShapeBaseImageData::onMount	(	ShapeBase	obj,
		int	slot,
		float	dt
	)

Called when the Image is first mounted to the object.

Parameters:

	obj	object that this Image has been mounted to
	slot	Image mount slot on the object
	dt	time remaining in this Image update

void ShapeBaseImageData::onUnmount	(	ShapeBase	obj,
		int	slot,
		float	dt
	)

Called when the Image is unmounted from the object.

Parameters:

	obj	object that this Image has been unmounted from
	slot	Image mount slot on the object
	dt	time remaining in this Image update

Member Data Documentation

bool ShapeBaseImageData::accuFire

Flag to control whether the Image's aim is automatically converged with the crosshair.

Currently unused.

Point3F ShapeBaseImageData::camShakeAmp

Amplitude of the camera shaking effect.

See also:: shakeCamera

Point3F ShapeBaseImageData::camShakeFreq

Frequency of the camera shaking effect.

See also:: shakeCamera

DebrisData ShapeBaseImageData::casing

DebrisData datablock to use for ejected casings.

See also:: stateEjectShell

bool ShapeBaseImageData::cloakable

Whether this Image can be cloaked.

Currently unused.

bool ShapeBaseImageData::computeCRC

If true, verify that the CRC of the client's Image matches the server's CRC for the Image when loaded by the client.

bool ShapeBaseImageData::correctMuzzleVector

Flag to adjust the aiming vector to the eye's LOS point.

See also:: ShapeBase::getMuzzleVector()

bool ShapeBaseImageData::emap

Whether to enable environment mapping on this Image.

MatrixPosition ShapeBaseImageData::eyeOffset

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

See also:: eyeRotation

MatrixRotation ShapeBaseImageData::eyeRotation

"X Y Z ANGLE" rotation offset from the ShapeBase model's eye node.

When in first person view, this is the rotation from the eye node to place the gun.

See also:: eyeOffset

bool ShapeBaseImageData::firstPerson

This flag must be set for the adjusted LOS muzzle vector to be computed.

See also:: ShapeBase::getMuzzleVector()

float ShapeBaseImageData::lightBrightness

Brightness of the light this Image emits.

Only valid for WeaponFireLight.

See also:: lightType

ColorF ShapeBaseImageData::lightColor

The color of light this Image emits.

See also:: lightType

int ShapeBaseImageData::lightDuration

Duration in SimTime of Pulsing and WeaponFire type lights.

See also:: lightType

float ShapeBaseImageData::lightRadius

Radius of the light this Image emits.

See also:: lightType

ShapeBaseImageLightType ShapeBaseImageData::lightType

The type of light this Image emits.

See also:: ShapeBaseImageLightType

float ShapeBaseImageData::mass

Mass of this Image.

This is added to the total mass of the ShapeBase object.

int ShapeBaseImageData::maxConcurrentSounds

Maximum number of sounds this Image can play at a time.

Any value <= 0 indicates that it can play an infinite number of sounds.

float ShapeBaseImageData::minEnergy

Minimum Image energy for it to be operable.

See also:: usesEnergy

int ShapeBaseImageData::mountPoint

Mount node # to mount this Image to.

This should correspond to a mount# node on the ShapeBase derived object we are mounting to.

MatrixPosition ShapeBaseImageData::offset

"X Y Z" translation offset from this Image's mountPoint node to attach to.

Defaults to "0 0 0". ie. attach this Image's mountPoint node to the ShapeBase model's mount# node without any offset.

See also:: rotation

ProjectileData ShapeBaseImageData::Projectile

The projectile fired by this Image.

MatrixRotation ShapeBaseImageData::rotation

"X Y Z ANGLE" rotation offset from this Image's mountPoint node to attach to.

Defaults to "0 0 0". ie. attach this Image's mountPoint node to the ShapeBase model's mount# node without any additional rotation.

See also:: offset

bool ShapeBaseImageData::shakeCamera

Flag indicating whether the camera should shake when this Image fires.

Note:: Camera shake only works properly if the player is in control of the one and only shapeBase object in the scene which fires an Image that uses camera shake.

filename ShapeBaseImageData::shapeFile

The DTS or DAE model to use for this Image.

Point3F ShapeBaseImageData::shellExitDir

Vector direction to eject shell casings.

See also:: casing

float ShapeBaseImageData::shellExitVariance

Variance (in degrees) from the shellExitDir vector to eject casings.

See also:: shellExitDir

float ShapeBaseImageData::shellVelocity

Speed at which to eject casings.

See also:: casing

bool ShapeBaseImageData::stateAllowImageChange[31]

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.

bool ShapeBaseImageData::stateDirection[31]

Direction of the animation to play in this state.

True is forward, false is backward.

bool ShapeBaseImageData::stateEjectShell[31]

If true, a shell casing will be ejected in this state.

ParticleEmitterData ShapeBaseImageData::stateEmitter[31]

Emitter to generate particles in this state (from muzzle point or specified node).

See also:: stateEmitterNode

string ShapeBaseImageData::stateEmitterNode[31]

Name of the node to emit particles from.

See also:: stateEmitter

float ShapeBaseImageData::stateEmitterTime[31]

How long (in seconds) to emit particles on entry to this state.

float ShapeBaseImageData::stateEnergyDrain[31]

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.

See also:: usesEnergy

bool ShapeBaseImageData::stateFire[31]

The first state with this set to true is the state entered by the client when it receives the 'fire' event.

bool ShapeBaseImageData::stateIgnoreLoadedForReady[31]

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.

ShapeBaseImageLoadedState ShapeBaseImageData::stateLoadedFlag[31]

Set the loaded state of the Image.

IgnoreLoaded: Don't change Image loaded state.
Loaded: Set Image loaded state to true.
NotLoaded: Set Image loaded state to false.

See also:: ShapeBaseImageLoadedState

caseString ShapeBaseImageData::stateName[31]

Name of this state.

ShapeBaseImageRecoilState ShapeBaseImageData::stateRecoil[31]

Type of recoil sequence to play on the ShapeBase object on entry to this state.

NoRecoil: Do not play a recoil sequence.
LightRecoil: Play the light_recoil sequence.
MediumRecoil: Play the medium_recoil sequence.
HeavyRecoil: Play the heavy_recoil sequence.

See also:: ShapeBaseImageRecoilState

bool ShapeBaseImageData::stateScaleAnimation[31]

If true, the timeScale of the stateSequence animation will be adjusted such that the sequence plays for stateTimeoutValue seconds.

caseString ShapeBaseImageData::stateScript[31]

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.

See also:: onMount() for the same arguments as this callback.

string ShapeBaseImageData::stateSequence[31]

Name of the sequence to play on entry to this state.

bool ShapeBaseImageData::stateSequenceRandomFlash[31]

If true, a random frame from the muzzle flash sequence will be displayed each frame.

The name of the muzzle flash sequence is the same as stateSequence, with "_vis" at the end.

SFXTrack ShapeBaseImageData::stateSound[31]

Sound to play on entry to this state.

ShapeBaseImageSpinState ShapeBaseImageData::stateSpinThread[31]

Controls how fast the 'spin' animation sequence will be played in this state.

Ignore: No change to the spin sequence.
Stop: Stops the spin sequence at its current position.
SpinUp: Increase spin sequence timeScale from 0 (on state entry) to 1 (after stateTimeoutValue seconds).
SpinDown: Decrease spin sequence timeScale from 1 (on state entry) to 0 (after stateTimeoutValue seconds).
FullSpeed: Resume the spin sequence playback at its current position with timeScale=1.

See also:: ShapeBaseImageSpinState

float ShapeBaseImageData::stateTimeoutValue[31]

Time in seconds to wait before transitioning to stateTransitionOnTimeout.

string ShapeBaseImageData::stateTransitionOnAltTriggerDown[31]

Name of the state to transition to when the alt trigger state of the Image changes to false (alt fire button up).

string ShapeBaseImageData::stateTransitionOnAltTriggerUp[31]

Name of the state to transition to when the alt trigger state of the Image changes to true (alt fire button down).

string ShapeBaseImageData::stateTransitionOnAmmo[31]

Name of the state to transition to when the ammo state of the Image changes to true.

string ShapeBaseImageData::stateTransitionOnLoaded[31]

Name of the state to transition to when the loaded state of the Image changes to 'Loaded'.

string ShapeBaseImageData::stateTransitionOnNoAmmo[31]

Name of the state to transition to when the ammo state of the Image changes to false.

string ShapeBaseImageData::stateTransitionOnNoTarget[31]

Name of the state to transition to when the Image loses a target.

string ShapeBaseImageData::stateTransitionOnNotLoaded[31]

Name of the state to transition to when the loaded state of the Image changes to 'Empty'.

string ShapeBaseImageData::stateTransitionOnNotWet[31]

Name of the state to transition to when the Image exits the water.

string ShapeBaseImageData::stateTransitionOnTarget[31]

Name of the state to transition to when the Image gains a target.

string ShapeBaseImageData::stateTransitionOnTimeout[31]

Name of the state to transition to when we have been in this state for stateTimeoutValue seconds.

string ShapeBaseImageData::stateTransitionOnTriggerDown[31]

Name of the state to transition to when the trigger state of the Image changes to false (fire button released).

string ShapeBaseImageData::stateTransitionOnTriggerUp[31]

Name of the state to transition to when the trigger state of the Image changes to true (fire button down).

string ShapeBaseImageData::stateTransitionOnWet[31]

Name of the state to transition to when the Image enters the water.

bool ShapeBaseImageData::stateWaitForTimeout[31]

If false, this state ignores stateTimeoutValue and transitions immediately if other transition conditions are met.

bool ShapeBaseImageData::useRemainderDT

If true, allow multiple timeout transitions to occur within a single tick (useful if states have a very small timeout).

bool ShapeBaseImageData::usesEnergy

Flag indicating whether this Image uses energy instead of ammo. The energy level comes from the ShapeBase object we're mounted to.

See also:: ShapeBase::setEnergyLevel()

ShapeBaseImageData Class Reference [Game Objects]

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation

ShapeBaseImageData Class Reference
[Game Objects]