Detectores de arrasto 3D

A instância DragDetector facilita e incentiva a interação com objetos 3D em um jogo, como abrir portas e gavetas, deslizar uma parte, pegar e lançar uma bola de boliche, puxar e disparar uma funda, e muito mais. Os principais recursos incluem:

• Coloque um DragDetector sob qualquer BasePart ou Model para torná-lo arrastável via todas as entradas (mouse, toque, gamepad e VR), tudo isso sem uma única linha de código.

• Escolha entre vários estilos de arrasto, defina como o objeto responde ao movimento e, opcionalmente, aplique limites de eixo ou movimento.

• Scripts podem responder à manipulação de objetos arrastados para acionar a interface do usuário ou tomar decisões lógicas, como ajustar o nível de luz em uma sala com base em um dimmer de interruptor deslizante.

• Os jogadores podem manipular partes ou modelos ancorados e eles permanecerão exatamente onde você os colocou ao serem soltos.

• DragDetectors funcionam no Studio, desde que você não esteja usando as ferramentas Selecionar, Mover, Escalar ou Rotacionar, facilitando o teste e ajuste de objetos arrastáveis enquanto edita.

Tornar objetos arrastáveis

Para tornar qualquer parte ou modelo arrastável, basta adicionar um DragDetector como um descendente direto.

1. Na janela Explorer, passe o mouse sobre a Part, MeshPart ou Model e clique no botão ⊕. Um menu contextual será exibido.

2. No menu, insira um DragDetector.

   

3. Por padrão, o objeto agora será arrastável no plano do solo, mas você pode personalizar seu DragStyle, definir como ele responde ao movimento e, opcionalmente, aplicar limites de eixo ou movimento.

Personalizar detectores de arrasto

Estilo de arrasto

DragDetectors mapeiam o movimento do cursor para linhas e planos virtuais para calcular o movimento 3D proposto. Através da propriedade DragStyle, você pode escolher entre diferentes mapeamentos para atender às suas necessidades. Por exemplo, TranslatePlane produz tradução em um plano virtual, enquanto RotateAxis produz rotação em torno de um eixo virtual.

Direção do arrasto

Por padrão, o movimento 3D e o DragStyle associado mapeiam para o espaço do mundo. No entanto, você pode querer mudar o ReferenceInstance, Orientation ou Axis, por exemplo, ao construir detectores de arrasto em modelos com partes ajustáveis.

Resposta ao movimento

A propriedade ResponseStyle especifica como um objeto responde ao movimento proposto, dependendo se o objeto está Anchored ou não.

Limites de eixo e movimento

Por padrão, não há limites para o movimento 3D além das restrições inerentes do DragStyle. Se necessário, você pode aplicar limites mínimos e máximos tanto para a tradução quanto para a rotação. Note, no entanto, que estes não são restrições; eles apenas impedem as tentativas do detector de arrasto de gerar movimento para permanecer dentro dos limites.

Permissões de arrasto

A permissão dos jogadores para interagir com uma determinada instância de detector de arrasto pode ser especificada pela propriedade PermissionPolicy. Isso é definido como Enum.DragDetectorPermissionPolicy.Everybody por padrão, e também pode ser alterado para suportar controles de permissão scriptados, conforme mostrado no exemplo de código.

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)

Resposta física

Assumindo que o estilo de resposta de um arrastador está definido como Physical e é aplicado a um objeto não ancorado, esse objeto será movido por forças de restrição que tentam trazê-lo para a posição/orientação dada pelo movimento proposto. Você pode personalizar ainda mais a resposta física através das seguintes propriedades:

Entrada de modificador

Alguns modos de DragStyle permitem que os usuários mantenham pressionada uma tecla/botão modificador para manipular o objeto arrastado de diferentes maneiras. Por padrão, o modificador é LeftControl no PC, ButtonR1 no gamepad ou ButtonL2 no VR. Você pode personalizar esses modificadores através das propriedades KeyboardModeSwitchKeyCode, GamepadModeSwitchKeyCode ou VRSwitchKeyCode da instância do detector de arrasto.

Replicação

Quando a propriedade RunLocally é falsa (padrão), o cliente interpreta toda a entrada para produzir dados que envia ao servidor para realizar o arrasto. Neste modo, todos os sinais de eventos personalizados e funções registradas devem estar nos Scripts do servidor.

Quando a propriedade RunLocally é verdadeira, nenhum evento é replicado para o servidor. Todos os sinais de eventos personalizados e funções registradas devem estar nos LocalScripts do cliente e você deve usar eventos remotos para propagar as alterações necessárias para o servidor.

