CARNAGE GRAINS / DOCUMENTATION

Constraints

Use Glue to connect grains, Attraction to gather them, and Attach to Geometry to connect grains to mesh targets.

Glue

Enable Glue before starting the simulation. Bonds are created between nearby grains at initialization. Use Compliance to control softness, and Break Distance to control how far they can stretch before breaking. Higher bond counts increase memory and solver work.

Enable GlueDefault: Off: Creates bonds between neighboring grains that resist changes in their separation, allowing the grains to hold together as a connected material.
ComplianceDefault: 0.0011: Controls the softness of glue bonds. Higher values allow more stretching and compression under force. Very low values may require more substeps or constraint iterations for stable results.
Damping RatioDefault: 0.1: Reduces oscillation as glue bonds stretch and compress. Higher values make this motion settle more quickly.
Break DistanceDefault: 3.0: Stretch limit for breaking glue bonds, expressed as a multiple of their rest length. A value of 2 allows a bond to stretch to twice its rest length before breaking. A value of 0 disables breaking.
Break VariationDefault: 0.0: Randomly varies Break Distance between glue bonds. Higher values create a wider range of breaking thresholds, allowing some bonds to break under less stretch than others.
Bond RadiusDefault: 2.5: Search distance for creating glue bonds, expressed as a multiple of Grain Radius and measured between grain centers. Higher values allow connections to more distant grains and can create more bonds.
Max ConnectionsDefault: 0: Maximum number of glue bonds per grain. Lower values limit connectivity. A value of 0 allows connections to all neighboring grains within Bond Radius.
Samples Per BondDefault: 0: Number of collision sample points between the grains connected by each glue bond. Higher values help detect mesh colliders passing between grains without adding particles. More samples increase simulation time, especially with many bonds.
Show ConstraintsDefault: Off: Display glue bonds as lines and create constraint geometry for meshing. Updating this geometry adds calculation time. Glue data is saved in the point cache even when this display is off.
In FrontDefault: Off: Draw glue constraints in front of other geometry in the viewport.
Glue MaskDefault: Off: Uses a mask to vary glue Compliance and Break Distance across the grains, allowing different regions to deform and break differently.

Glue Break Distance is a multiple of bond rest length. Attachment Break Distance is an actual distance to the attachment point. These controls do not use the same units.

Glue Mask

Appears when Enable Glue and Glue Mask are on. The mask changes glue softness and breaking distance across the source; high mask values give stronger bonds. Object Proximity measures distance to the object’s origin, not its surface.

SourceDefault: Noise: Method used to generate the mask values.
Noise: Uses procedural 3D noise sampled at grain positions to generate the mask.
Weight Paint: Uses weights from a vertex group on the fill mesh to define the mask. Each grain receives the weight of the nearest mesh vertex.
Object Proximity: Generate mask values from distance to an object's origin, with higher values closer to it.
Texture: Uses an image or procedural Blender texture to define the mask, mapped using grain positions or the fill mesh's UV coordinates.
Noise TypeDefault: Perlin: Pattern used to generate procedural mask values.
Perlin: Smooth noise with additional layers controlled by Detail.
Voronoi: Cell-shaped gradients based on distance to the nearest feature point.
Crackle: A pattern emphasizing boundaries between Voronoi cells.
Cell Noise: A constant random value within each grid cell.
ScaleDefault: 2.0: Size of the noise features. Higher values produce broader patterns.
DetailDefault: 2: Number of noise layers used by Perlin noise. Higher values add finer variation.
OffsetDefault: 0.0, 0.0, 0.0: Offset of the coordinates used to sample the noise pattern.
Vertex GroupDefault: glue_mask: Vertex group on the fill mesh used to supply mask weights.
Texture: Blender texture used to supply mask values.
CoordinatesDefault: Object: Coordinate system used to sample the texture.
Object: Sample the texture using grain positions in the Mapping Object's local coordinates, or world coordinates when no object is assigned.
UV: Find the nearest point on the fill mesh’s surface and interpolate its face-corner UV coordinates to sample the texture. This preserves UV seams.
UV MapDefault: Empty: UV map on the fill mesh used to sample the texture. Leave empty to use the active UV map.
Mapping Object: Object whose local coordinates position, rotate, and scale the texture. Leave empty to use world coordinates.
Object: Object whose origin is used to calculate the proximity mask. Its surface shape does not affect the mask.
RadiusDefault: 1.0: Distance over which the proximity mask falls from full weight to zero.
FalloffDefault: Smooth: How the mask value decreases with distance from the proximity object.
Linear: Decrease mask weight evenly with distance.
Smooth: Decrease mask weight with a smooth transition at both ends of the range.
Sharp: Decrease mask weight rapidly near the object, concentrating high values close to it.
Constant: Use full mask weight within Radius and zero outside it.
ContrastDefault: 1.0: Adjusts the mask's brightness. Values above 1 darken the mask; values below 1 brighten it.
InvertDefault: Off: Reverses the mask values, turning low values into high values and high values into low values.
Depth FalloffDefault: Off: Blends the mask toward Interior Value as distance from the fill mesh's surface increases.
Depth RangeDefault: 0.1: World-space distance from the fill mesh’s surface over which the mask transitions to Interior Value, independent of object scale. Higher values spread the transition over a greater depth.
Interior ValueDefault: 1.0: Target mask value for grains at or beyond Depth Range from the fill mesh's surface. Lower values soften glue bonds and reduce their breaking distance when breaking is enabled.
Curve RemapDefault: Off: Use a curve to remap the final mask values. The horizontal axis is the input value; the vertical axis is the output value.
Show MaskDefault: On: Display glue mask values on the grains. Red indicates higher values and stronger bonds; blue indicates lower values and softer bonds.

