UIDragDetector 인스턴스는 슬라이더, 스피너 등과 같은 경험의 2D 사용자 인터페이스 요소와의 상호작용을 촉진하고 장려합니다. 주요 기능은 다음과 같습니다:
GuiObject 인스턴스 아래에 UIDragDetector를 배치하여 단 한 줄의 코드 없이 모든 사용자 입력을 통해 드래그할 수 있게 만듭니다.
여러 DragStyle 옵션 중에서 선택하고, ResponseStyle를 통해 객체가 모션에 어떻게 반응할지 정의하며, 선택적으로 축, 움직임 제한 또는 드래그 경계를 적용할 수 있습니다.
스크립트는 드래그된 객체의 조작에 반응하여 설정 조정과 같은 논리적 반응을 유도할 수 있습니다.
UIDragDetectors는 Select, Move, Scale, 또는 Rotate 도구 및 특정 플러그인이나 스튜디오의 UI 편집 도구를 사용하지 않는 한 스튜디오의 편집 및 재생 모드에서 작동합니다.
UI 요소를 드래그 가능하게 만들기
모든 GuiObject 인스턴스를 드래그 가능하게 만들려면 UIDragDetector를 직접 하위 객체로 추가하면 됩니다.
메뉴에서 UIDragDetector를 삽입합니다.