Respostas de script ao clicar e arrastar

Através de sinais de eventos, alterações de propriedades, estilo de arrasto Scriptable e funções personalizadas, scripts podem responder à manipulação de objetos arrastados para acionar a interface do usuário ou tomar decisões lógicas, como ajustar o nível de luz em uma sala com base em um dimmer de interruptor deslizante.

Sinais de eventos

Através dos seguintes sinais de eventos, você pode detectar quando um usuário começa, continua e termina de arrastar um objeto.

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)

Alterações no quadro de arrasto

Além dos sinais de eventos, você pode monitorar alterações no DragFrame do detector diretamente.

local dragDetector = script.Parent.DragDetector

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

Estilo de arrasto scriptado

Se você definir o DragStyle de um detector como Scriptable, você pode fornecer sua própria função que recebe um Ray e retorna um CFrame no espaço do mundo. O detector moverá o movimento para que o objeto arrastado vá para aquela localização/orientação personalizada.

local Workspace = game:GetService("Workspace")

local dragDetector = script.Parent.DragDetector
dragDetector.DragStyle = Enum.DragDetectorDragStyle.Scriptable

local cachedHitPoint = Vector3.zero
local cachedHitNormal = Vector3.yAxis

local function followTheCursor(cursorRay)
	-- Excluir objeto arrastado da detecção de raycast
	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)

Função de restrição personalizada

Os detectores de arrasto não têm regras de movimento integradas sobre grades e encaixes, mas você pode registrar funções de restrição personalizadas para editar o DragFrame do detector antes que ele seja aplicado. Por exemplo, você pode manter o movimento em uma grade arredondando posições para múltiplos do incremento da grade, ou simular um jogo de xadrez com regras de movimento legais para cada peça.

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 = SNAP_INCREMENT // 1
	if snapIncrement < 1 then
		return proposedMotion
	end
	local newWorldPosition = startPartPosition + proposedMotion.Position
	local roundedX = ((newWorldPosition.X / snapIncrement + 0.5) // 1) * snapIncrement
	local roundedY = ((newWorldPosition.Y / snapIncrement + 0.5) // 1) * snapIncrement
	local roundedZ = ((newWorldPosition.Z / snapIncrement + 0.5) // 1) * snapIncrement
	local newRoundedWorldPosition = Vector3.new(roundedX, roundedY, roundedZ)
	return proposedMotion.Rotation + (newRoundedWorldPosition - startPartPosition)
end

local connection = dragDetector:AddConstraintFunction(2, snapToWorldGrid)
-- Quando aplicável, remova a função de restrição invocando connection:Disconnect()

Exemplo de uso

Objetos físicos não ancorados

Uma implementação básica de detectores de arrasto é um jogo de equilíbrio de torre onde os jogadores devem cuidadosamente remover peças e tentar manter a torre em pé. Na seguinte estrutura de torre, cada peça tem um DragDetector filho com um DragStyle padrão de TranslatePlane para que os jogadores possam puxar as peças para fora, mas não para cima ou para baixo.

Modelos ancorados com partes ajustáveis

Você pode facilmente criar e compartilhar modelos que são principalmente ancorados, mas que têm uma ou mais partes/modelos filhos que os jogadores podem arrastar. Por exemplo, a seguinte mesa tem duas gavetas que os jogadores podem abrir para inspecionar o que há dentro.

Detectores de arrasto e restrições

Você pode combinar detectores de arrasto com Constraints, por exemplo, uma marionete. Na seguinte configuração, os controles são ancorados, as partes do corpo são não ancoradas e as restrições mantêm a marionete unida. Mover os controles com o estilo de arrasto TranslateViewPlane faz a marionete dançar, e as partes do corpo individuais também podem ser movidas com detectores de arrasto, tudo enquanto o modelo mantém sua integridade.

Interfaces de usuário 3D

Interfaces de usuário 3D são facilmente alcançáveis através de detectores de arrasto, como ajustar o brilho de um SpotLight com base em um dimmer de interruptor deslizante. Você também pode detectar os eixos X e Z individualmente para controlar dois aspectos diferentes de uma interface de usuário 3D, como o Size, Speed e Color de um ParticleEmitter.

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

	-- Ajustar o tamanho e a velocidade das partículas com base no fator X do detector de arrasto
	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)
	-- Ajustar a cor das partículas com base no fator Z do detector de arrasto
	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)