3D Drag Detectors

The DragDetector instance facilitates and encourages interaction with 3D objects in an experience, such as opening doors and drawers, sliding a part around, grabbing and tossing a bowling ball, pulling back and firing a slingshot, and much more. Key features include:

Making Objects Draggable

To make any part or model draggable, simply add a DragDetector as a direct descendant.

  1. In the Explorer window, hover over the Part, MeshPart, or Model and click the ⊕ button. A contextual menu displays.

  2. From the menu, insert a DragDetector.

  3. By default, the object will now be draggable in the ground plane, but you can customize its DragStyle, define how it responds to motion, and optionally apply axis or movement limits.

Customizing Drag Detectors

Drag Style

DragDetectors map cursor motion to virtual lines and planes to calculate proposed 3D motion. Through the DragStyle property, you can choose from different mappings to suit your needs. For example, TranslatePlane produces translation in a virtual plane, whereas RotateAxis produces rotation about a virtual axis.

SettingDescription
TranslateLine1D motion along the detector's Axis, by default the world Y axis.
TranslatePlane2D motion in the plane perpendicular to the detector's Axis, by default the world XZ plane.
TranslatePlaneOrLine2D motion in the plane perpendicular to the detector's Axis and, when the modifier is active, 1D motion along the detector's Axis.
TranslateLineOrPlane1D motion along the detector's Axis and, when the modifier is active, 2D motion in the plane perpendicular to the detector's Axis.
TranslateViewPlane2D motion in the plane perpendicular to the camera's view. In this mode, the plane is constantly updated, even while dragging, and will always face the camera's current view.
RotateAxisRotation about the detector's Axis, by default the world Y axis.
RotateTrackballTrackball rotation, further customized through the TrackballRadialPullFactor and TrackballRollFactor properties.
BestForDeviceTranslatePlaneOrLine for mouse and gamepad; TranslatePlane for touch; 6DOF for VR.
ScriptableCalculates desired motion via a custom function provided through SetDragStyleFunction().

Drag Direction

By default, 3D motion and the associated DragStyle map to world space. However, you may want to change the ReferenceInstance, Orientation, or Axis, for example when building drag detectors into models with adjustable parts.

PropertyDescriptionDefault
ReferenceInstanceAn instance whose pivot provides the reference frame for the drag detector. The DragFrame is expressed relative to this reference frame which may be retrieved via GetReferenceFrame(). If the reference frame is nil, translation will be in the direction of (or in the plane perpendicular to) the Axis property in world space.nil
OrientationSpecifies the YXZ rotation of axes of motion relative to the reference frame (does not change the orientation of the reference frame itself). Linear translation and axial rotation will be on this reoriented Y axis, and planar translation in the XZ plane. Changing this value automatically updates Axis and vice versa.(0, 0, 0)
AxisThe primary axis of motion, expressed relative to the reference frame. Changing this value automatically updates Orientation and vice versa.(0, 1, 0)

Response to Motion

The ResponseStyle property specifies how an object responds to the proposed motion, depending on whether the object is Anchored or not.

SettingAnchored BehaviorUnanchored Behavior
GeometricBoth inside the running experience and in Studio edit mode, the position/orientation of an anchored object will be updated to exactly reflect the proposed motion.For an unanchored object, behavior is the same as for an anchored object. However, in a running experience, the object will be anchored at the start of the drag and restored to unanchored upon drag release.
PhysicalAn anchored object will default to Geometric behavior, as it is not affected by forces.An unanchored object will be moved by constraint forces that attempt to bring it to the desired position and/or orientation given by the proposed motion.
CustomThe object will not move at all, but DragFrame will still be updated and you can respond to drag manipulation however you'd like.(same as anchored)

Axis & Movement Limits

By default, there are no limits to 3D motion beyond the inherent restrictions of the DragStyle. If necessary, you can apply minimum and maximum limits to both translation and rotation. Note, however, that these are not constraints; they merely impede the drag detector's attempts to generate motion in order to remain within limits.

PropertiesDescriptionDefault
MinDragTranslation
MaxDragTranslation
Limits to drag translation in each dimension. If MaxDragTranslation is greater than MinDragTranslation, translation will be clamped within that range.(0, 0, 0)
MinDragAngle
MaxDragAngle
Only relevant if DragStyle is set to RotateAxis. If MaxDragAngle is greater than MinDragAngle, rotation will be clamped within that range.0

Drag Permission

Permission of players to interact with a given drag detector instance can be specified by the PermissionPolicy property. This is set to Enum.DragDetectorPermissionPolicy.Everybody by default, and it can also be changed to support scripted permission controls as shown in the code sample.

SettingDescription
NobodyNo players can interact with the DragDetector.
EverybodyAll players can interact with the DragDetector.
ScriptablePlayers' drag permissions will be determined by a function registered through SetPermissionPolicyFunction(). Under this setting, failure to register a function or returning an invalid result will prevent all players from dragging.
DragDetector - Scripted Drag Permission