기본적으로 이제 객체는 LayerCollector 인터페이스에서 드래그 가능하게 됩니다.
UI 드래그 탐지기 사용자 정의
드래그 스타일
UIDragDetectors는 커서 모션을 매핑하여 제안된 2D 모션 및/또는 회전을 계산합니다. DragStyle 속성을 통해 필요에 맞는 다양한 매핑을 선택할 수 있습니다. 예를 들어, Enum.UIDragDetectorDragStyle.TranslatePlane은 LayerCollector의 2D 평면에서 변환을 생성하고, Enum.UIDragDetectorDragStyle.Rotate는 일반적으로 변환 대신 회전을 생성합니다.
| 설정 | 설명 |
|---|---|
| TranslateLine | 탐지기의 DragAxis를 따라 1D 모션. |
| TranslatePlane | LayerCollector의 평면에서 2D 모션. |
| Rotate | 기본적으로 탐지기의 부모 GuiObject의 절대 중앙 위치를 중심으로 회전합니다. ReferenceUIInstance가 설정된 경우, 그 인스턴스의 절대 중앙 위치를 중심으로 회전합니다. |
| Scriptable | 사용자가 SetDragStyleFunction()을 통해 제공한 사용자 지정 함수를 통해 원하는 모션을 계산합니다. |
드래그 방향
기본적으로 2D 모션 및 관련된 DragStyle는 조상의 LayerCollector 공간에 매핑됩니다. 그러나 다양한 UI 구성 요소를 구축할 때 ReferenceUIInstance 또는 DragAxis를 변경하고 싶을 수 있습니다.
| 설정 | 설명 | 기본값 |
|---|---|---|
| ReferenceUIInstance | 탐지기에 대한 참조 공간과 원점이 되는 절대 중앙 위치를 가진 GuiObject 인스턴스입니다. 이 참조를 설정하면 DragUDim2, DragRotation와 같은 속성 및 DragAxis의 동작에 영향을 미칩니다. | nil |
| DragAxis | Vector2 값으로, DragStyle가 Enum.UIDragDetectorDragStyle.TranslateLine으로 설정된 경우 드래그된 객체의 움직임 축을 정의합니다. 축은 UIDragDetector의 로컬 공간에서 정의되며, ReferenceUIInstance가 정의된 경우 해당 인스턴스의 로컬 공간에서 정의됩니다. | (1, 0) |
모션에 대한 응답
UIDragDetector.ResponseStyle 속성은 제안된 모션에 의해 객체의 위치 값이 어떻게 변경되는지를 지정합니다. 사용자 지정 응답 스타일을 사용하면 탐지기의 부모가 제안된 모션을 실행하지 않고도 결과 UIDragDetector.DragUDim2 및 UIDragDetector.DragRotation 값을 원하는 대로 사용할 수 있습니다.
| 설정 | 설명 |
|---|---|
| Offset | 탐지기의 부모 GuiObject.Position 값의 Offset 값에 따라 이동합니다. 기본적으로 이 설정입니다. |
| Scale | 탐지기의 부모 GuiObject.Position 값의 Scale 값에 따라 이동합니다. |
| CustomOffset | UI 요소는 전혀 움직이지 않지만, 탐지기의 DragUDim2의 Offset 값은 여전히 업데이트되며, 탐지기의 이벤트도 여전히 발생하여 드래그 조작에 자유롭게 응답할 수 있습니다. |
| CustomScale | UI 요소는 전혀 움직이지 않지만, 탐지기의 DragUDim2의 Scale 값은 여전히 업데이트되며, 탐지기의 이벤트도 여전히 발생하여 드래그 조작에 자유롭게 응답할 수 있습니다. |
변환 및 회전 제한
기본적으로 DragStyle의 고유한 제한 이외에는 2D 모션에 대한 제한이 없습니다. 원하는 경우 다음 속성을 사용하여 최소 및 최대 변환 및 회전에 대한 제한을 선언할 수 있습니다. 추가로, 드래그된 객체가 특정 GuiObject의 경계 내에서 어떻게 제약되는지를 정의할 수도 있습니다. 예를 들어 Frame와 같은 요소가 있습니다.
| 속성 | 설명 | 기본값 |
|---|---|---|
| MinDragTranslation MaxDragTranslation | 각 차원에서의 드래그 변환에 대한 제한으로, UDim2 값으로 정의됩니다. MaxDragTranslation이 MinDragTranslation보다 크면 변환은 해당 범위 내에서 변동됩니다. | {0, 0}, {0, 0} |
| MinDragAngle MaxDragAngle | DragStyle가 Enum.UIDragDetectorDragStyle.Rotate로 설정되었거나, SetDragStyleFunction()이나 AddConstraintFunction()을 통해 설정된 함수가 회전 값을 정의하는 경우에만 관련이 있습니다. MaxDragAngle가 MinDragAngle보다 크면 회전은 해당 범위 내에서 제한됩니다. | 0 |
| BoundingBehavior | BoundingUI가 설정되었을 때 탐지기 인스턴스의 경계 동작을 결정합니다. 이를 EntireObject로 설정하면 드래그된 UI 전체가 BoundingUI 내에서 제한되고, HitPoint로 설정하면 드래그된 UI가 정확한 히트/잡기 지점과 그에 따른 위치에 따라 제한됩니다. 편의상, 기본값인 Automatic은 BoundingUI에 완전히 포함된 UI 객체의 경우 EntireObject 동작을 모방하고, 그렇지 않은 경우에는 HitPoint로 설정됩니다. | Automatic |
속도 조정
SelectionModeDragSpeed 및 SelectionModeRotateSpeed를 통해 탐지기의 최대 드래그/회전 속도를 세밀하게 조정할 수 있습니다. 추가로, UIDragSpeedAxisMapping을 통해 탐지기의 SelectionModeDragSpeed에 따라 X/Y 차원 드래깅 속도를 세밀하게 조정할 수 있습니다.
| 속성 | 설명 |
|---|---|
| SelectionModeDragSpeed | 탐지기가 속하는 첫 번째 조상 ScreenGui 또는 SurfaceGui의 Scale 및 Offset의 조합으로 변환에 대한 최대 드래그 속도를 정의합니다. |
| SelectionModeRotateSpeed | UIDragDetector가 회전할 수 있는 초당 최대 각도를 정의합니다. |
| UIDragSpeedAxisMapping | 탐지기의 SelectionModeDragSpeed에 따라 X/Y 차원 드래그 속도를 정의합니다. 기본값은 XY로, 즉 X 및 Y 축 속도가 각각 X 및 Y의 Scale/Offset 값에 기반합니다. 대안으로는 XX 및 YY가 있으며, 이는 각각 X 축(XX) 또는 Y 축(YY)에 기반한 속도를 의미하며, Offset 값은 여전히 해당 축에 적용됩니다. 예를 들어 첫 번째 조상 ScreenGui가 800×600 크기로 설정되고 SelectionModeDragSpeed가 {0.1, 10}, {0.1, 20}로 설정된 경우, XX 설정에서는 X/Y 드래그 속도가 80+10/80+20가 되며, YY에서는 60+10/60+20가 됩니다(참고로 Offset 값은 두 경우 모두 동일하게 유지됩니다). |
클릭 및 드래깅에 대한 스크립트 반응
이벤트 신호, 속성 변경, Scriptable 드래그 스타일 및 사용자 정의 함수를 통해, 스크립트는 드래그된 UI 요소의 조작에 반응하여 다양한 설정을 유도하거나 논리적 결정을 내릴 수 있습니다. 예를 들어, 음악과 효과음 볼륨을 개별적으로 조정하는 슬라이더와 같은 것입니다.
이벤트 신호
다음 이벤트 신호를 통해 사용자가 객체의 드래깅을 시작, 계속 및 종료할 때를 감지할 수 있습니다.
| 이벤트 | 설명 |
|---|---|
| DragStart | 사용자가 객체의 드래깅을 시작할 때 발생합니다. |
| DragContinue | 사용자가 DragStart가 시작된 후 객체의 드래깅을 계속할 때 발생합니다. |
| DragEnd | 사용자가 객체의 드래깅을 중지할 때 발생합니다. |
다음 슬라이더는 컨테이너를 BoundingUI로 지정하여 컨테이너 영역 내에서의 움직임을 제한하며, 스케일 기반 TranslateLine 드래그가 추가 스크립팅 없이 컨테이너의 전체 너비로 제한되도록 합니다.
UIDragDetector - 이벤트 신호 투명도 변경
-- 계층 구조는 SliderContainer ⟩ Handle ⟩ UIDragDetector ⟩ (이 스크립트)
local sliderContainer = script.Parent.Parent.Parent
local handle = sliderContainer:FindFirstChild("Handle")
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")
uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale -- 스케일로 드래깅 설정
uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.TranslateLine -- 드래깅을 선으로 제한
uiDragDetector.BoundingUI = sliderContainer
-- 처음에는 핸들의 X 스케일 값에 따라 컨테이너 투명도 설정
sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale
-- 잡기 시작 시 핸들 테두리를 확장하여 표시
uiDragDetector.DragStart:Connect(function(inputPosition)
handle:FindFirstChildWhichIsA("UIStroke").Thickness = 6
end)
-- 스케일에 따라 얼마나 드래그했는지에 따라 투명도 변경
uiDragDetector.DragContinue:Connect(function(inputPosition)
sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale
end)
-- 잡기 종료를 표시하기 위해 핸들 테두리 재설정
uiDragDetector.DragEnd:Connect(function(inputPosition)
handle:FindFirstChildWhichIsA("UIStroke").Thickness = 4
end)
위치 및 회전 변경
이벤트 신호 외에도 탐지기의 DragUDim2 및/또는 DragRotation 속성의 변화를 직접 모니터링할 수 있습니다.
다음 탐지기는 DragStyle를 Rotate로 설정하여 사용자가 색상 회전 링 주변에서 핸들을 드래그할 수 있도록 하며, Instance:GetPropertyChangedSignal()를 통해 드래그 회전의 변화를 감지합니다.
UIDragDetector - DragRotation 변화
local handle = script.Parent.Parent -- 드래그할 UI 요소
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")
uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.Rotate -- 드래그 스타일을 회전으로 설정
local function changeHue()
local currAngle = (math.fmod(handle.Rotation, 360)) / 360
if currAngle < 0 then
currAngle += 1
end
handle.BackgroundColor3 = Color3.fromHSV(currAngle, 1, 1)
end
-- 처음에는 핸들 회전에 따라 색상을 설정
changeHue()
-- 탐지기의 드래그 회전에 대한 GetPropertyChangedSignal()에 함수 연결
uiDragDetector:GetPropertyChangedSignal("DragRotation"):Connect(changeHue)
스크립트 드래그 스타일
탐지기의 UIDragDetector.DragStyle을 Enum.UIDragDetectorDragStyle.Scriptable로 설정하면, 입력 위치의 Vector2를 입력으로 받고 UDim2(위치) 및 부동 소수점(회전)을 반환하는 사용자 지정 함수를 제공할 수 있습니다. 탐지기는 반환된 값을 기반으로 객체를 계산된 위치/회전으로 업데이트하며, DragSpace 속성과 DragRelativity 속성의 영향을 받습니다.
기본적으로 반환된 UDim2 및 부동 소수점은 탐지기의 부모의 로컬 공간에서의 최종 원하는 위치/회전입니다. 기존의 변환/회전 제한은 여전히 적용되며, 지정된 BoundingUI 인스턴스에 의해 부과된 경계 제한도 동일하게 적용됩니다.
다음 예제는 X 좌표 입력의 변화에 따라 사인파를 따라 UI 요소를 드래그합니다. 탐지기의 DragSpace는 Enum.UIDragDetectorDragSpace.Relative로 설정되어 있습니다.
UIDragDetector - 드래그가 사인파를 따르기
local frame = script.Parent -- 드래그할 UI 요소
local uiDragDetector = frame:FindFirstChildWhichIsA("UIDragDetector")
local initialXValue = 0
local maxHeightChange = 200
local pixelsPerRadian = 75 -- 주파수를 높이려면 이 값을 낮추세요
uiDragDetector.DragStart:Connect(function(inputPosition)
initialXValue = inputPosition.X
end)
local function computeSinWaveCoordinate(inputPosition)
local deltaX = inputPosition.X - initialXValue
-- Y 델타는 양수의 Y 변화에 따라 화면에서 "위"로 가도록 음수로 설정
local deltaY = -math.sin(deltaX / pixelsPerRadian) * maxHeightChange
return UDim2.fromOffset(deltaX, deltaY)
end
uiDragDetector:SetDragStyleFunction(computeSinWaveCoordinate)
사용자 지정 제약 함수
UIDragDetectors에는 그리드 및 스냅에 관한 내장된 움직임 규칙이 없지만, 탐지기의 UIDragDetector.DragUDim2 및 UIDragDetector.DragRotation이 적용되기 전에 편집할 사용자 지정 제약 함수를 등록할 수 있습니다. 예를 들어, 특정 증가로 위치를 반올림하여 움직임을 그리드로 제한하거나 허용된 움직임 영역을 정의할 수 있습니다. 이는 기존의 변환/회전 제한 이전에 적용되는 점을 참고하세요.
다음 예제는 행과 열의 수에 따라 평면 드래그를 X/Y 그리드로 클램프하는 제약 함수를 활용합니다. 탐지기의 ResponseStyle는 Enum.UIDragDetectorResponseStyle.Scale로 설정되어 있으며, 그리드 컨테이너로 설정된 BoundingUI도 있습니다.
UIDragDetector - 그리드에서 드래그, 타일로 스냅하기
-- 계층 구조는 GridContainer ⟩ Handle ⟩ UIDragDetector ⟩ (이 스크립트)
local gridContainer = script.Parent.Parent.Parent
local handle = gridContainer:FindFirstChild("Handle") -- 드래그할 UI 요소
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")
uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale -- 스케일로 드래깅 설정
uiDragDetector.DragRelativity = Enum.UIDragDetectorDragRelativity.Relative
uiDragDetector.BoundingUI = gridContainer
local NUM_COLUMNS = 10
local NUM_ROWS = 5
local xScaleIncrement = 1 / NUM_COLUMNS
local yScaleIncrement = 1 / NUM_ROWS
local initialParentPosition = uiDragDetector.Parent.Position
uiDragDetector.DragStart:Connect(function()
initialParentPosition = uiDragDetector.Parent.Position
end)
local function dragToGridOnly(proposedPosition, proposedRotation)
local griddedXScale = math.round(proposedPosition.X.Scale / xScaleIncrement) * xScaleIncrement
local griddedYScale = math.round(proposedPosition.Y.Scale / yScaleIncrement) * yScaleIncrement
return UDim2.fromScale(griddedXScale, griddedYScale), proposedRotation
end
uiDragDetector:AddConstraintFunction(1, dragToGridOnly)