User Guide: Building-block Effects
Building-block effects are the raw materials of special effects and are a good place to start learning about AFX. Many of them are effects that you are probably already familiar with. The standard Torque Explosion is one example of a common building-block effect. The AFX Zodiac effect is another.
An important consideration of building-block effects is that they are conceptually separate from the AFX framework. This allows AFX to support preexisting engine effects like Explosion, ParticleEmitter, and SFXProfile, as well as custom AFX effects like afxZodiac, afxModel, and afxBillboard, and even custom user effects (implemented with a relatively simple adapter class).
Building-block effects are not limited to visual effects, but include sound effects, script events, and damage distribution, to name a few. Actually, just about anything you want to happen at a specific time and place can become a building-block effect under AFX control.
Passive and Influence Effects
Many special effects are passive in that they are primarily decorative in nature. Other objects don’t collide with them and they don’t manipulate or change other simulation objects. Passive effects can usually run exclusively on the clients, effectively invisible to the server. Take particle emitters as an example: you may have identical emitters running on different clients, but it’s usually not important that each particle they generate match exactly from client to client.
Some effects are influence effects. These effects do something to other simulation objects and therefore usually must execute on the server, or operate in some coordinated fashion across both server and clients. Examples of influence effects include Camera Shake and Animation Clip. Camera Shake forces the camera or other objects to vibrate, while Animation Clip selects animation sequences to play in Player and AiPlayer objects.
Animation Clip - afxAnimClipData
An Animation Clip forces a target Player or AiPlayer to perform a particular animation sequence. The Animation Clip does not supply any new animation data, it merely selects, by name, a sequence that is already defined in the target.
Normally when an Animation Clip is applied to a user-controlled Player, any interactive user actions will override the animation selected by the Clip, but Animation Clips can be configured to temporarily block out some user actions for the duration of the clip.
Animation Clip controls the rate of animation playback and can even play a sequence in reverse.
When an Animation Clip selects a blended animation sequence, it is mixed with the current animation instead of replacing it. Animation Clips can be used to activate multiple, overlapping blend sequences.
New in AFX 2: afxAnimClips will select the current sequence of a multi-sequence afxModel when the model is configured as the anim-clip's primary position constraint using a #effect type of constraint.
- Networking: server and client
Animation Lock - afxAnimLockData
Animation Lock is used to lock out user controlled Player actions, often while an Animation Clip is concurrently playing. Animation Clips can already do this, but must lock out user actions for the entire clip length. Sometimes you only want user actions blocked for a short section of a longer playing animation, such as while the Player is thrown in the air. With Animation Lock, you can set a specific timespan when user actions are blocked, independent of any Animation Clip timing.
- Networking: server and client
Area Damage - afxAreaDamageData
Area Damage is useful for assigning area damage with unusual timing that requires synchronization with other special effects. Damage effects can also inflict area damage, but unlike Damage effects, Area Damage calculates the area damage in C++ code rather than calling out to the script function radiusDamage().
- Networking: server only
- New in AFX 2
Audio Bank - afxAudioBank
Audio Bank is operationally identical to Sound Effect except that multiple sound files can be specified. In conjunction with AFX field substitutions, Audio Bank can be used to play a sound that is randomly picked from as many as 32 choices.
- Networking: client only
- New in AFX 2
Billboard - afxBillboardData
A Billboard effect creates a simple textured quadrangle that always faces the camera. A Billboard effect is much like a single static particle and is rendered in a similar fashion. It includes fields for selecting texture coordinates and controlling the blend function.
- Networking: client only
- New in AFX 2
Camera Puppet - afxCameraPuppetData
Camera Puppet is an effect that takes over and controls the transformation of camera objects using the AFX constraint system. It's useful for adding cut-scene like camera control to effects.
- Networking: configurable
- New in AFX 2
Note: Camera Puppet is still a highly experimental type of effect in need of further improvement. Here are some of the known issues:
- Does not reposition the camera to avoid being blocked by objects in the line-of-sight.
- Does not avoid placing the camera inside other objects.
- There are circumstances in which the camera will jitter and not settle into a stable position.
Camera Shake - afxCameraShakeData
Camera Shake utilizes the standard Torque CameraShake class to implement a shaken camera effect. CameraShake is not normally specified with a datablock, so AFX provides a special afxCameraShakeData type. The Torque CameraFXManager is not used for this effect. Instead, the CameraShake class is managed by the AFX framework.
In spite of its name, this effect is not limited to shaking the camera. The target of its effect is determined by the AFX constraint system and can be other existing scene objects.
- Networking: client only
Collision Event - afxCollisionEventData
A Collision Event is used to detect when a constraint source object collides with something. Specifically, it detects when a ShapeBase-derived object's onCollision() method is called. The Collision Event can respond to a collision by calling a script method (similar to a Script Event) or by setting a choreographer trigger bit.
- Networking: server only
- New in AFX 2
Console Message - afxConsoleMessageData
Console Message is a very simple “effect” that prints a message to the console. It can be useful for debugging effect scripts (such as when you want to make sure that an effect with a certain kind of timing is actually getting executed) and for evaluating some kinds of field substitutions.
- Networking: server and client
- New in AFX 2
Damage Effect - afxDamageData
In many games, an important action is the assignment of damage to one or more characters or objects. For assigning damage with unusual timing that requires synchronization with other special effects, AFX implements a Damage Effect. Damage Effects can be used to deal direct damage, radius damage, and damage over time.
Damage Effects can also be used for healing by specifying negative damage amounts.
- Networking: server only
Debris - DebrisData
Debris is a standard Torque effect which can also be used as an AFX building-block effect. AFX uses DebrisData datablocks along with the Debris class to create client-only debris instances. AFX controls when and where a Debris effect is used, including its initial direction vector, but once the debris is launched it resolves on its own. Once started, AFX won’t interrupt the debris early or dynamically change anything about it.
You can constrain other effects to the debris using effect-to-effect constraints.
- Networking: client only
Explosion - ExplosionData
Explosion is a standard Torque effect which can also be used as an AFX building-block effect. AFX uses ExplosionData datablocks along with the Explosion class to create client-only explosions. AFX controls when and where an explosion occurs, but once the explosion is triggered it resolves on its own. AFX won’t interrupt the explosion early or dynamically change anything about it.
- Networking: client only
Foot Switch - afxFootSwitchData
The Foot Switch effect is used to temporarily disable some or all of the stock footstep effects in Player objects. Footstep generated sounds, decals, and dust can all be individually enabled or disabled. This effect is useful when replacing the some of the standard footstep effects with Phrase Effects that respond to footstep triggers.
- Networking: client only
- New in AFX 2
Gui Controller - afxGuiControllerData
With a Gui Controller, the position of an existing gui control can be manipulated using constraints. When a Gui Controller is constrained to a scene object, the dynamic 3D position of the constraint will be projected into 2D screen coordinates and assigned to the affected gui control.
When used to control a progress-bar, the displayed progress of the bar will reflect the elapsed lifetime of the effect. This could be used, for instance, as an alternative to the built-in casting bar control used by afxMagicSpell.
- Networking: client only
- New in AFX 2
Gui Text - afxGuiTextData
A Gui Text effect is used in conjunction with an afxGuiTextHud gui control to add a single text element to the heads-up-display. The position of the text will continuously track the 2D projection of the effect's 3D position. For example, one use for Gui Text effects is to display a floating damage value when an object receives damage.
The Gui Text effect determines the text message and its color, and can be configured to use the shape-name of the effect's constraint source object as its text.
- Networking: client only
- New in AFX 2
Note: Text size is currently determined by the afxGuiTextHud control and cannot be set independently for separate Gui Text effects.
Light - afxLightData
AFX adds the simple afxLightData and afxLight classes for implementing client-only dynamic Lighting Effects. It supports all of the Torque lighting types: Point, Spot, Vector, and Ambient.
For TGE, Point is the most useful because the other types have little or no effect on terrain and interiors. With TGEA, Spot lights do affect terrain and interiors, making them much more useful. Also, an illumination mask can be used to target specific object types: dts, dif, terrain, or atlas.
afxLights are not supported on Torque 3D and must be replaced by alternative T3D-specific lighting effects.
- Networking: client only
Machine Gun - afxMachineGunData
Machine Gun is a simple but useful effect for rapidly shooting standard Torque Projectile objects. Specify roundsPerMinute and attach a ProjectileData datablock, and Machine Gun will fire off projectiles at the specified rate while the effect is active.
Machine Gun is aimed using the AFX constraint system and can track a moving target.
- Networking: server only
Model - afxModelData
Torque has a number of model classes, but lacks an effective client-only model effect. AFX fills this gap with the lightweight afxModelData and afxModel classes. afxModel loads a single dts format model and can play one animation sequence stored in the model. It also has settings for transparency, and in TGE you can override some of the built-in material settings.
New in AFX 2: afxAnimClips will select the current sequence of a multi-sequence afxModel when the model is configured as the anim-clip's primary position constraint using an effect-to-effect (#effect) type of constraint.
With TGEA, the surface characteristics of Model effects are controlled using Materials and CustomMaterials. AFX provides a number of simple pre-made CustomMaterials that are very useful for basic Model Effects.
- Networking: client only
Mooring - afxMooringData
Mooring is an invisible object which can be positioned and oriented within a scene like other objects. It's main purpose is to serve as a common mount point for other effects within the same choreographer. Typically one uses AFX animation and constraint features to create movement for a Mooring and then other effects are bound to it using effect-to-effect (#effect) constraints.
An Mooring can be configured to display an axis object at its location, which is very helpful during the design and debugging phases of effect development.
- Networking: configurable
Multi Light - afxMultiLightData
A Multi Light is a very simple effect that groups together up to four Light Effects and/or SG Light Objects in any combination. It allows multiple lights to act as a single light, controlled by one effect wrapper.
Multi Lights are most useful in TGEA when they are used in combination with illumination masks. In such cases, you divide a single light into two lights, each separately illuminating terrain and dts/dif objects. A Multi Light effect then recombines these lights for management by a single effects wrapper as if it were a single light.
Multi Lights should not be confused with duel lights, a lighting optimization used by the TGEA lighting system.
- Networking: client only
Particle Emitter - ParticleEmitterData
The Particle Emitter is a standard Torque effect which can also be used as an AFX building-block effect. AFX uses ParticleEmitterData datablocks along with the ParticleEmitter class to create client-only particle emitters. AFX dynamically controls a particle emitter’s location, orientation, and when it is actively emitting particles.
AFX enhances the stock ParticleEmitter with a number of AFX-specific customizations and subclasses, including features that are standard in TGEA: tiled particles, tiled particle animation, distance sorting, and expanded blend settings.
New in AFX 2: Path-based particle emitters can now be configured to continuously conform to the ground on a point-by-point basis.
- Networking: client only
Phrase Effect - afxPhraseEffectData
A Phrase Effect is a grouping or phrase of effects that share a common timeline, but do nothing until certain trigger events occur. It's like having a whole Effectron organized as an individual effect.
Phrase effects can respond to a number of different kinds of triggers:
- Player triggers such as footsteps, jumps, landings, and idle triggers.
- Arbitrary animation triggers on dts-based scene objects.
- Arbitrary trigger bits assigned to active choreographer objects.
- Networking: server and client
- New in AFX 2
Physical Zone - afxPhysicalZoneData
A Physical Zone is a Torque effect that applies physical forces to Players and other movable objects that enter a specific region of influence. AFX has enhanced Physical Zones by allowing orientation of vector forces and adding radial forces. AFX has also optimized Physical Zone networking so that they can be constrained to moving objects for a variety of effects including repelling and flying. Physical Zone effects are defined using afxPhysicalZoneData datablocks.
New in AFX 2: Constraint object can now optionally be excluded from the effects of the Physical Zone.
- Networking: server only
Player Movement - afxPlayerMovementData
DESCRIPTION NEEDED HERE
- Networking: server only
- New in AFX 2
Player Puppet - afxPlayerPuppetData
DESCRIPTION NEEDED HERE
- Networking: configurable
- New in AFX 2
Projectile - ProjectileData, afxProjectileData
Standard Torque Projectiles can be used as an AFX building-block effect. AFX uses ProjectileData datablocks along with the Projectile class to shoot server-initiated projectiles. AFX controls when and where a Projectile effect is started, including its initial direction vector, but once the projectile is launched it resolves on its own. Once started, AFX won’t interrupt the projectile early or dynamically change anything about it.
New in AFX 2: afxProjectileData, a subclass of ProjectileData adds a number of new options.
- Networking: server only
Script Event - afxScriptEventData
Arbitrary script functions can be called as an AFX effect using afxScriptEventData. They are useful for implementing high-level scripted side-effects such as character resurrection and teleportation.
Script Event methods now include a 7-value transform argument in place of a 3-value position used in previous versions. This exposes constraint orientations that can be useful for scripts that need to spawn new objects at a constraint determined position and orientation.
- Networking: server only
SG Light Object - sgLightObjectData
The flexible sgLightObject (formerly sgUniversalStaticLight) can be used as an AFX building-block effect. It has many more options than the basic Lighting Effect, including flares.
sgLightObject is not supported on Torque 3D and must be replaced by alternative T3D-specific lighting effects.
- Networking: client only
Sound Effect - AudioProfile, SFXProfile
AFX supports audio effects using standard Torque AudioProfile (or SFXProfile) datablocks which in turn utilize AudioDescription (or SFXDescription) datablocks. Audio effects are created from profiles using alxPlay() and managed internally. AFX dynamically controls an audio effect’s 3D location and when it shuts off, possibly with a fade out. Both looping and one-shot sound effects are supported.
Although the SFX audio system used by TGEA and Torque 3D is not available for TGE, SFXProfile and SFXDescription fields are nearly identical to AudioProfile and AudioDescription. To facilitate cross-engine effect design, SFXProfile and SFXDescription can be used with TGE as synonyms for AudioProfile and AudioDescription.
- Networking: client only
StaticShape - StaticShapeData, afxStaticShapeData
Stock Torque StaticShapes can be used as an AFX building-block effect. For passive client-only effects, afxModel is usually preferred, but when you need to place an effect model on the server you can use a StaticShape. This may be necessary for objects that are vulnerable to collisions or those that provide mount points for projectiles.
New in AFX 2: With afxStaticShapeData, a subclass of StaticShapeData, the Static Shape can be configured to spawn and become a permanent part of the scene.
- Networking: server ghosted
Volume Light - afxVolumeLightData
Torque Volume Lights can be used as an AFX building-block effect. These lighting effects add geometry-based effects to a base SG Light Object effect. The VolumeLight object is not usually created from a datablock, but the AFX afxVolumeLightData can be used.
Volume Lights are not supported on Torque 3D. (maybe)
- Networking: client only
Zodiac - afxZodiacData
AFX includes a very useful decal-like effect called a Zodiac. Zodiacs are special purpose decal textures, often circular, that are always projected vertically onto the ground. Parameters control dynamic rotation and scale as well as texture, color, and blending style.
Zodiacs are very effective as rune lighting rings that rotate below a magic user while casting a spell. They are also useful for explosion shockwaves, scorched earth stains, and selection indicators.
Zodiacs work on terrain, atlas, interiors, and polysoup-enabled dts models. Interior zodiacs have controls for limiting the vertical range of a zodiac and whether this range scales when the zodiac changes size.
Zodiacs can fade out based on distance from the camera and they can fade out and/or shrink based on an altitude setting above the nearest terrain or interior.
Zodiacs now have settings to filter their rendering according to the angle gradient of interior and polysoup polygons.
Zodiac rendering can now be disabled on individual terrain, atlas, interior, and polysoup objects.
With TGEA, Zodiacs can be prevented from rendering in reflections or rendered exclusively in reflections, or both.
- Networking: client only
Zodiac Plane - afxZodiacPlaneData
A Zodiac Plane is like a regular Zodiac, but instead of projecting the texture onto an interior or terrain, the texture is mapped onto a square polygon object that can be positioned and transformed arbitrarily in the scene. Zodiac Plane duplicates many of the fields used by Zodiac effects and wherever possible, also duplicates their resulting behaviors.
- Networking: client only
- New in AFX 2
Previous: User Guide: Hierarchy and Workflow
