Cloth Settings - Kamzik123/AnvilToolkit-Resources GitHub Wiki

This tutorial explains every setting in the ClothSettings files used by Assassin's Creed IV: Black Flag. ClothSettings control how simulated cloth (scarves, capes, coat tails, flags, etc.) behaves in the game -- how heavy it feels, how it reacts to wind, how it collides with the character's body, and more.

Game compatibility: This tutorial applies to pre-AC Unity titles -- from AC1 through AC Rogue. AC Unity overhauled the cloth simulation system with new settings and behavior, so this guide does not apply to Unity or any game released after it.

Example file: This tutorial references CHR_P_EdwardKenway_Scarf_ClothSettings.xml (Edward's scarf) exported with schema-based exporter as a working example throughout.

• How Cloth Simulation Works (Quick Overview)
• Settings Reference
  • Gravity
  • PreloadTime
  • WeightFactor
  • AirFrictionFactor
  • MinSphereRadius and MaxSphereRadius
  • RigidityScale
  • ConstraintFactor (Unused at Runtime)
  • NormalNormalMinCosine (Unused at Runtime)
  • WindFriction
  • WindRandomFactor
  • EnablePhysics
  • ProcessCollisions
  • UseWind
  • CollideWithPlane
  • RigidityUpVector
  • MaxCollisionCount
  • ConstraintIterationCount
  • UseWindAtVertices (Unused at Runtime)
  • UseGravityBone
  • GravityBoneID
  • GravityBoneScale
  • UseVelocityBone
  • VelocityBoneID
  • SkinningLinearVelocityFactor
  • SkinningAngularVelocityFactor
  • SkinningMaxFadeoutSpeed
  • MinSkinFactor and MaxSkinFactor
  • WeightUpwardVelocityFactor
  • MaxAdjustedWeightFactor
  • CollisionMode
  • MoveBackCollisionThreshold
• Tips for Modding

The game simulates cloth using a system called Verlet integration with distance constraints. Here's the simplified version:

1. Every frame, the game looks at each vertex (point) in the cloth mesh.
2. It applies forces like gravity and wind to push those vertices around.
3. It applies air friction to slow them down so they don't swing forever.
4. It runs a constraint solver that makes sure connected vertices don't drift too far apart (this is what prevents the cloth from stretching into spaghetti).
5. It checks for collisions against the character's body (approximated as capsule shapes around bones) and an optional flat plane, pushing any vertices that clip through back outside.
6. It blends between the simulated position and the original animation-driven ("skinned") position based on how fast the character is moving. This prevents the cloth from lagging behind dramatically during fast actions.

All of the ClothSettings values control different parts of this process.

<Vector3 Name="Gravity">( 0, 0, -4 )</Vector3>

The direction and strength of gravity pulling on the cloth. The three numbers are the X, Y, and Z components of the gravity vector.

• (0, 0, -4) means gravity pulls straight down along the Z axis at a strength of 4.
• For reference, real-world gravity would be about (0, 0, -9.8). The scarf uses -4 (roughly 40% of real gravity) to give it a lighter, more floaty feel.
• Setting this to (0, 0, 0) makes the cloth weightless -- it will just float in place.
• You can point gravity sideways or even upward for unusual effects.

<Float Name="PreloadTime">0</Float>

How many seconds of cloth simulation to run "invisibly" before the cloth appears on screen. This lets the cloth settle into a natural resting position before the player sees it.

• 0 means the cloth starts from its default rest pose immediately.
• A value like 1.0 would simulate 1 second of physics before showing the cloth, so it would already be hanging naturally when it appears.
• Useful if your cloth starts in an unnatural T-pose position and you want it to drape realistically from the start.

<Float Name="WeightFactor">0.07</Float>

How heavy the cloth feels. This multiplies the gravity force applied to each vertex.

• Lower values (like 0.07) = lighter cloth that floats and sways gently (silk, thin fabric).
• Higher values (like 0.5+) = heavier cloth that drops quickly and swings with momentum (thick leather, heavy canvas).
• 0 = the cloth is weightless and won't respond to gravity at all.

<Float Name="AirFrictionFactor">0.1</Float>

How much air resistance slows down the cloth each frame. Think of it as damping.

• 0 = no friction, the cloth swings back and forth endlessly like a pendulum in a vacuum.
• 0.1 = mild friction, the cloth swings freely but eventually settles. Good for scarves and light fabric.
• 0.5 = heavy friction, the cloth barely swings and comes to rest quickly. Good for thick, stiff materials.
• 1.0 = maximum friction, the cloth moves sluggishly as if underwater.

<Float Name="MinSphereRadius">0.03</Float>
<Float Name="MaxSphereRadius">0.06</Float>

Each vertex in the cloth mesh has an invisible collision sphere around it. These settings control the size range of those spheres.

• Larger spheres = the cloth stays farther away from the character's body. Prevents clipping but can look like the cloth is floating above the surface.
• Smaller spheres = the cloth hugs the body more closely. Looks more natural but risks clipping through the mesh.
• The actual radius for each vertex is set per-vertex in the cloth mesh data and clamped between these min and max values.
• The scarf uses small values (0.03-0.06) because it's a thin piece of fabric that should sit close to the body.

<Float Name="RigidityScale">1</Float>

Controls how strongly the cloth tries to maintain its original shape (the shape it has in the character's animation). Each vertex in the cloth mesh has its own rigidity value baked in, and this setting multiplies all of them.

• 1.0 = use the per-vertex rigidity values as designed.
• Higher than 1.0 = stiffer cloth that resists deformation and tries to stay near its animated position.
• Lower than 1.0 = floppier cloth that deforms more freely.
• 0 = no rigidity, the cloth is entirely driven by physics with no pull back toward the animated shape.

<Float Name="ConstraintFactor">1.05</Float>

This value is NOT used by the game engine at runtime. It is a build-time parameter used by Ubisoft's content tools when generating the cloth mesh data. It controls the maximum stretch ratio for distance constraints -- a value of 1.05 means constraints can stretch up to 5% beyond their rest length. Changing this value in the exported XML will have no effect in-game.

<Float Name="NormalNormalMinCosine">-1</Float>

This value is NOT used by the game engine at runtime. It is a build-time parameter for constraining how much adjacent vertex normals can diverge. A value of -1 means no restriction. Changing this in the exported XML will have no effect in-game.

<Float Name="WindFriction">0</Float>

How much the environmental wind pushes the cloth around. This multiplies the wind force from the game's wind system.

• 0 = the cloth is completely unaffected by wind, even if UseWind is true.
• Higher values = the cloth responds more strongly to wind. Try values between 0.1 and 1.0.
• The scarf uses 0, meaning it ignores environmental wind entirely.

<Float Name="WindRandomFactor">0</Float>

Adds random turbulence/flutter to the wind effect. Each frame, a random amount of variation is added to the wind direction for each vertex.

• 0 = wind blows uniformly (no flutter). Even if wind is enabled, there's no random variation.
• Higher values = more chaotic fluttering, as if the cloth is caught in gusty wind.
• Only has an effect if both UseWind is true and WindFriction is greater than 0.

<Bool Name="EnablePhysics">True</Bool>

The master switch for cloth simulation.

• True = the cloth is physically simulated (gravity, wind, collisions, etc. all apply).
• False = the cloth is not simulated at all. It rigidly follows the character's animation as if it were a static mesh piece. No swaying, no physics.

<Bool Name="ProcessCollisions">True</Bool>

Enables collision detection between the cloth and character body parts. The game approximates the character's body using capsule shapes (cylinders with rounded ends) placed along skeleton bones.

• True = the cloth will push away from the character's body when it touches it. Prevents the cloth from clipping through the torso, arms, legs, etc.
• False = the cloth passes straight through the character's body. It will clip through everything.

<Bool Name="UseWind">True</Bool>

Whether the wind system is active for this cloth.

• True = the cloth can be affected by the game's environmental wind. The actual amount of wind effect depends on WindFriction.
• False = wind calculations are skipped entirely.

Note: The scarf has UseWind=True but WindFriction=0, so wind is technically "on" but has zero effect. Setting UseWind to False would have the same visual result but skip some calculations.

<Bool Name="CollideWithPlane">False</Bool>

Enables collision against a flat plane surface attached to the character. This acts like an invisible floor that prevents the cloth from passing through it.

• True = the cloth will collide with a flat plane. The plane is positioned and oriented based on the character's position and orientation -- it moves and rotates with the character.
• False = no plane collision. The cloth can hang and swing in any direction freely.

When to use this:

• Capes and coats that rest on the character's back benefit from this. The plane prevents the cape from clipping through the character's backside or torso from behind.
• Hanging cloths, scarves, and ribbons that swing freely should leave this off, since a plane would restrict their natural movement.

Limitations:

• There is only one plane per cloth -- you can't define multiple collision surfaces.
• The plane is infinite -- it extends in all directions. It's not a bounded rectangle.
• The plane is attached to the character entity -- it rotates when the character rotates.

<Enum Name="RigidityUpVector" Type="SoftBodyAxis" Value="SOFTBODY_AXIS_Z">2</Enum>

Defines which axis is considered "up" for rigidity calculations.

In most cases this should match the world's up axis. In AC4, Z is up, so the default value of 2 is correct.

<Unsigned8 Name="MaxCollisionCount">3</Unsigned8>

The maximum number of character LiteRagdoll capsules to test for collision each frame. This is a performance setting.

• The game finds all nearby characters and builds LiteRagdoll capsules from their skeleton bones.
• This value caps how many of those capsules are actually tested. If there are 5 nearby characters but MaxCollisionCount is 3, only the first 3 are checked.
• Higher values = more accurate collision but more expensive.
• Lower values = cheaper but the cloth may clip through nearby NPCs.
• For a player character's cloth, 3 is usually sufficient since the most important collision is with the player's own body.

<Unsigned8 Name="ConstraintIterationCount">3</Unsigned8>

How many times the constraint solver runs per frame. Each pass makes the constraints (the connections between cloth vertices) more accurate.

• 1 = fast but loose. Constraints are only roughly satisfied. The cloth may stretch noticeably.
• 3 = good balance between quality and performance. This is the most common value.
• 5+ = very accurate constraints, minimal stretching, but increasingly expensive.

If your cloth looks stretchy or rubbery, try increasing this value. The maximum number of iterations is 7.

<Bool Name="UseWindAtVertices">False</Bool>

This value is NOT used by the game engine at runtime. It is a build-time or content-tool parameter. Changing it in the exported XML will have no effect in-game.

<Bool Name="UseGravityBone">False</Bool>

When enabled, the direction of gravity for this cloth is determined by a specific skeleton bone instead of the world's gravity direction.

• False = gravity always pulls in the world's down direction (as set by the Gravity vector).
• True = gravity direction is taken from the orientation of the bone specified by GravityBoneID. If the character tilts, gravity for the cloth tilts with the bone.
• Useful for cloth that should always hang "down" relative to a body part rather than the world. Could also be used for underwater or zero-gravity effects.

<Unsigned32 Name="GravityBoneID">4294967295</Unsigned32>

The ID of the skeleton bone used for gravity direction when UseGravityBone is True.

• 4294967295 (0xFFFFFFFF) means "none" / invalid. No gravity bone is assigned.
• When UseGravityBone is True, set this to a valid bone ID from the character's skeleton.

<Float Name="GravityBoneScale">1</Float>

Multiplier for the gravity bone's influence.

• 1.0 = the bone's direction fully replaces the gravity vector.
• 0.5 = half-strength influence from the bone.
• Only matters when UseGravityBone is True.

<Bool Name="UseVelocityBone">False</Bool>

When enabled, velocity calculations (used for the skinning blend system) track a specific bone instead of the entity root.

• False = velocity is computed from the character's root position and rotation.
• True = velocity is computed from the bone specified by VelocityBoneID. This gives more accurate velocity data for cloth attached to specific body parts (like a shoulder cape that should react to arm movement, not just whole-body movement).

<Unsigned32 Name="VelocityBoneID">4294967295</Unsigned32>

The bone ID used for velocity tracking when UseVelocityBone is True.

• 4294967295 (0xFFFFFFFF) means "none" / invalid.

<Float Name="SkinningLinearVelocityFactor">8</Float>

Controls how much the character's movement speed causes the cloth to "snap" to its animated position.

When the character runs, jumps, or moves quickly, the cloth can lag behind unrealistically. To prevent this, the game blends the cloth back toward its animated position based on how fast the character is moving. This setting controls the sensitivity of that blend.

• Higher values (like 8) = the cloth snaps to the animated position during fast movement. Good for preventing extreme stretching during fast actions.
• Lower values (like 1-2) = the cloth stays more physically simulated even during fast movement. More realistic but can cause dramatic trailing.
• 0 = no snap-to-skin from linear velocity. The cloth is fully simulated regardless of movement speed.

<Float Name="SkinningAngularVelocityFactor">8</Float>

Same as SkinningLinearVelocityFactor but for rotation. Controls how much the character's turning/spinning causes the cloth to snap to its animated position.

• Higher values = cloth snaps to the animated position during fast rotation (like combat spins).
• Lower values = cloth trails behind during rotation.

<Float Name="SkinningMaxFadeoutSpeed">0.4</Float>

How quickly the cloth transitions from its "snapped to animation" state back to being fully simulated when the character slows down.

• Lower values (like 0.1) = the cloth stays snapped to animation longer and transitions back to simulation very slowly. Smooth but sluggish.
• Higher values (like 1.0) = the cloth quickly returns to full simulation as soon as the character slows down. Responsive but can cause a visible "pop" as it releases.
• 0.4 is a good middle ground.

<Float Name="MinSkinFactor">0</Float>
<Float Name="MaxSkinFactor">1</Float>

The range of the skinning blend factor.

• MinSkinFactor is the blend floor -- even when the character is standing still, the cloth will blend at least this much toward the animated position. A value of 0 means the cloth is fully simulated when the character is idle. A value of 0.5 would mean the cloth always keeps at least 50% of its animated shape.
• MaxSkinFactor is the blend ceiling -- during fast movement, the blend can go up to this value. A value of 1 means the cloth can fully snap to the animated position. A value of 0.5 would mean the cloth always retains at least 50% of its simulated physics.

<Float Name="WeightUpwardVelocityFactor">-2</Float>

Adjusts the cloth's effective weight based on whether the character is moving up or down.

• Negative values (like -2) = when the character moves upward (jumping, climbing), the cloth becomes heavier and resists going up. When moving downward (falling), the cloth becomes lighter and floats up. This is physically intuitive -- when you jump, a scarf trails behind because inertia keeps it down.
• Positive values = the opposite effect (unusual).
• 0 = the cloth weight stays constant regardless of vertical velocity.

<Float Name="MaxAdjustedWeightFactor">5</Float>

Caps the maximum effective weight after velocity adjustments. Prevents the WeightUpwardVelocityFactor from making the cloth unrealistically heavy.

• The effective weight is clamped to: WeightFactor * MaxAdjustedWeightFactor.
• With WeightFactor=0.07 and MaxAdjustedWeightFactor=5, the effective weight can range from 0 to 0.35.
• If the cloth feels too heavy during jumps, try lowering this value.

<Enum Name="CollisionMode" Type="ClothCollisionMode" Value="CLOTH_COLLISIONMODE_MOVEBACK">1</Enum>

Controls how the game resolves collisions between the cloth and character body capsules. There are three modes:

When to use which:

• MOVEBACK (1) is the default and works well for most cloth. It's fast and handles simple cases like scarves, ribbons, and loose hanging fabric.
• CONSTRAINTS (2) is better for cloth that closely follows the body shape, like tight capes or form-fitting fabric. It prevents the jittering that can occur when collision corrections undo constraint corrections and vice versa.
• NONE (0) should rarely be used unless you want the cloth to clip through the body on purpose or are handling collision some other way.

<Float Name="MoveBackCollisionThreshold">0</Float>

A minimum penetration depth required before collision correction kicks in. Only used when CollisionMode is MOVEBACK (1).

• 0 = all collisions are resolved, no matter how small the penetration.
• Higher values = tiny collisions are ignored. Can reduce jittering from minor surface contacts but may allow small amounts of clipping.

Making cloth feel heavier:

• Increase WeightFactor (try 0.15-0.3)
• Increase Gravity Z magnitude (try -6 to -10)
• Increase AirFrictionFactor (try 0.2-0.4)

Making cloth feel lighter / more floaty:

• Decrease WeightFactor (try 0.02-0.05)
• Decrease Gravity Z magnitude (try -1 to -3)
• Decrease AirFrictionFactor (try 0.01-0.05)

Reducing stretching:

• Increase ConstraintIterationCount (try 4-6, but watch performance)
• Increase SkinningLinearVelocityFactor and SkinningAngularVelocityFactor to prevent extreme stretching during fast movement

Adding wind effects:

• Set UseWind to True
• Set WindFriction to a value greater than 0 (try 0.3-0.8)
• Optionally set WindRandomFactor to add flutter (try 0.1-0.5)

Preventing clipping through the body:

• Set ProcessCollisions to True
• Increase MinSphereRadius and MaxSphereRadius (but too large will make the cloth float visibly above the body)
• For tightly-fitting cloth, try CollisionMode = 2 (CONSTRAINTS) instead of 1 (MOVEBACK)

Preventing clipping through flat surfaces (character's back, etc.):

• Set CollideWithPlane to True

Cloth looks weird during fast movement or combat:

• Increase SkinningLinearVelocityFactor and SkinningAngularVelocityFactor (8-12)
• Increase SkinningMaxFadeoutSpeed for a quicker return to physics after action

Values you can ignore (no runtime effect):

• ConstraintFactor -- build-time only, changing it does nothing
• NormalNormalMinCosine -- build-time only, changing it does nothing
• UseWindAtVertices -- build-time only, changing it does nothing