Since CRYENGINE 3.8 this document has been superseded by Attachment System Tutorial - Character Tool.
The character pipeline uses a character attachment system which allows to attach separate static objects to joints or directly to polygonal faces of a mesh and update them together with the animated character.
These are autonomous object that that can be replace or detached at run-time by the game-code and fall to the ground under gravity. It's also possible to use skin-attachments to replace entire body parts such as heads, hands, or upper and lower body.
Download and extract the file Attachment_exampleFiles.rar in your Objects directory. Example: <root>\GameSDK\Objects\Attachment_exampleFiles\Bone_attachment_simulateSocket
Bone-attachments are attached to a joint. The location can be ‘relative’ to a selected joint or they can be perfectly aligned with the selected joint if you click the checkbox "Align Bone Attachment".
Face-attachments are projected on the surface of the mesh (to only one particular triangle) and always stay on the surface of the mesh, even if the skinned mesh is deformed in extreme ways. The location of a face-attachment can be relative to a face. Bone-attachments don’t do that. Since SDK3.5 you can assign face-attachments to all meshes, even if these meshes are part of a skin-attachment.
Face-attachments allow faster prototyping. For bone attachments you need bone in the model and adding these bones is complex, time consuming and only tech-artists with Maya/Max installed can do it. Face attachments are easier to use for fast experimental setups and everyone can do it in CharEdit.
With skin-attachments we can replace body parts (head, hands, legs). Each skin-attachment can have its own character features (morph-targets). A skin-attachment can have NO animation. To animate the skin-attachment and deform its mesh, always use the skeleton-pose of the base-character.
There are several special-case names for attachments which define whether they appear in 1p or 3p. These are listed inside Player.cpp under SetupPlayerCharacterVisibility.
As an example, the reason the players head doesn't render in 1p is because it's called "head" in the character CDF, and "head" is defined as a ppThirdPersonPart in this file.
If you want to attach something to a character, the first step is to create an "empty" attachment-socket. A ‘socket’ is an attachment slot without anything in it. Empty sockets can also be used by the game-code to plugin (and process) typical game-objects like CEntityAttachment, CLightAttachment or CEffectAttachment. In such a case we use the attachment-system to actually update game-code. In the attachment window you can create a new attachment-socket, by selecting the type of attachment (Bone, Face or Skin).
It is also possible to change a face-attachment into a bone-attachment (and vice versa) after it was created. Just select a new type and click the "apply" button. Converting a skin-attachment into a bone or face doesn't make practical sense.
Object selection for the socket.
Material selection of the assigned object. The name of the material assigned to the object is shown here, with a button to browse and attach a different object “…” to the right. Dflt assigns a default material.
Deletes the assigned model from the attachment-socket. It doesn’t delete the socket itself.
Assign model to animation-socket (CGF or SKIN).
Hides the currently selected attachment. This feature can be set by default and saved in the file, but usually it’s a run-time feature.
The attachment system in SDK3.5.5 supports simulated movements of bone- and face-attachments. This type of animation is always a reaction to previous (primary) motion, that's why they are called secondary animations. This feature is an extension of an already existing system.
To approximate the physical movement of objects on characters we use the properties of springs and pendula:
Option | Description |
---|---|
Drop-down list | This features options for No Physics, PA_Cone, PA_HalfCone, PA_HingePlane and SA_Ellipsoid. All proxies starting with PA_ activate a pendulum simulation. |
Draw Setup | You can turn the debug setup on/off. If enabled is shows a green cone, half-code or a hinge-plane. |
Run Simulation | Activates the simulation. If deactivated, it shows the attached object in the default pose. |
Recommended FPS | Simulations with high stiffness values require a higher simulation update rate to guarantee a precise and stable simulation. You can choose values between 10-255. |
MaxAngle | Allows you to choose the opening angle for proxies like cone, half-cone or hinge-plane. |
Rotation | Rotates the hinge-plane, half-cone or ellipsoids. This has no visible impact on the cone. |
ScaleZP | Only active for springs. It scales the positive half of the spherical proxy. |
ScaleZN | Only active for springs. It scales the negative half of the spherical proxy. |
Mass | Defines the mass of the bob. As long as stiffness is 0, the mass has no impact on the period of oscillation. |
Gravity | The default value of 9.81m/sec is the standard acceleration of falling objects due to gravity on Earth. |
Damping | Fake the effects of air-resistance and friction. Higher dampening-value will make oscillating objects come to rest faster. |
Stiffness | Value between 0-999. A value of 0 has no stiffness at all and the pendulum will hang downward when it comes to rest. |
Pivot Offset | Adjusts the pivot rotation point. By default it's the pivot of the model, which is not always the natural simulation pivot. |
Simulation Axis | This is a vector with a direction and a length, which defines the default rod of the pendulum. This length of the rod has a big impact on the amplitude of the pendulum. |
Stiffness Target | This is a vector. By default its identical to the simulation axis (=rod of the pendulum). Stiffness Target is different for pendula and springs:
|
The socket is created as explained in part1 "Setup of attachment-sockets". Then you have to plugin a CGF into the socket.
The type, size and shape of the CGF (sword-sheath, pistol, dagger) will have no impact on the simulation, but it determines which setup you choose, because we can only mimic the behavior of a real physics object.
To add a dynamic simulation just open the RollupBar under "Simulate Socket" and select either PA_Cone, PA_Hinge, PA_HalfCone or SA_Ellipsoid. The first three are proxies to constraint the movements of a pendulum.
The last one (ellipsoid) constraints the movement of a spring. The ellipsoid is a sphere that you can mold like clay into an non-uniform ellipsoid, a half-sphere, a plane or a single line.
Now you have a physicalized socket which reacts to the movements of the character. You can visualize it with "Draw Setup".
Once you have the basic-setup, you can play around with the physics parameters (mass, gravity, dampening, stiffness). You can edit all these parameters while the character animations are playing and see the effects immediately.
To tweak the dynamics it is assumed that the user has a basic understanding of these parameters and their relationship.
Attach a static object with a collision triangle to an empty socket.
Example file: Objects\Attachment_exampleFiles\Bone_attachment_triangleCollision\leggun.cdf
Load the exported or downloaded LegGun.chr file and start adding a new empty socket. There we will attach a gun this time to simulate a “thigh” with a attached gun.
The issue here is that the cone for example could penetrate through the leg and the simulation would not look right without collision.
One solution would be to use the half cone but a bone driven solution would be better to make sure to get all movements covered.
For that we are able to assign to each socket 3 bones which are connected and build a collision plane (example for really long hair would be to add to each shoulder bones a “triangle bone” and one on the pelvis).
This feature needs to be added to the cdf file in a text editor we simple add a line which defines the bones for the collision triangle.
Let’s open the Objects\Attachment_exampleFiles\Bone_attachment_triangleCollision\leggun.cdf
file in a text editor.
Adding PA_Align0="bonename01" PA_Align1="bonename02" PA_Align2="bonename03" to an attachment will allow to draw the collision triangle.
The collision triangle will be created counterclockwise, that is why we start in the leggun.cdf with the bone triangle3 – triangle1.
The setup works only if you see a colored triangle in the area of the 3 bones. To test the asset you can simple drag in the cdf as a geomEntity in the level and move it with the gizmo around.
One more interactive example would be to replace the local player’s cdf. Download and replace the sdk_player.cdf with the existing one (or only in the .pak file) with GameSDK\Objects\characters\human\sdk_player\sdk_player.cdf.
In this case the simulated objects can be part of the character's mesh (rather than separated CGFs). The main motivation for this feature was the optimization of the render thread.
Because all simulated objects can be part of the mesh, we can add secondary animations without addition draw-calls. So if a model has 256 dangly objects, but all objects are part of the same mesh with the same material ID, then all of them will take only one single draw-call.
Reducing draw-calls is the most important thing if you want to optimize the render-thread. Because this is a very light-weight feature with only minimal impact on CPU, it will work perfectly on PS3 and X360.
To transfer the socket simulation onto a joint, first you need to create and physicalize the socket as explained in 2a).
In order to animate the joint directly (and everything that is skinned to that joint) you must leave the "object-field" empty and give the attachment-name the same name as the joint-name. Make sure that the attachment name is lower case.
You can use the "rename" functionality and click the “apply” button. With this simple trick we redirect the simulated animation to the joint and modify the whole character pose.
An update of a joint, is always a full update of the whole branch with all its children. This means we can use exactly the same system so simulate ropes: first we create a pendulum-simulator at the root of the chain, and then you add a new simulator for each link.
It is absolutely important that the rope-links have a child-parent relationship, or the simulation will not look correct.
Example file: Objects\Attachment_exampleFiles\JiggleJoint\jellyspoon.cdf
DCC setup (3ds max)
Example asset: Objects\Attachment_exampleFiles\JiggleJoint\jiggleJoint.max
Simple character setup with bones and a skinned geometry
Load the exported or downloaded example file JellySpoon.chr in the character editor, add one bone attachment and rename it to jelly1 like the name of the bone which you want to influence.
From there make sure to align a SA_Ellipsoid to the attachment and adjust the shape and properties to get a nice spring effect to simulate the jelly.
Example file: Objects\Attachment_exampleFiles\Pendulum_chain\PendulumChain.max
Example file: Objects\Attachment_exampleFiles\Pendulum_chain\pendulum_chain.cdf
In our example file we will simulate a metal chain a simple bone hierarchy with skinned geometry elements. The chain starts with the root and has 9 bones attached to it as a hierarchy each bone is linked to the next one.
The naming convention isn't important at this stage that is the beauty of this system it allows already existing and exported characters to be used for the simulation of their bones.
By default, the system uses the Y direction to simulate the pendulum therefore we have to make sure that the Y-axis is pointing in the direction of the simulation axis. But in the attachment panel you can set any axis as simulation axis.
Load the exported or downloaded example file Objects\Attachment_exampleFiles\Pendulum_chain\Pendulum_chain.chr
in the character editor and start adding new attachments.
We have to create an empty bone attachment which is using exactly the same name as the bone that we want to simulate for our example file. Please make sure that you create a bone attachment and name it exactly as the bone.
It is also really important to write all the names in lower-case otherwise the system won’t be able to recognize the bone. Apply the bone to the attachment by pressing the “Apply” button on the bottom of the attachment menu.
Next, you have to align the socket with simulated joint by clicking on the “Align with bone” button. Now we will enable the simulation by assigning a simulation primitive in the “simulate socket” menu.
Now you can play around with the physics parameters (mass, gravity, dampening, stiffness). You can edit all those parameters while the animations are playing and see the effects immediately.
You can also load your created .cdf into the forest level by dragging in the chr file as a geomEntity. The immediate update will only happen in the character editor but you are able to save the new changes to your .cdf and reload the scripts in the level to see it updating in the level.
Hinged character attachments use a fairly simple dedicated code (directly in the animation system) that can only handle one-hinge attachments with joint limits (they don't even handle collisions with the character or with other attachments).
To turn on dangling for a particular attachment, one has to specify 2 planes that form the edge used as a hinge. Planes are specified in the attachment's coordinate space. The first plane is the one the attachment "lies" on in its resting state, and the second is another plane it contacts with.
For the most typical attachment orientation, natural plane selection would be positive y, positive z (+y,+z).
Default attachment orientation corresponds to joint angle 0. The maximum rotation angle is specified as the "limit" property. Use the "damping" property to prevent the "pendulum effect" (values up to 10 are reasonable, but can go even higher when needed).
Note that the changes take effect only after you press Apply button.
The axis of the local coordinate system can be seen as normals on planes with the same name. The +y Axis is the normal to the +y plane. the -y Axis is the normal of the -y plane, +z is the normal on the +z plane (see color coding in the picture below).
In the example above, the +y and +z planes were chosen. The hinge axis is created between them.