Caminhos 2D

A instância Path2D, juntamente com seus métodos e propriedades da API, permite implementar splines 2D e linhas curvas 2D, úteis para efeitos de UI como animações baseadas em caminhos e editores de gráfico.

Criar um caminho 2D

Para adicionar um Path2D à tela ou a um objeto dentro da experiência:

1. Na janela Explorer, insira uma instância Path2D sob um ScreenGui ou SurfaceGui visível (não precisa ser um filho direto).

   

2. Selecione o novo Path2D para revelar o widget de ferramentas no visualizador. Por padrão, a ferramenta Adicionar Ponto está selecionada.

   

3. Comece a clicar na tela para adicionar uma série de pontos de controle para formar um caminho. O caminho inicial provavelmente será impreciso, mas você pode ajustar a posição de qualquer ponto de controle mais tarde.

   

   Se você arrastar o mouse após clicar, tangentes serão criadas naquele ponto. Tangentes também podem ser adicionadas procedimentalmente a qualquer ponto de controle.

4. Quando terminar, clique no botão Concluído do widget ou pressione Enter.

Modificar pontos de controle

Com um Path2D selecionado na hierarquia do Explorer, você pode modificar seus pontos de controle individuais, bem como suas tangentes.

Mover pontos

Para mover um ponto de controle individual em um caminho, habilite a ferramenta Selecionar (V) e, em seguida, clique e arraste para uma nova posição.

Para um posicionamento muito específico, selecione o ponto de controle e, em seguida, na janela Propriedades, defina uma nova posição para a propriedade SelectedControlPointData do ponto (UDim2).

Observe que a posição de um ponto não é absoluta, mas sim relativa ao contêiner pai do caminho. Por exemplo, compare um ponto de controle 30% da esquerda e 20% do topo de um caminho dentro de um ScreenGui, em comparação com um caminho idêntico colocado dentro de um Frame localizado no canto superior direito do ScreenGui.

Adicionar pontos

Novos pontos de controle podem ser adicionados a um Path2D entre dois pontos existentes ou de qualquer extremidade usando a ferramenta Adicionar Ponto (P).

Excluir pontos

Para excluir um ponto de controle, passe o mouse sobre ele e clique com o botão direito, em seguida, selecione Excluir Ponto no menu pop-up contextual.

Tangentes do ponto de controle

As tangentes do ponto de controle permitem que você crie e ajuste curvas em um caminho.

Adicionar tangentes

Para adicionar tangentes a qualquer ponto de controle que ainda não tenha tangentes:

1. Habilite a ferramenta Adicionar Tangente no widget de ferramentas.

   

2. Passe o mouse sobre o ponto de controle desejado e clique para adicionar duas tangentes espelhadas (opcionalmente, arraste após clicar para ajustar as novas tangentes).

   

Ajustar tangentes

Para ajustar as tangentes existentes de um ponto de controle individual:

1. Habilite a ferramenta Selecionar (V).

   

2. Passe o mouse sobre um marcador de tangente (não sobre o ponto de controle), e clique e arraste para uma nova posição. Se as tangentes estiverem espelhadas, o ponto de tangente emparelhado se moverá em uníssono.

   

Para definir manualmente uma posição específica UDim2 para uma tangente:

1. Habilite a ferramenta Selecionar (V) e selecione o ponto de controle. Na janela Propriedades, expanda o campo SelectedControlPointData para expor as propriedades LeftTangent e RightTangent.

   

2. Defina a posição para LeftTangent e/ou RightTangent. Observe que isso irá quebrar o comportamento espelhado das tangentes.

Excluir tangentes

Para excluir ambas as tangentes de um ponto de controle, passe o mouse sobre e clique com o botão direito naquele ponto, em seguida, selecione Limpar Tangentes no menu pop-up contextual.

Para excluir apenas uma das tangentes (esquerda ou direita), passe o mouse sobre e clique com o botão direito no marcador daquela tangente, em seguida, selecione Excluir Tangente.

Quebrar e espelhar

Por padrão, as tangentes se espelham mutuamente. Quando você arrasta para ajustar um marcador de tangente, o ponto de tangente emparelhado se moverá em uníssono.

Para "quebrar" as tangentes de modo que cada uma possa ser movida independentemente da outra, passe o mouse sobre e clique com o botão direito no ponto de controle associado, em seguida, selecione Quebrar Tangentes no menu contextual. Uma vez quebradas, você pode mover cada marcador de tangente sem afetar o outro.

Propriedades visuais do caminho

Você pode personalizar a aparência visual de um Path2D com as seguintes propriedades:

Scripting de caminhos

A programação é útil para vários fluxos de trabalho relacionados a caminhos. Os seguintes exemplos usam métodos como GetControlPoints() que retorna uma tabela de Path2DControlPoints e GetPositionOnCurveArcLength() que retorna a posição UDim2 em um determinado valor t ao longo da spline.

Arranjar Objetos de UI ao Longo do Caminho
local parent = script.Parent
local path = parent:FindFirstChildWhichIsA("Path2D")

local function arrangeChildren()
	local segmentCount = #path:GetControlPoints()
	local objectsToArrange = {}

	for _, child in parent:GetChildren() do
		if child:IsA("GuiObject") then
			table.insert(objectsToArrange, child)
		end
	end

	for idx, child in objectsToArrange do
		local t = idx / (#objectsToArrange + 1)
		child.Position = path:GetPositionOnCurveArcLength(t)
	end
end

-- Arranjar inicialmente os objetos filhos de UI ao longo do caminho
arrangeChildren()

-- Ouvir o aumento/remocão de filhos para ajustar o arranjo
parent.ChildAdded:Connect(arrangeChildren)
parent.ChildRemoved:Connect(arrangeChildren)

Animar Objeto de UI ao Longo do Caminho
local Tweenservice = game:GetService("TweenService")

local parent = script.Parent
local path = parent:FindFirstChildWhichIsA("Path2D")
local objectToAnimate = parent:FindFirstChildWhichIsA("GuiObject")

local TWEEN_DURATION = 4
local TWEEN_EASING_STYLE = Enum.EasingStyle.Cubic
local TWEEN_EASING_DIRECTION = Enum.EasingDirection.InOut

local pathSampleValue = Instance.new("NumberValue")
local tweenInfo = TweenInfo.new(TWEEN_DURATION, TWEEN_EASING_STYLE, TWEEN_EASING_DIRECTION, 0, true, 2)
local tween = Tweenservice:Create(pathSampleValue, tweenInfo, {Value = 1})

local function onSampleValueChanged()
	objectToAnimate.Position = path:GetPositionOnCurveArcLength(pathSampleValue.Value)
end
pathSampleValue.Changed:Connect(onSampleValueChanged)

tween:Play()