local dragDetector = script.Parent.DragDetector
dragDetector.PermissionPolicy = Enum.DragDetectorPermissionPolicy.Scriptable
dragDetector:SetPermissionPolicyFunction(function(player, part)
if player and player:GetAttribute("IsInTurn") then
return true
elseif part and not part:GetAttribute("IsDraggable") then
return false
else
return true
end
end)

Physics Response

Assuming a dragger's response style is set to Physical and it is applied to an unanchored object, that object will be moved by constraint forces that attempt to bring it to the position/orientation given by the proposed motion. You can further customize the physical response through the following properties:

PropertyDescriptionDefault
ApplyAtCenterOfMassWhen false, drag force is applied at the point the user clicks on. When true, force is applied at the object's center of mass.false
MaxForceMaximum force applied for the object to reach its goal.10000000
MaxTorqueMaximum torque applied for the object to reach its goal.10000
ResponsivenessHigher values cause the object to reach its goal more rapidly.10

Modifier Input

Some DragStyle modes allow users to hold down a modifier key/button to manipulate the dragged object in different ways. By default, the modifier is LeftControl on PC, ButtonR1 on gamepad, or ButtonL2 on VR. You can customize these modifiers through the KeyboardModeSwitchKeyCode, GamepadModeSwitchKeyCode, or VRSwitchKeyCode properties of the drag detector instance.

Replication

When the RunLocally property is false (default), the client interprets all input to produce data that it sends to the server to perform the drag. In this mode, all custom event signals and registered functions must be in server Scripts.

When the RunLocally property is true, no events are replicated to the server. All custom event signals and registered functions must be in client LocalScripts and you must use remote events to propagate necessary changes to the server.

Scripting Responses to Clicking and Dragging

Through event signals, property changes, Scriptable drag style, and custom functions, scripts can respond to the manipulation of dragged objects to drive UI or make logical decisions, such as adjusting the light level in a room based on a sliding wall switch dimmer.

Event Signals

Through the following event signals, you can detect when a user starts, continues, and ends dragging an object.

EventDescription
DragStartFires when a user starts dragging the object.
DragContinueFires when a user continues dragging the object after DragStart has been initiated.
DragEndFires when a user stops dragging the object.
DragDetector - Event Signals

local dragDetector = script.Parent.DragDetector
local highlight = Instance.new("Highlight")
highlight.Enabled = false
highlight.Parent = script.Parent
dragDetector.DragStart:Connect(function()
highlight.Enabled = true
end)
dragDetector.DragContinue:Connect(function()
end)
dragDetector.DragEnd:Connect(function()
highlight.Enabled = false
end)

Drag Frame Changes

In addition to event signals, you can monitor changes to the detector's DragFrame directly.

DragDetector - DragFrame Changes

local dragDetector = script.Parent.DragDetector
dragDetector:GetPropertyChangedSignal("DragFrame"):Connect(function()
local currentDragTranslation = dragDetector.DragFrame.Position
print(currentDragTranslation)
end)

Scripted Drag Style

If you set a detector's DragStyle to Scriptable, you can provide your own function that takes in a Ray and returns a world space CFrame. The detector will move the motion so that the dragged object goes to that custom location/orientation.

DragDetector - Scripted DragStyle

local dragDetector = script.Parent.DragDetector
dragDetector.DragStyle = Enum.DragDetectorDragStyle.Scriptable
local cachedHitPoint = Vector3.zero
local cachedHitNormal = Vector3.yAxis
local function followTheCursor(cursorRay)
-- Exclude dragged object from raycast detection
local raycastParams = RaycastParams.new()
raycastParams.FilterDescendantsInstances = {dragDetector.Parent}
raycastParams.FilterType = Enum.RaycastFilterType.Exclude
local hitPoint = Vector3.zero
local hitNormal = Vector3.yAxis
local raycastResult = workspace:Raycast(cursorRay.Origin, cursorRay.Direction, raycastParams)
if raycastResult then
hitPoint = raycastResult.Position
hitNormal = raycastResult.Normal.Unit
else
hitPoint = cachedHitPoint
hitNormal = cachedHitNormal
end
cachedHitPoint = hitPoint
cachedHitNormal = hitNormal
local lookDir1 = hitNormal:Cross(Vector3.xAxis)
local lookDir2 = hitNormal:Cross(Vector3.yAxis)
local lookDir = if lookDir1.Magnitude > lookDir2.Magnitude then lookDir1.Unit else lookDir2.Unit
return CFrame.lookAt(hitPoint, hitPoint + lookDir, hitNormal)
end
dragDetector:SetDragStyleFunction(followTheCursor)

Custom Constraint Function

