Skip to Content
Kinemium

Cloth

Create hanging fabric, curtains, and other deformable surfaces that respond to forces and impulses.

Cloth is a 3D object for creating fabric that can move and deform rather than staying rigid. You can suspend it from one or two attachments, control its appearance, and use forces or impulses to make it move.

Cloth inherits from Instance, so you can organize it in your hierarchy, clone it, and use inherited properties such as Name and Parent.

Getting started

A cloth needs at least one Attachment to define where it hangs. The attachment must belong directly to a Part in the Workspace hierarchy.

The following example assumes you already have a Cloth and two attachments on a rail in your scene:

local function setupCurtain(cloth: Cloth, left: Attachment, right: Attachment)
    cloth.Attachment0 = left
    cloth.Attachment1 = right

    cloth.Size = Vector2.new(6, 4)
    cloth.Color = Color3.fromRGB(220, 210, 195)
    cloth.Mass = 1
    cloth.Damping = 2
    cloth.CanCollide = true
    cloth.Enabled = true
end

The two attachments hold the upper corners of the curtain. The rest of the fabric extends down from them.

Attaching cloth

One attachment

With a single attachment, the cloth hangs from the center of its upper edge. Its initial width and height come from Size, and the attachment's orientation determines the initial direction of the fabric.

local function setupHangingFabric(cloth: Cloth, attachment: Attachment)
    cloth.Attachment0 = attachment
    cloth.Attachment1 = nil
    cloth.Size = Vector2.new(3, 5)
    cloth.Enabled = true
end

For a truly single-point setup, make sure the attachment doesn't have exactly one other Attachment sibling that can serve as a second anchor.

Two attachments

Use two attachments for curtains, banners, or fabric stretched across a rail.

cloth.Attachment0 = leftAttachment
cloth.Attachment1 = rightAttachment
cloth.Size = Vector2.new(6, 4)

When the two attachment positions are more than 0.001 studs apart, their distance determines the cloth's width instead of Size.X. Size.Y still determines its height. If they are nearly coincident, the cloth uses the configured width as a fallback.

If you leave Attachment1 unset and Attachment0 has exactly one other non-destroyed Attachment sibling, Cloth can automatically use that sibling as the second anchor. When several candidates exist, explicitly assign the attachment you want.

Attachment0 must be valid before the cloth can be displayed. If Attachment1 is invalid, the cloth falls back to a single anchor.

Making cloth move

Continuous force

Use Force for a sustained effect, such as wind pushing a curtain. The value is a three-dimensional vector, not a target position.

-- Push the fabric along the positive X axis.
cloth.Force = Vector3.new(8, 0, 0)

-- Remove the applied force.
cloth.Force = Vector3.new(0, 0, 0)

Assigning zero removes the configured force; it doesn't reset the cloth's pose.

One-time impulse

Use ApplyImpulse() for a brief push, such as fabric reacting to a nearby impact.

cloth:ApplyImpulse(Vector3.new(0, 0, 12))

You can leave Force at zero while applying impulses. Use Mass and Damping to tune the response. The exact movement depends on the physics simulation.

Properties

All properties in this table are readable and writable.

PropertyTypeDefaultDescription
Attachment0Attachment?nilPrimary anchor. Required for the cloth to appear.
Attachment1Attachment?nilOptional second anchor for the opposite upper corner.
SizeVector2Vector2.new(6, 4)Configured width and height in studs. Each dimension must be between 0.1 and 1024.
ColorColor3Color3.new(0.85, 0.85, 0.85)Base color of the fabric.
MaterialVariantstring""Name of the material variant intended for the cloth.
EnabledbooleantrueWhether cloth is enabled. Disabling it resets its simulated state and clears pending impulses.
CanCollidebooleantrueControls whether collision is enabled for the cloth.
Massnumber1Mass used for the cloth simulation. Must be finite and at least 0.001.
Dampingnumber2Controls how quickly movement is damped. Must be finite and nonnegative.
ForceVector3Vector3.new(0, 0, 0)Continuous applied force. All components must be finite.

Changing the shape

Changing Size or either attachment resets the cloth's initialized pose. Changing an attachment also clears any pending impulse, so set up anchors before applying a push.

Appearance

You can change the color or select a named material variant without changing the cloth's dimensions.

cloth.Color = Color3.fromRGB(110, 35, 45)
cloth.MaterialVariant = "Velvet"

"Velvet" is an example name; use a material variant that exists in your project. Texture and material rendering behavior depends on the material configuration.

Resetting the cloth

To discard its current pose and pending impulses, disable and re-enable the cloth:

cloth.Enabled = false
cloth.Enabled = true

It can initialize again from its current attachments when they are valid. This does not clear Force or reset the other configuration properties.

Methods

ApplyImpulse

ApplyImpulse(impulse: Vector3): ()

Applies a one-time impulse to the cloth.

The method accepts a Vector3 and returns no values. Multiple impulses submitted before they are processed accumulate. An impulse is only queued when the cloth is enabled and Attachment0 is assigned. Non-finite accumulated impulses raise an error.

local function pushFabric(cloth: Cloth)
    if cloth.Enabled and cloth.Attachment0 then
        cloth:ApplyImpulse(Vector3.new(0, 3, 10))
    end
end

Events

Touched

Touched is the cloth's contact event.

cloth.Touched:Connect(function(...)
    print("Cloth contact", ...)
end)

The current class API exposes this event, but its callback arguments and exact firing conditions are not specified by the available class definition. Don't rely on a particular argument type or collision notification frequency without verifying the physics behavior.

Cloning

A cloned cloth copies its attachment references, size, appearance, enabled state, collision setting, mass, damping, and continuous force. It does not copy its live deformed pose or pending impulses. If you want the copy to hang elsewhere, assign new attachments to it before use.

Troubleshooting

  • The cloth is missing: Check that Enabled is true and Attachment0 belongs to a Part under Workspace.
  • The width doesn't match Size.X: With two valid, separated anchors, their distance sets the width.
  • A second corner appears pinned unexpectedly: Check for an additional Attachment sibling of Attachment0.
  • An impulse has no effect: Make sure the cloth is enabled, has a valid primary attachment, and is able to simulate.
  • Changing an anchor resets the fabric: This is expected when the cloth needs to initialize a new pose.

The public API does not currently expose controls for individual cloth points, cloth subdivision, or collision filtering specific to Cloth. Use the properties and methods above to control the fabric.

On this page