For Texture sources, the embedded Texture Settings exposes the Blender texture type, image selection or procedural size/basis, intensity, contrast, and an optional color ramp. UV image sequences follow the scene frame.

Attraction

Attraction pulls nearby grains into clumps without using the fixed glue-bond network. Turn on Use Attraction and set a nonzero Attraction Weight; enabling the checkbox alone leaves the default weight at zero.

Use AttractionDefault: Off: Pulls nearby grains toward each other, helping them gather into clumps.
Attraction WeightDefault: 0.0: Strength of attraction between nearby grains. Higher values pull grains together more strongly.
Search ScaleDefault: 1.2: Attraction search distance, measured between grain centers as a multiple of the diameter defined by Grain Radius. Higher values allow attraction between more distant grains.
Attraction MaskDefault: Off: Uses a mask to vary attraction strength across the grains, allowing different regions to clump more or less strongly.

Attraction Mask

Appears when Use Attraction and Attraction Mask are on. Use Sample Every Frame when the mask must respond during the run. It samples at the grains’ current positions and adds processing work. Object Proximity is not offered in this mask.

SourceDefault: Noise: Where the attraction mask weights come from
Noise: Uses procedural 3D noise sampled at grain positions to generate the mask.
Weight Paint: Uses weights from a vertex group on the fill mesh to define the mask. Each grain receives the weight of the nearest mesh vertex.
Texture: Uses an image or procedural Blender texture to define the mask, mapped using grain positions or the fill mesh's UV coordinates.
Sample Every FrameDefault: Off: Resample the attraction mask at the grains' current positions each frame, allowing changes in the mask to affect the simulation. Adds calculation time.
Texture: Blender texture used to supply mask values.
CoordinatesDefault: Object: Coordinate system used to sample the texture.
Object: Sample the texture using grain positions in the Mapping Object's local coordinates, or world coordinates when no object is assigned.
UV: Find the nearest point on the fill mesh’s surface and interpolate its face-corner UV coordinates to sample the texture. This preserves UV seams.
UV MapDefault: Empty: UV map on the fill mesh used to sample the texture. Leave empty to use the active UV map.
Mapping Object: Object whose local coordinates position, rotate, and scale the texture. Leave empty to use world coordinates.
Noise TypeDefault: Perlin: Pattern used to generate procedural mask values.
Perlin: Smooth noise with additional layers controlled by Detail.
Voronoi: Cell-shaped gradients based on distance to the nearest feature point.
Crackle: A pattern emphasizing boundaries between Voronoi cells.
Cell Noise: A constant random value within each grid cell.
ScaleDefault: 2.0: Size of the noise features. Higher values produce broader patterns.
DetailDefault: 2: Number of noise layers used by Perlin noise. Higher values add finer variation.
OffsetDefault: 0.0, 0.0, 0.0: Offset of the coordinates used to sample the noise pattern.
Vertex GroupDefault: attraction_mask: Vertex group on the fill mesh used to supply mask weights.
ContrastDefault: 1.0: Adjusts the mask's brightness. Values above 1 darken the mask; values below 1 brighten it.
InvertDefault: Off: Reverses the mask values, turning low values into high values and high values into low values.
Depth FalloffDefault: Off: Blends the mask toward Interior Value as distance from the fill mesh's surface increases.
Depth RangeDefault: 0.1: World-space distance from the fill mesh’s surface over which the mask transitions to Interior Value, independent of object scale. Higher values spread the transition over a greater depth.
Interior ValueDefault: 1.0: Target mask value for grains at or beyond Depth Range from the fill mesh's surface. Lower values reduce attraction; higher values retain more of the strength set by Attraction Weight.
Curve RemapDefault: Off: Use a curve to remap the final mask values. The horizontal axis is the input value; the vertical axis is the output value.
Show MaskDefault: On: Display attraction mask values on the grains to show where attraction is stronger or weaker.

