Upkeep : T3D Engine Modifications
In order to make T3D and AFX work together, a number of code modifications are made to T3D source files. Other changes were made so that AFX features could be demonstrated using an RPG-style interaction model in the AFX Demo. This section describes each of these changes and why they were made.
Specific game applications may not require all of these changes, but you should be very careful when leaving any of them out. You should especially try to maintain compatibility with all effect types so you can make use of future effects from users and content packs.
Changes that you can fairly easily leave out according to preference are marked with an * in the table below. Other changes should be included if possible.
Modifications by Topic
afxModel Type *
Adds a new object type which allows you to differentiate afxModels from other types in selections and collisions. Because the number of object types is very close to the limit, this change is disabled by default. It can be enabled by uncommenting AFX_CAP_AFXMODEL_TYPE in objectTypes.h and arcaneFX.h
- Search Term
- (afxModel-type)
- Files
- engine/source/T3D/objectTypes.h
Animation Clip
These changes add functionality to Player and AiPlayer that allow AFX Animation Clip effects to select animation sequences other than the one playing under normal conditions. They also allow Animation Clip and Animation Lock effects to temporarily block user control of Player objects.
- Search Term
- (anim-clip)
- Files
- engine/source/T3D/aiPlayer.cpp
- engine/source/T3D/aiPlayer.h
- engine/source/T3D/player.cpp
- engine/source/T3D/player.h
Camera Detection
This change adds the virtual method SceneObject::isCamera() which normally returns false, but is overridden by camera objects (such as Camera and afxCamera) to return true.
It is used by the AFX constraint system to determine when a constraint source is a camera and requires special handling.
- Search Term
- (is-camera)
- Files
- engine/source/sceneGraph/sceneObject.h
- engine/source/T3D/camera.h
Camera Speed *
This change adds the static method getMovementSpeed() to the standard Camera class. It returns the value of Camera::mMovementSpeed, a variable exposed to script as $Camera::movementSpeed.
The afxCamera class determines its own movement speed from the value returned by Camera::getMovementSpeed(). This makes it responsive to camera speed changes made by users such as in the world editor.
- Search Term
- (cam-speed)
- Files
- engine/source/T3D/camera.h
Canvas
This change adds the method, setConsumeLastInputEvent(). By setting a false value, a child control can handle an event but still allow the event to be passed on and also handled by the ActionMap.
Also added clearMouseButtonDown() and clearMouseRightButtonDown() for clearing "down" status of mouse buttons in cases where ActionMap grabs the mouse for dragging and blocks the up events from reaching GuiCanvas.
afxTSCtrl uses this functionality to detect mouse down events without modifying the normal behavior provided for these events by the ActionMap.
- Search Term
- (canvas)
- Files
- engine/source/gui/core/guiCanvas.cpp
- engine/source/gui/core/guiCanvas.h
Collision Events *
This modification adds functionality to ShapeBase that allows C++ code to register callbacks that will be called when ShapeBase::onCollision() is called.
This capability is used to implement AFX Collision Events.
- Search Term
- (collision-events)
- Files
- engine/source/T3D/shapeBase.cpp
- engine/source/T3D/shapeBase.h
Core
Depending on release, AFX requires one or more core functions to be inserted in key locations of the game application.
On T3D clients, arcaneFX::advanceTime() is called each frame from clientProcess(). It is important that this call is made before the advanceTime() calls are made for regular scene objects.
Previous engine versions required calls to arcaneFX::init() and arcaneFX::shutdown() from within initGame() and shutdownGame(). This is now handled transparently using the MODULE_BEGIN/MODULE_END macros.
- Search Term
- (core)
- Files
- engine/source/app/game.cpp
Datablock Caching *
Implements functionality used by the client datablock caching system. This feature is enabled by default, but can be disabled by commenting out AFX_CAP_DATABLOCK_CACHE in gameConnection.h.
- Search Term
- (db-cache)
- Files
- engine/source/T3D/gameConnection.cpp
- engine/source/T3D/gameConnection.h
- engine/source/T3D/gameConnectionEvents.cpp
Datablock Copy-on-reload *
This change extends the behavior of the TorqueScript datablock copy operator, ":". Normally the copy operator is only meaningful when a new datablock is created, in which case the fields of an existing datablock are used to initialize fields of a new datablock.
With this modification, fields of an existing datablock are used to initialize fields of another existing datablock when it is re-initialized during a script reload. It greatly increases the usefulness of effect script reloads, which can be done in AFXDemo by right-clocking on a spell button.
- Search Term
- (copy-on-reload)
- Files
- engine/source/console/compiledEval.cpp
Datablock Id Size *
This change increases the value of DataBlockObjectIdBitSize to accommodate a larger number of datablocks. The previous value of 10 limited the total number of datablocks to 1024, whereas the new value of 13 allows up to 8192 datablocks. (The AFX Demo currently creates over 4500 datablocks.) Bumping this value to 12 or 13 is recommended for any game using a large number of special effects.
Possible Side Effects: When datablock ids are transmitted across a network connection, the value of DataBlockObjectIdBitSize is used to pack them into a minimum number of bits. While increasing the value does increase the total number of bits transmitted, this amount will be small for most applications. (In the AFX Demo, for example, about 4500 datablock ids are transmitted during start-up and very infrequently after that. This means that increasing the id size by 3, increases the amount of data transferred by about 1.6 kilobytes.)
- Search Term
- (datablock-id-size)
- Files
- engine/source/console/sim.h
Datablock Temporary Cloning
SimObject is extended to allow some datablock subclasses to create temporary clones of themselves so that their fields can be modified without affecting the behavior of object instances referencing the original datablock.
A special copy constructor is added to a number of stock T3D datablock subclasses to enable them to create temporary clones.
The cloned datablocks are considered temporary in that they are primarily intended as a means to make late modification of datablock fields at the time the datablock is used to initialize the values of an object instance. The temporary datablock exists while the object it initializes exists and is deleted when the object is deleted.
- Search Term
- (datablock-temp-clone)
- Files
- engine/source/console/simObject.cpp
- engine/source/console/simObject.h
- engine/source/sfx/sfxDescription.cpp
- engine/source/sfx/sfxDescription.h
- engine/source/sfx/sfxProfile.cpp
- engine/source/sfx/sfxProfile.h
- engine/source/sfx/sfxTrack.cpp
- engine/source/sfx/sfxTrack.h
- engine/source/T3D/debris.cpp
- engine/source/T3D/debris.h
- engine/source/T3D/fx/explosion.cpp
- engine/source/T3D/fx/explosion.h
- engine/source/T3D/fx/particle.cpp
- engine/source/T3D/fx/particle.h
- engine/source/T3D/fx/particleEmitter.cpp
- engine/source/T3D/fx/particleEmitter.h
- engine/source/T3D/gameBase/gameBase.cpp
- engine/source/T3D/gameBase/gameBase.h
- engine/source/T3D/projectile.cpp
- engine/source/T3D/projectile.h
- engine/source/T3D/shapeBase.cpp
- engine/source/T3D/shapeBase.h
- engine/source/T3D/staticShape.cpp
- engine/source/T3D/staticShape.h
Enhanced Field Management
These changes extend the way fields of scripted objects are handled. In particular it allows dynamic fields with particular prefixes to be copied to another object.
- Search Term
- (enhanced-field-mgmt)
- Files
engine/source/console/simFieldDictionary.cpp engine/source/console/simFieldDictionary.h engine/source/console/simObject.cpp engine/source/console/simObject.h
Enhanced Projectile
These modifications extend the stock Projectile class for better control of collision-masks and source object timeouts.
- Search Term
- (enhanced-projectile)
- Files
- engine/source/T3D/projectile.cpp
- engine/source/T3D/projectile.h
Fade GUI Control
Adds potential fading control to GuiControl objects which is used by AFX Gui Controller effects.
- Search Term
- (fade-gui-ctrl)
- Files
- engine/source/gui/core/guiControl.cpp
- engine/source/gui/core/guiControl.h
Ground Cover *
Adds AmbientModulationBias field to fxFoliageReplicator. It allows adjustment to the amount foliage lighting is modulated by the sun's ambient. In some situations, this can avoid foliage lighting that becomes too dark or too light.
- Search Term
- (ground-cover)
- Files
- engine/source/T3D/fx/fxFoliageReplicator.cpp
- engine/source/T3D/fx/fxFoliageReplicator.h
Inspect Substitutions *
These changes are a work-in-progress and are disabled by default. They implement customizations to some GUI elements used by the editors such that the substitution statement extension to TorqueScript is recognized and can be manipulated in some editors.
- Search Term
- (inspect-subs)
- Files
- engine/source/gui/editor/guiInspector.cpp
- engine/source/gui/editor/guiInspector.h
- engine/source/gui/editor/inspector/group.cpp
Light Visualization *
In stock T3D, when $Light::renderViz is true, any lights derived from LightBase will render reference geometry (such as cones and spheres) to help visualize the range settings for each light.
With these changes, the same concept can be applied on a per light basis using the localRenderViz field of afxT3DLightBaseData derived datablocks (afxT3DPointLightData and afxT3DSpotLightData).
- Search Term
- (localRenderViz)
- Files
- engine/source/T3D/lightBase.cpp
- engine/source/T3D/lightBase.h
Model Bounding-box Check *
This change adds the field, silentBBoxValidation, to ShapeBaseData datablocks. It is simply a boolean field that can be used to turn off a console error for certain objects with an invalid collision bounding box.
- Search Term
- (bbox-check)
- Files
- engine/source/T3D/shapeBase.cpp
Object Selection
Adds object selection capabilities including:
- flags to mark selection status of SceneObject classes
- methods for managing selections in GameConnection classes
-
raised ambient lighting for rollovers in sgLightingManager - raycasts that don't ignore corpses in Player classes. .
- Search Term
- (obj-select)
- Files
- engine/source/sceneGraph/sceneObject.cpp
- engine/source/sceneGraph/sceneObject.h
- engine/source/T3D/gameBase/gameConnection.cpp
- engine/source/T3D/player.cpp
- engine/source/T3D/player.h
Packet Overflow Checks
Adds the BitStream::getMaxWriteBitNum() method which exposes a value that indicates the maximum amount of data that can be written to a single packet.
This method is used by AFX objects afxMagicSpell and afxEffectron to warn when the amount of networked dynamic field data in an object might cause a packet overrun. Such overruns are not normally a problem with stock T3D but other AFX modifications introduce the ability to propagate some dynamic fields to clients for use with launch-time effect parametrization.
- Search Term
- (packet-overflow-checks)
- Files
- engine/source/core/stream/bitStream.h
Particle System Enhancements
AFX modifies the stock particle system in many way. These modifications are described in more detail in the Particle System Modifications section later in this document.
- Search Term
- N/A
- Files
- engine/source/T3D/fx/particle.cpp
- engine/source/T3D/fx/particle.h
- engine/source/T3D/fx/particleEmitter.cpp
- engine/source/T3D/fx/particleEmitter.h
PhysicalZone Enhancements
Adds radial style PhysicalZones with spherical and cylindrical shapes, and allows orientation of standard vector forces using the PhysicalZone transformation.
- Search Term
- (enhanced-physical-zone)
- Files
- engine/source/T3D/containerQuery.cpp
- engine/source/T3D/physicalZone.cpp
- engine/source/T3D/physicalZone.h
PhysicalZone Optimizations
Adds network optimizations to PhysicalZones now that they are more likely to move around dynamically.
- Search Term
- (pz-opt)
- Files
- engine/source/T3D/physicalZone.cpp
- engine/source/T3D/physicalZone.h
Player Foot Switch *
Extends Player object to allow built-in footstep effects (footprint decals, dust particles, and footfall sounds) to be turned on and off by external code.
This capability is utilized by AFX FootSwitch effects which are useful when one wants to replace the built-in Player effects with AFX alternatives.
- Search Term
- (foot-switch)
- Files
- engine/source/T3D/player.cpp
- engine/source/T3D/player.h
Player Look *
These changes allow you to disengage the Player's head and arm animation from the view direction which is something you don't want in a 3rd person, RPG-style camera model.
- Search Term
- (player-look)
- Files
- engine/source/T3D/player.cpp
- engine/source/T3D/player.h
Player Movement *
Extends Player class to recognize speed bias and movement amounts as applied by AFX Player Movement effects.
- Search Term
- (player-movement)
- Files
- engine/source/T3D/player.cpp
- engine/source/T3D/player.h
Player Puppet *
This change alters the Player class so that Player Puppet effects can manipulate its position and orientation via the AFX constraint system.
- Search Term
- (player-puppet)
- Files
- engine/source/T3D/player.cpp
- engine/source/T3D/player.h
Polysoup Type
With this change, when usePolysoup is set to true on a TSStatic it also becomes the new type, PolysoupObjectType, which is useful for collision testing and camera avoidance.
- Search Term
- (polysoup-type)
- Files
- engine/source/T3D/objectTypes.h
- engine/source/T3D/tsStatic.cpp
Process Ordering
Adds functionality that allows effects to position themselves in the processing lists after objects they are constrained to.
- Search Term
- (process-order)
- Files
- engine/source/T3D/gameBase/processList.cpp
- engine/source/T3D/gameBase/processList.h
Radius Search *
Adds Container::getRadiusSearchList() method which is used by AFX Area Damage effects as a fast alternative to scripted calls to the initContainerRadiusSearch() console function.
- Search Term
- (radius-search)
- Files
- engine/source/sceneGraph/sceneObject.h
Reload Reset
This change adds the virtual method SimObject::reloadReset() which does nothing by default, but can be overridden by datablock classes that need to be notified when reinitialized as part of a script reload.
Generally it's required by classes like afxMagicSpellData that implement special fields like addCastingEffect to set multiple values of an internal dynamic array.
- Search Term
- (reload-reset)
- Files
- engine/source/console/simObject.h
Scope Tracking
Adds functionality used to keep track of constraint objects on clients when they leave scope and then return.
- Search Term
- (scope-tracking)
- Files
- engine/source/sim/netObject.cpp
- engine/source/sim/netObject.h
- engine/source/T3D/gameBase/gameBase.cpp
- engine/source/T3D/gameBase/gameBase.h
SFX Legacy *
Defines convenience classes so that AudioDescription and AudioProfile can be used as synonyms for sfxDescription and sfxProfile. While it's recommended that you switch to using the SFX objects, these are useful when testing and porting older scripts.
- Search Term
- (sfx-legacy)
- Files
- engine/source/sfx/sfxDescription.cpp
- engine/source/sfx/sfxProfile.cpp
Substitution Statements
TorqueScript is extended to allow substitution statements. With these changes, some datablock fields can be specified with an alternative string with a leading "$$" which is known as a substitution statement. A substitution statement is essentially a single line of script that can be evaluated to produce a substitute value for the field.
Substitution statements are typically evaluated on cloned datablocks, just before the datablock is used to instantiate an object.
This set of changes includes modifications to stock T3D datablocks: Explosion, Debris, ParticleEmitter, Projectile, SFXProfile, and ShapeBase, so that they can be better manipulated using substitutions.
- Search Term
- (substitutions)
- Files
- engine/source/console/compiledEval.cpp
- engine/source/console/consoleObject.cpp
- engine/source/console/consoleObject.h
- engine/source/console/simDatablock.cpp
- engine/source/console/simDatablock.h
- engine/source/console/simObject.cpp
- engine/source/sfx/sfxProfile.cpp
- engine/source/T3D/debris.cpp
- engine/source/T3D/fx/explosion.cpp
- engine/source/T3D/fx/particleEmitter.cpp
- engine/source/T3D/projectile.cpp
- engine/source/T3D/shapeBase.cpp
Texture Tag Remapping
Adds functionality which allows remapping of texture tags to new values at runtime.
- Search Term
- (remap-txr-tags)
- Files
- engine/source/materials/materialList.cpp
- engine/source/T3D/shapeBase.cpp
- engine/source/T3D/shapeBase.h
Triggers
These changes add support for triggered effects, including detection of dts animation triggers and standard Player movement triggers. Also added are special Player triggers that detect jumping, landing, and idles states.
- Search Term
- (triggers)
- Files
- engine/source/T3D/player.cpp
- engine/source/T3D/player.h
- engine/source/ts/tsShapeInstance.h
Visibility Features
Customizes visibility features related to object fading and animated transparency levels.
- Search Term
- (vis-feat)
- Files
- engine/source/T3D/shapeBase.cpp
Zodiacs
Adds changes for rendering AFX "zodiac" decals on regular terrain, dif interiors, and polysoup-enabled tsStatic models.
Possible Side Effects: Zodiac rendering does effect performance depending on how many zodiacs are active and how large they are. When no zodiacs are active, these changes have very little effect on the rendering performance of terrain and interiors.
- Search Term
- (interior-zodiacs)
- Files
- engine/source/interior/interior.h
- engine/source/interior/interiorCollision.cpp
- engine/source/interior/interiorInstance.cpp
- engine/source/interior/interiorInstance.h
- engine/source/interior/interiorRender.cpp
- Search Term
- (polysoup-zodiacs)
- Files
- engine/source/T3D/tsStatic.cpp
- engine/source/T3D/tsStatic.h
- Search Term
- (terrain-zodiacs)
- Files
- engine/source/terrain/terrCell.cpp
- engine/source/terrain/terrCell.h
- engine/source/terrain/terrData.cpp
- engine/source/terrain/terrData.h
- engine/source/terrain/terrRender.cpp
- engine/source/terrain/terrRender.h
Zoned In
Adds a flag to GameConnection class to indicate when a client is fully connected or "zoned-in". A client is "zoned-in" when the connection process completes and the client is ready to interact with the user. This information determines when AFX will startup active effects on a newly added client.
- Search Term
- (zoned-in)
- Files
- engine/source/T3D/gameBase/gameConnection.cpp
- engine/source/T3D/gameBase/gameConnection.h