Drag detectors do not have built-in motion rules about grids and snapping, but you can register custom constraint functions to edit the detector's DragFrame before it is applied. For example, you can keep motion on a grid by rounding positions to multiples of the grid increment, or simulate a chess game with rules of motion legal to each piece.

DragDetector - Custom Constraint Function

local dragDetector = script.Parent.DragDetector
local startPartPosition = nil
local SNAP_INCREMENT = 4
dragDetector.DragStart:Connect(function()
startPartPosition = script.Parent.Position
end)
dragDetector.DragEnd:Connect(function()
startPartPosition = nil
end)
local function snapToWorldGrid(proposedMotion)
if startPartPosition == nil then
return proposedMotion
end
local snapIncrement = math.floor(SNAP_INCREMENT)
if snapIncrement < 1 then
return proposedMotion
end
local newWorldPosition = startPartPosition + proposedMotion.Position
local roundedX = math.floor(newWorldPosition.X / snapIncrement + 0.5) * snapIncrement
local roundedY = math.floor(newWorldPosition.Y / snapIncrement + 0.5) * snapIncrement
local roundedZ = math.floor(newWorldPosition.Z / snapIncrement + 0.5) * snapIncrement
local newRoundedWorldPosition = Vector3.new(roundedX, roundedY, roundedZ)
return proposedMotion.Rotation + (newRoundedWorldPosition - startPartPosition)
end
local connection = dragDetector:AddConstraintFunction(2, snapToWorldGrid)
-- When applicable, remove the constraint function by invoking connection:Disconnect()

Example Usage

Unanchored Physical Objects

A basic implementation of drag detectors is a tower balance game where players must carefully remove pieces and attempt to keep the tower upright. In the following tower structure, each piece has a child DragDetector with a default DragStyle of TranslatePlane so that players can pull the pieces outward but not upward or downward.

Anchored Models With Adjustable Parts

You can easily create and share models which are primarily anchored, but which have one or more child parts/models that players can drag. For example, the following desk has two drawers which players can open to inspect what's inside.

Drag Detectors and Constraints

You can combine drag detectors with Constraints, for example a marionette puppet. In the following setup, the control handles are anchored, the body parts are unanchored, and constraints hold the marionette together. Moving the handles with the TranslateViewPlane DragStyle makes the marionette dance, and the individual body parts may also be moved with drag detectors, all while the model retains its integrity.

3D User Interfaces

3D user interfaces are easily achievable through drag detectors, such as adjusting the brightness of a SpotLight based on a sliding switch dimmer. You can also detect the X and Z axes individually to control two different aspects of a 3D user interface, such as the Size, Speed, and Color of a ParticleEmitter.

DragDetector - 3D User Interface

local model = script.Parent
local slider = model.SliderPart
local originPart = model.OriginPart
local emitter = script.Parent.EmitterPart.ParticleEmitter
local dragDetector = slider.DragDetector
dragDetector.ReferenceInstance = originPart
dragDetector.MinDragTranslation = Vector3.zero
dragDetector.MaxDragTranslation = Vector3.new(10, 0, 10)
local dragRangeX = dragDetector.MaxDragTranslation.X - dragDetector.MinDragTranslation.X
local dragRangeZ = dragDetector.MaxDragTranslation.Z - dragDetector.MinDragTranslation.Z
local MIN_PARTICLE_SIZE = 1
local MAX_PARTICLE_SIZE = 1.5
local MIN_PARTICLE_SPEED = 2.5
local MAX_PARTICLE_SPEED = 5
local COLOR1 = Color3.fromRGB(255, 150, 0)
local COLOR2 = Color3.fromRGB(255, 0, 50)
local function updateParticles(emitter)
local dragFactorX = (dragDetector.DragFrame.Position.X - dragDetector.MinDragTranslation.X) / dragRangeX
local dragFactorZ = (dragDetector.DragFrame.Position.Z - dragDetector.MinDragTranslation.Z) / dragRangeZ
-- Adjust particle size and speed based on drag detector X factor
emitter.Size = NumberSequence.new{
NumberSequenceKeypoint.new(0, 0),
NumberSequenceKeypoint.new(0.1, MIN_PARTICLE_SIZE + ((MAX_PARTICLE_SIZE - MIN_PARTICLE_SIZE) * dragFactorX)),
NumberSequenceKeypoint.new(1, 0)
}
local speed = MIN_PARTICLE_SPEED + ((MAX_PARTICLE_SPEED - MIN_PARTICLE_SPEED) * dragFactorX)
emitter.Speed = NumberRange.new(speed, speed * 1.2)
-- Adjust particle color based on drag detector Z factor
local color = COLOR2:Lerp(COLOR1, dragFactorZ)
emitter.Color = ColorSequence.new{
ColorSequenceKeypoint.new(0, color),
ColorSequenceKeypoint.new(1, color)
}
end
dragDetector:GetPropertyChangedSignal("DragFrame"):Connect(function()
updateParticles(emitter)
end)