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:

• Place a DragDetector under any BasePart or Model to make it draggable via all inputs (mouse, touch, gamepad, and VR), all without a single line of code.

• Choose from several drag styles, define how the object responds to motion, and optionally apply axis or movement limits.

• Scripts can respond to 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.

• Players can manipulate anchored parts or models and they'll stay exactly where you put them upon release.

• DragDetectors work in Studio as long as you're not using the Select, Move, Scale, or Rotate tools, making it easier to test and adjust draggable objects while editing.

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.

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.

Response to Motion

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

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.

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.

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:

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.

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)