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
endThe 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
endFor 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.
| Property | Type | Default | Description |
|---|---|---|---|
Attachment0 | Attachment? | nil | Primary anchor. Required for the cloth to appear. |
Attachment1 | Attachment? | nil | Optional second anchor for the opposite upper corner. |
Size | Vector2 | Vector2.new(6, 4) | Configured width and height in studs. Each dimension must be between 0.1 and 1024. |
Color | Color3 | Color3.new(0.85, 0.85, 0.85) | Base color of the fabric. |
MaterialVariant | string | "" | Name of the material variant intended for the cloth. |
Enabled | boolean | true | Whether cloth is enabled. Disabling it resets its simulated state and clears pending impulses. |
CanCollide | boolean | true | Controls whether collision is enabled for the cloth. |
Mass | number | 1 | Mass used for the cloth simulation. Must be finite and at least 0.001. |
Damping | number | 2 | Controls how quickly movement is damped. Must be finite and nonnegative. |
Force | Vector3 | Vector3.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 = trueIt 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
endEvents
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
Enabledis true andAttachment0belongs to aPartunder 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
Attachmentsibling ofAttachment0. - 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.
