User Guide: Constraint System
From AFXWiki
Contents |
When designing special effects, one of the best sources for animation is other animated objects. The AFX constraint system allows you to directly “borrow” the animation of other objects and use it to place and move your effects. Each effect wrapper specifies three separate constraints: a primary position constraint for constraining to a 3D location, an orientation constraint for constraining to an orientation or bearing, and a secondary position constraint often used to aim an effect towards the camera or some other target.
Constraint Sources
Constraint sources are existing objects or points that have an established position and possibly an orientation as well. Using fields of afxEffectWrapperData, you can separately constrain an effect's position and orientation to one or more constraint sources.
The constraint system supports three different types of constraint sources: point constraints, transform constraints, and object constraints. A point constraint is a fixed point in space. Spell effects that are active after the spell impacts a target can be constrained to the impact position, which is a point constraint. A transform constraint is fixed like a point constraint, but specifies orientation as well as position. An object constraint is the origin of a scene object or another effect. Effects can be constrained to a spell's missile projectile which is an object constraint. Object constraints that are subclasses of ShapeBase also allow constraining to one of the shape's named hierarchical nodes. The spellcaster character is a subclass of ShapeBase, so effects can be constrained the the spellcaster's origin, or to one of its named nodes such as a hand or a foot.
Each effects choreographer specifies a convenient set of predefined constraint sources most useful for constraining that choreographer's effects. At a minimum, constraint sources corresponding to the camera and audio listener are provided, but most choreographers provide more. The tables below summarize predefined constraint sources for several kinds of choreographers.
Predefined Constraint Sources
afxMagicSpell
- caster
- Object that is casting the magic spell, usually an object derived from Player of AiPlayer, but can be any ShapeBase derived object.
- target
- Object that the spell is targeting. Not all spells require a target, so you should only use this constraint source in spells that require one.
- missile
- The magic missile projectile used to deliver the magic to a target for some types of spells. It exists during the Delivery stage of the spell. Not all spells have a missile, so you should only use this constraint source in spells that do.
- camera
- This is the camera and its location is unique to each client. It is useful to specify the camera as a secondary position constraint and use an Aim transform modifier to point effects towards it.
- listener
- This is the audio listener and like the camera, its location is unique to each client. It is useful for coordinating the location of certain kinds of sound effects with the listener location.
- impactObject
- This is an object impacted by the spell. Often it is the same as the target but not always. It does not exist until the spell's impact event is reached.
- impactPoint
- This is a specific 3D location of an impact. It does not exist until the spell's impact event is reached.
afxSelectron
- selected
- The selected scene object which the selectron is going to highlight.
- camera
- This is the camera and its location is unique to each client. It is useful to specify the camera as a secondary position constraint and use an Aim transform modifier to point effects towards it.
- listener
- This is the audio listener and like the camera, its location is unique to each client. It is useful for coordinating the location of certain kinds of sound effects with the listener location.
- freeTarget
- When in free-targeting mode, this constraint source provides the current location of the free target. Effects constrained to this position will move around and provide feedback to the user about free target's current location.
afxEffectron
- camera
- This is the camera and its location is unique to each client. It is useful to specify the camera as a secondary position constraint and use an Aim transform modifier to point effects towards it.
- listener
- This is the audio listener and like the camera, its location is unique to each client. It is useful for coordinating the location of certain kinds of sound effects with the listener location.
User-defined Constraint System
Additional user-defined constraint sources can be specified dynamically at the time an effects choreographer instance is created. These constraint sources behave identically to predefined constraint sources and effect wrappers refer to them in the same way.
afxChoreographer::addConstraint(%consSrc, %consName)
Use addConstraint() to add a user-defined constraint source to an instance of an effects choreographer. Can be used with afxMagicSpell, afxSelectron, and afxEffectron choreographers.
Syntax
- %consSrc
- Specify an existing scene object to use as a constraint source. You can alternatively specify a fixed point constraint in the form of a three-valued xyz position, or a fixed seven-valued transform.
- %consName
- A name which effect wrappers use to refer to the added constraint source. (Avoid using names like "camera" that conflict with a choreographer's predefined constraint source names.)
Returns
- No return value.
Notes
- Must be called immediately after the choreographer instance is created. It can be called inside an onActivate() callback, or using the object returned by the call that initiated the choreographer, (such as castSpell() for afxMagicSpells).
- The given scene object must exist at the time this method is called.
Specialized Constraint Sources
There are three other types in addition to predefined and user-defined constraint sources: effect, ghost, and scene constraint objects. Instead of using a predefined name to refer to one of these types of constraint sources, you use one of the special keywords #effect, #ghost, or #scene, following each with an appropriate name.
#effect
Use #effect to constrain one effect to another effect within the same choreographer. Before you can use an effect as an #effect constraint source, you must give it a name using the afxEffectWrapperData effectName field and set its isConstraintSrc field to true.
Limitations
The effect constraint source must be in the same choreographer as the constrained effect. Server effects can only constrain to other server effects and client effects can only constrain to other client effects. (See #ghost below for a way to constrain client effects to a server effect.)
Effect constraint sources do not record history. (See Constraint History below.)
Notes
You can constrain an effect to any other effect belonging to the same choreographer, but for best results you should only constrain to effects that will be evaluated before the constrained effect. Your safest bet is to constrain to effects specified earlier in the same phrase.
#ghost
Use #ghost to constrain a client effect to the ghost of an effect created on the server by the same choreographer. Similar to #effect constraint sources, #ghost constraint sources are used to constrain a client effect to a server effect's ghost object.
Before you can use an effect as a #ghost constraint source, you must give it a name using the afxEffectWrapperData effectName field and set its ghostIsConstraintSrc field to true.
#scene
Use #scene to constrain an effect to an existing named scene object. Both client and server effects can be constrained to a #scene constraint object.
Constraint History
A powerful feature of the constraint system is constraint history. Constraint objects can be configured to record a short history of past positions and/or orientations. Both the length of history recorded and the sampling rate can be configured. Effects constrained to a constraint with history can refer to old values of the constraint within the recorded range.
Constraint history is useful for creating effects that follow behind another object. Constraint history is used in the spell Insectoplasm (AFX:SpellPack1), where model segments line up behind an erratically moving missile to form a giant centipede-like monster.
Previous: User Guide: Effects Choreographers