Attach to Geometry

Enable AttachDefault: Off: Creates constraints connecting nearby grains to target mesh surfaces, allowing the targets to hold or pull the grains.

Add targets with +, select an entry, and assign its mesh. Each row has an enabled checkbox. A grain binds to the nearest target; removing an entry does not delete the target object. Enable Animated for moving targets, and keep their vertex and face topology unchanged.

EnabledDefault: On: Include this target when creating and solving attachment constraints.
Object: Mesh surface that nearby grains can attach to.
AnimatedDefault: Off: Follow the target's movement and deformation each frame. The target must keep the same vertices and faces throughout the animation.
ComplianceDefault: 0.0: Controls the softness of attachment constraints. Higher values allow grains to move farther from their target distance under force. A value of 0 gives the stiffest attachment.
DampingDefault: 0.1: Reduces motion along attachment constraints, helping grains settle around their target distance.
Search RadiusDefault: 0.05: Maximum distance from the target surface at which an unattached grain can form an attachment.
Rest LengthDefault: 1.0: Target attachment distance as a multiple of the grain's initial distance from the target surface. A value of 1 preserves that distance; 0 pulls the grain onto the surface.
BreakableDefault: Off: Let the attachment snap when pulled far enough
Break DistanceDefault: 0.1: Distance from a grain to its attachment point at which the attachment breaks.

Attachment Break Mask

Use a Break Mask to vary how far grains can pull away before their attachments break. Select an attachment target, enable Breakable, then enable Break Mask and expand its arrow to see the controls.

The mask is sampled on the attachment target. Black areas break at Minimum Break Distance; white areas use Break Distance. Gray values blend between the two. Attachment softness and damping are controlled separately.

Break MaskDefault: Off: Vary the breaking distance across the selected attachment surface.
Minimum Break DistanceDefault: 0.01: Breaking distance in black mask areas. White areas use Break Distance. If Minimum Break Distance is higher than Break Distance, both use Break Distance.
SourceDefault: Noise: How the attachment surface supplies mask values.
Noise: Generate a procedural pattern in the target’s reference local coordinates.
Weight Paint: Interpolate vertex-group weights across the target surface.
Texture: Sample an image or procedural Blender texture on the target surface.
Animated MaskDefault: Off: Re-evaluate attached grains’ mask values each frame, including animated textures and settings. When off, each grain keeps the value sampled when it attaches. Broken attachments stay broken.
Noise TypeDefault: Perlin: Pattern used by the Noise source.
Perlin: Smooth noise with additional layers controlled by Detail.
Voronoi: Cell-shaped gradients based on distance to the nearest feature point.
Cell Noise: A constant random value within each cell.
ScaleDefault: 0.1: Size of noise features in the attachment target’s reference local space. Higher values create broader patterns.
DetailDefault: 2: Number of noise layers for Perlin noise. Higher values add finer variation.
OffsetDefault: 0.0, 0.0, 0.0: Offset of the coordinates used to sample the noise pattern.
Vertex GroupDefault: Empty: Vertex group on the attachment target supplying the mask weights.
Texture: Blender texture supplying the mask. Use Texture Settings to choose an image or adjust its procedural pattern.
CoordinatesDefault: UV: Coordinate system used by the Texture source.
UV: Interpolate the attachment target’s UV coordinates at each binding point, preserving seams.
Object: Sample in the attachment target’s reference local coordinates.
UV MapDefault: Empty: UV map on the attachment target. Leave empty to use its active UV map.
ContrastDefault: 1.0: Values above 1 darken the mask and make more areas break sooner; values below 1 brighten it.
InvertDefault: Off: Reverse the mask, swapping low and high values.
Remap CurveDefault: Off: Remap mask values with a curve. The horizontal axis is the input value; the vertical axis is the output value.
Show MaskDefault: Off: Display a grayscale overlay on the selected attachment target. Black breaks sooner; white uses Break Distance. The overlay leaves materials unchanged and is hidden in Rendered shading and final renders.

Configure the mask before starting. Enable the target’s Animated option for movement or deformation and keep its vertex and face topology consistent. Noise and Object mapping use the target’s reference shape, so the pattern follows the surface. Use Animated Mask when the mask values themselves need to change over time.

Changing a setup

Set bond search settings, connectivity and attachment targets before starting. Changes to geometry or bindings need a fresh simulation. Material controls such as Compliance, Break Distance and Attraction Weight can vary during the run; see Animation & keyframes. After editing animation, Reset and re-simulate to replace previously cached results.

Reference updated 7 November 2026. Defaults describe a fresh setup; saved scenes may use different values.