User Guide: Transform Modifiers (Xmods)
While the AFX constraint system is very powerful, all you can really do with it by itself is hang your effects onto your characters and objects like ornaments on a Christmas tree. Usually, you want something a bit more dynamic than that, and in AFX you get more by using transform modifiers or xmods for short. An xmod is a simple code module that changes an effect’s current position and orientation constraint values. One xmod might move an effect’s position by a simple offset, another rotates the effect about an arbitrary axis, and yet another adjusts the effect's position vertically to a fixed height above the ground. By arranging xmods into a sequence of operations, you can achieve a large variety of procedural animation behaviors.
Xmods are used in effect wrappers and are arranged as a sequential list of modifiers, up to 32 modifiers per effect. Each modifier picks up where the last modifier left off and further modifies an effect’s positional or rotational constraint values. For example, use a small Local Offset followed by a Spin and your effect will spin on its own axis a short distance from its constraint position. Reverse the order, placing the Spin first, followed by the Local Offset, and your effect will orbit its constraint position at a distance determined by the offset.
Most xmods support four parameters that allow the modifier's influence to fade in and out: delay, lifetime, fadeInTime, and fadeOutTime. These parameters resemble the timing parameters used in effect wrappers, but instead of controlling visibility, they weight an xmod's influence. The delay field postpones the modifier's operation, which will have no influence during the delay duration. After delay, the modifier's influence will fade in over the fadeInTime duration. Lifetime determines the length of time the modifier is active, and fadeOutTime sets the duration of the modifier's influence fade out. Consider the World Offset transform modifier, which simply adds a 3D offset to an effect's position. Using influence settings, the effect will start at its constrained position, then gradually slide to the offset position during the fadeInTime. When lifetime expires, it then slides back to its constrained position during the fadeOutTime.
Xmods perform their operation over and over during the life of an effect, so, by design, they are kept as simple as possible.
Transform Modifier Summaries
afxXM_Aim
The effect’s current orientation is adjusted to face toward the effect’s secondary position constraint. By convention, an object faces in the direction pointed to by its local Y axis.
afxXM_AltitudeConform
As with afxXM_GroundConform, the effect's position is moved vertically to a specified height above the underlying terrain or interior structure, but its prior height or altitude is recorded in a way that some effects can utilize. Separate altitudes are recorded for underlying terrain and interiors.
Only Zodiac effects make direct use of altitude settings, but they are also saved by Mooring effects and can be referenced by Zodiacs constrained to the Mooring.
afxXM_BoxAdapt
Examines the bounding-box of the effect's position constraint object and measures the length of the largest XY dimension. This length is then used as a scale-factor for certain types of effects. For example, this modifier can be used to adapt the radius of a selectron's zodiac to the bounding-box size of the selected object.
afxXM_BoxConform
The effect’s position is adjusted to align with a specified side of its position constraint object's bounding-box.
afxXM_BoxHeightOffset
The effect's position is offset by the z-dimension of the position constraint object's bounding box plus a specified offset. This modifier if useful for placing effect objects over the head of characters that may vary in height.
afxXM_Freeze
An effect’s position, orientation, and/or secondary position constraint is sampled exactly once, and then repeated from then on, regardless of later changes in the constraints.
afxXM_GroundConform
The effect's position is moved vertically to a specified height above the underlying terrain or interior structure.
afxXM_LocalOffset
A local 3D offset is added to the effect’s current posConstraint location. To make the offset local, it is first reoriented using the effect’s current orientConstraint. Then the localized offset is added to the effect’s current location.
New in AFX 1.2: Local offset can be configured to apply to the secondary position.
afxXM_MountedImageNode
When you mount weapons or other items to a Player as mounted images (as opposed to mounted objects), you may want to constrain effects to a specific node of the mounted image. Mounted image meshes become a specialized intrinsic part of the ShapeBase they are mounted to and you cannot directly refer to their nodes using the AFX constraint-spec syntax.
afxXM_MountedImageNode provides a way to get around this limitation and allows you to specify a mount slot and a node name. Include it in the modifier list of an effect and that effect will be constrained to the specified node of the mounted image in the specified slot of the effects constraint source.
afxXM_Oscillate
The effect's position, orientation, and/or scale is set or offset to repeatedly swing between a minimum and a maximum value. The speed of the swinging can be set, as can the specific transformation to effect.
afxXM_PathConform
The effect’s current position is adjusted to conform to a specified path. It’s orientation may also be adjusted to orient to the path. The path is defined using an afxPathData datablock.
afxXM_PivotNodeOffset
DESCRIPTION NEEDED
afxXM_RandomRot
The effect's orientation is replaced with a random orientation falling within a specified phi and theta range. When using RandomRot to choose orientations on client effects, you will probably get different orientations for each client. If you need orientations that match across all clients, be sure to use RandomRot on a server-based effect.
afxXM_Scale
Adjusts the current scale of an effect by adding a scale offset. Unlike position and orientation, an effect's scale is not determined by a constraint source. The effect's scale is initially determined by the effect wrapper's scaleFactor, and can be subsequently modified by one or more instances of this transform modifier.
afxXM_Shockwave
Replaces the current effect position with one calculated along a linear path from the first position to the position of the secondary position constraint. Often used to move a Sound Effect at a constant rate toward the listener position so the sound reached the listener at the same time as an expanding shockwave texture ring.
afxXM_Spin
The effect’s current orientation is modified to rotate around a specified axis, at a specified rate and starting angle.
Random variances can be specified for both the starting angle and rate.
afxXM_VelocityOffset
DESCRIPTION NEEDED
afxXM_WaveScalar
Interpolates any of an effect's modifier parameters as it moves within a range of values. A variety of waveforms and other parameters are available to precisely control the way the parameter varies. afxXM_WaveScalar overlaps the functionality of afxXM_Oscillate, and generally offers increased flexibility and control.
afxXM_WaveRiderScalar
A special simplified variation of afxXM_WaveScalar, it must follow an instance of an afxXM_WaveScalar in an effect's modifier list. In which case, it will reuse the curve defined by previous afxXM_WaveScalar reducing some calculations. It is useful when more than one modifier parameter needs to follow a shared wave.
afxXM_WorldOffset
A 3D offset is added to the effect’s primary constraint position.
Previous: User Guide: Constraint System
