Skeleton Files ‐ Reflex3 Constraints - Kamzik123/AnvilToolkit-Resources GitHub Wiki
Reflex3 Constraints will be editable for Mirage in AnvilToolkit v1.3.5
This page documents the Reflex3 constraint system used in newer Assassin's Creed titles (Origins, Odyssey, Valhalla, Mirage). Reflex3 constraints are a separate system from the older BoneModifier constraints — they live in dedicated Reflex3SkeletonConstraints data attached to skeleton files.
Reflex3 provides a richer constraint evaluation pipeline with support for constraint lists, expression-based position/rotation drivers, cloth simulation, measurement constraints, and more.
Game support: Reflex3 constraints are present from AC Origins onward. The constraint data format has evolved across titles — the toolkit handles the Mirage (v2) format, with partial support for older versions.
Table of Contents
Overview: How Reflex3 Constraints Are Stored
Reflex3 constraints are stored in a hierarchical structure:
Reflex3SkeletonConstraints (top-level wrapper in the skeleton file)
└── Reflex3SkeletonConstraint[] (one or more constraint sets)
├── ReflexVersion (engine version that built this data)
└── Constraints[] (individual constraint definitions)
├── ConstraintID (type — see table below)
├── ConstraintVersion (version of this constraint's data format)
├── SortDepth (evaluation order priority)
└── [type-specific data]
Each constraint set contains a StateBuffer — a pre-compiled runtime cache that the engine uses to skip rebuilding constraints from scratch. The toolkit clears this on export, forcing the engine to rebuild from the constraint data.
Common Fields
Every constraint shares these base fields:
| Field | Type | Description |
|---|---|---|
ConstraintID |
int | The constraint type (0–16, see table below) |
ConstraintVersion |
int | Data format version for this constraint type |
SortDepth |
int | Evaluation order — lower values are evaluated first |
Most constraints also contain:
| Field | Type | Description |
|---|---|---|
Common |
ConstraintCommon | Contains SortDepth and LOD (level of detail threshold) |
ConstrainedObject |
BoneInfo | The bone being constrained — BoneID, ParentBoneID, and InitTransform (4x4 matrix) |
Targets |
BoneInfo[] | One or more target bones that drive the constraint |
Constraint Types
Attachment (ID 0)
Attaches a bone rigidly to one or more target bones with blend weights. Used for attaching equipment, weapons, or accessories to character bones.
| Field | Description |
|---|---|
PreSkinTransform |
Matrix applied before skinning (v2 only) |
ConstrainedObject |
The bone being attached |
Targets |
Target bones, each with an AffectMask (which transform channels are affected), a PreSkinTransform, and a Weight |
BallJoint (ID 1)
A spherical joint constraint that limits a bone's rotation relative to a socket bone. Used for realistic joint limits on limbs, heads, or physics objects. Includes a convex hull that defines the allowed rotation volume.
| Field | Description |
|---|---|
Socket |
The parent/socket bone |
Target |
The target bone |
SocketIsParentOfTarget |
Whether the socket bone is a direct parent |
ConstrainedObjects |
List of constrained bones, each with pose data |
Facets |
Convex hull facets defining the allowed rotation region (normal, vertices, barycentric data) |
PoseIndices |
Per-pose index mapping |
BoundingVolume (ID 3)
Constrains a bone to stay within or orient toward bounding volumes defined by target bones. Used for keeping bones within valid spatial regions.
| Field | Description |
|---|---|
ConstrainedObject |
The bone being constrained |
LookAtOffset |
Angular offset for look-at behavior |
ConstraintMode |
How the constraint is applied |
Targets |
Target bones with bounding volume data (Data vector), CollisionMode, and Type |
ConstraintList (ID 4)
A container that groups multiple sub-constraints together. Sub-constraints are stored inline using the same binary header format as top-level constraints. The list evaluates all contained constraints as a group.
| Field | Description |
|---|---|
Common |
Sort depth and LOD |
SubConstraint |
A nested Reflex3SkeletonConstraint containing the sub-constraints |
DoubleBallJoint (ID 5)
An extension of BallJoint that uses two socket-target pairs for more complex joint behavior. Each pair has its own convex hull defining the allowed rotation space.
| Field | Description |
|---|---|
Socket0, Socket1 |
Two socket bones |
Target0, Target1 |
Two target bones |
SocketIsParentOfTarget0/1 |
Parent relationship flags |
ConstrainedObjects |
Constrained bones with pose vectors per socket-target combination |
ConvexHull0, ConvexHull1 |
Two convex hulls (facets + pose indices), one per socket-target pair |
HingeVector (ID 6)
A hinge constraint that limits rotation to a single axis, like a door hinge. Supports angle clamping, distance weighting, and gravity-influenced rotation.
| Field | Description |
|---|---|
ConstrainedObject |
The bone being hinged |
OrientationNode |
Bone defining the hinge orientation |
Info |
Hinge parameters: AffectLocalTransform, UsingAngleClamp/Weight, UsingDistanceWeight, LocalRotationOffset/Axis, LocalGravityAxis, min/max angle and distance, start/end angle |
Targets |
Target bones with blend weights |
LookAt (ID 7)
Points a bone toward one or more target bones. Used for eye tracking, head turning, weapon aiming, and turret behavior.
| Field | Description |
|---|---|
ConstrainedObject |
The bone that rotates to look |
Offset |
Quaternion rotation offset |
UpNode |
Bone defining the "up" direction |
UseInitialOffset |
Whether to apply the initial offset |
UseWorldAsUpnode |
Use world up instead of a bone |
AlignType |
How the look-at alignment is computed |
LookAtAxis, UpNodeAxis, SourceAxis |
Axis definitions for the look-at calculation |
Targets |
Target bones with blend weights |
Measurement (ID 8)
Measures distances, angles, or other spatial relationships between bones. Used for procedural adjustments based on bone positions (e.g., foot placement, IK).
| Field | Description |
|---|---|
MixingMode |
How measurements are combined |
ConstrainedObjects |
Bones being measured, each with pose rotation and position |
Measurements |
Measurement entries, each with: MeasurementType (0–3), FirstTarget/SecondTarget bones, Length, Width, MinimumRange, MaximumRange, Inverted flag |
Orientation (ID 9)
Blends a bone's orientation toward one or more target bones. Similar to LookAt but operates on the full rotation rather than a look direction.
| Field | Description |
|---|---|
ConstrainedObject |
The bone being oriented |
UseInitialOffset |
Keep initial rotation offset |
UseLocalTransform |
Operate in local space |
Offset |
Quaternion offset |
Targets |
Target bones with blend weights |
Physics (ID 10)
Adds physics simulation to a bone — spring-based sliding, pendulum swinging, gravity, wind, and collision. Used for hair, cloth strips, weapon sway, and dangling objects.
| Field | Description |
|---|---|
ConstrainedObject |
The simulated bone |
UseSlide / SlideX/Y/Z |
Enable per-axis sliding with SlideMax/SlideMin limits |
UseSwing |
Enable pendulum swing |
Gravity |
Gravity strength |
UseGravityNode / GravityNode |
Custom gravity direction from a bone |
IsGravityLocal |
Gravity in local or world space |
WindFactor |
Wind influence strength |
SlideInfoOptimized |
Spring and damping constants for sliding |
SwingInfoOptimized |
Center of mass, damping, swing limits for swinging |
EvaluationVersion |
Physics solver version (v2+) |
SwingAxis |
Custom swing axis (v3+) |
Position (ID 11)
Constrains a bone's position to match one or more target bones, with optional offset and blend weights.
| Field | Description |
|---|---|
ConstrainedObject |
The bone being positioned |
UseInitialOffset |
Keep initial position offset |
Offset |
Position offset vector |
Targets |
Target bones with blend weights |
RotationExpression (ID 12)
Drives a bone's rotation using mathematical expressions based on another bone's rotation. Allows per-axis control with multipliers, offsets, and limits. Used for procedural secondary motion (e.g., eyebrow raises driven by jaw rotation).
Fixed 412-byte buffer containing:
| Field | Description |
|---|---|
ConstrainedObject |
The driven bone |
Target |
The source bone whose rotation is read |
Info |
Expression parameters: per-axis Enable flags, TargetSet/KeepInitialOffset flags, TargetAxes mapping, InitialLocalRotationEuler, OffsetRotationEuler, Multiply vector, MathsEnable/MathsTargetMultiply/MathsOffsetRotationEuler for additional math operations |
LimitInfo |
Per-axis rotation limits: Minimum/Maximum vectors, Enable flags, and maths-based limit extensions with tangent values |
PositionExpression (ID 14)
Drives a bone's position using mathematical expressions based on another bone's position. The position equivalent of RotationExpression.
Fixed 312-byte buffer containing:
| Field | Description |
|---|---|
ConstrainedObject |
The driven bone |
Target |
The source bone whose position is read |
Info |
Expression parameters: InitialTargetPosition, Multiply vector, per-axis TargetAxis mapping, HasTarget, EnableLimit flags |
InfoOptimized |
Pre-computed results: TargetModifierResult matrix, AxisMask, LimitMin/LimitMax, TargetInitialEffect, AdditiveMode |
Cloth (ID 15)
Full cloth physics simulation. The most complex constraint type — defines a soft-body mesh with particles, springs, triangles/quads, collision volumes, skinning, and per-vertex properties.
The cloth version (1–4) determines the data format. Version 4 adds a GravityNode bone and SMotion physics data.
| Field | Description |
|---|---|
Technology |
Cloth solver technology identifier |
Gravity |
Gravity direction/strength vector |
GravityNode |
Bone for custom gravity direction (v4 only) |
Outputs |
Cloth vertices — each with BoneInfo, two transform matrices, and ParentIndex for the cloth hierarchy |
Triangles |
Triangle face indices (3 × uint16 per triangle) |
Quads |
Quad face indices (4 × uint16 per quad) |
Colliders |
Collision shapes — BoneInfo, Type, Radius, SecondRadius, HalfExtents, HalfLength, and Offset matrix (v2+) |
LimitArrays |
Per-output rotation/position limits — each with Type, Radius, HalfExtents, HalfLength, Offset matrix |
SkinBones |
Skinning bones — BoneInfo with local and parent transform matrices |
Skins |
Per-output skinning — bone index and weight arrays |
Properties |
Per-property settings — IsEnabled, GlobalValue, UseGlobal, and per-bone float values |
SMotionData |
Raw SMotion physics solver data (spring/particle simulation, v3+) |
Offset (ID 16)
Applies a static positional offset to one or more bones. Version 1 supports a single target, version 2 supports multiple.
| Field | Description |
|---|---|
Common |
Sort depth and LOD |
Targets |
Target bones, each with BoneInfo, OffsetA, and OffsetB vectors |
Container Structure
The binary container uses a versioned header:
| Field | Size | Description |
|---|---|---|
| Magic | 4 | 0x12B6441 |
| Version | 4 | Always 2 |
| ReflexVersion | 4 | Engine version that built this data (varies per game/build) |
| ConstraintCount | 4 | Number of constraints |
| StateBufferSize | 4 | Size of pre-compiled state cache (cleared on toolkit export) |
| Reserved | 16 | Four reserved uint32 fields (always 0) |
| StateBuffer | var | Pre-compiled state data (cleared on export — engine rebuilds from constraints) |
| Constraints | var | Individual constraint data blocks |
Each constraint block has a per-constraint header:
| Field | Size | Description |
|---|---|---|
| Magic | 4 | 0x12B3B2C |
| ConstraintID | 4 | Constraint type |
| ConstraintInstanceId | 16 | Runtime instance identifier (regenerated on export) |
| ConstraintVersion | 4 | Data format version |
| LOD | 4 | Level of detail |
| SortDepth | 4 | Evaluation order |
| BodySize | 4 | Size of constraint-specific data |
| Body | var | Constraint-specific data |