Navegação é o processo de mover um personagem ou objeto (agente) ao longo de um caminho lógico ao redor de obstáculos para alcançar um destino, evitando opcionalmente materiais perigosos ou regiões definidas.
Visualização de navegação
Para ajudar com o layout e depuração da navegação, o Studio pode renderizar uma malha de navegação e rótulos de modificadores. Para habilitá-los, ative Malha de Navegação e Modificadores de Navegação no widget de Opções de Visualização no canto superior direito da viewport 3D.

Com Malha de Navegação habilitada, áreas coloridas mostram onde um personagem pode andar ou nadar. Pequenas setas indicam áreas que um personagem tentará alcançar pulando.

Implementação
Embora a navegação possa ser implementada de várias maneiras através de PathfindingService e seus métodos associados, como CreatePath(), esta seção usa o seguinte script de navegação para o personagem do jogador.
Para testar enquanto lê:
- IMPORTANTENo Explorer, selecione o contêiner StarterPlayer. Em seguida, na janela de Propriedades, defina tanto DevComputerMovementMode quanto DevTouchMovementMode como Scriptable.


Copie o seguinte código para um LocalScript dentro de StarterCharacterScripts, ou obtenha este pacote e coloque-o em StarterCharacterScripts.
PlayerPathFollow (LocalScript in StarterCharacterScripts)local PathfindingService = game:GetService("PathfindingService")local Players = game:GetService("Players")local RunService = game:GetService("RunService")local DESTINATION = Vector3.new(20, 0.5, 20)local GROUND_WAIT = 0.01local VELOCITY_MULTIPLIER = 0.0625local path = PathfindingService:CreatePath({AgentCanClimb = true,Costs = {Water = 20}})local character = script.Parentlocal humanoid = character:WaitForChild("Humanoid")local waypointslocal nextWaypointIndexlocal blockedConnectionlocal currentWaypointReachedConnectionlocal currentWaypointPlaneNormal = Vector3.zerolocal currentWaypointPlaneDistance = 0local pathfinderWorking = falselocal function disconnectCurrentWaypointReachedConnection()if not currentWaypointReachedConnection then return endcurrentWaypointReachedConnection:Disconnect()currentWaypointReachedConnection = nilendlocal function isCurrentWaypointReached()if humanoid.FloorMaterial == Enum.Material.Air thenreturn falseendlocal reached = falseif currentWaypointPlaneNormal ~= Vector3.zero then-- Compute the distance from humanoid to destination planelocal dist = currentWaypointPlaneNormal:Dot(humanoid.RootPart.Position) - currentWaypointPlaneDistance-- Compute the component of the humanoid velocity that is towards the planelocal velocity = -currentWaypointPlaneNormal:Dot(humanoid.RootPart.Velocity)-- Compute the threshold from the destination plane based on humanoid velocitylocal threshold = math.max(1.0, VELOCITY_MULTIPLIER * velocity)-- Consider waypoint reached if less then threshold in front of the planereached = dist < thresholdelsereached = trueendif reached thencurrentWaypointPlaneNormal = Vector3.zerocurrentWaypointPlaneDistance = 0moveToNextWaypoint()endendlocal function calculateNextWaypointApproach()nextWaypointIndex += 1if nextWaypointIndex > #waypoints thenreturn falseendlocal currentWaypoint = waypoints[nextWaypointIndex - 1]local nextWaypoint = waypoints[nextWaypointIndex]-- Build destination plane from next waypoint towards current onecurrentWaypointPlaneNormal = currentWaypoint.Position - nextWaypoint.Position-- Set normal perpendicular to Y plane when not climbing upif nextWaypoint.Label ~= "Climb" thencurrentWaypointPlaneNormal = Vector3.new(currentWaypointPlaneNormal.X, 0, currentWaypointPlaneNormal.Z)endif currentWaypointPlaneNormal.Magnitude > 0.000001 thencurrentWaypointPlaneNormal = currentWaypointPlaneNormal.UnitcurrentWaypointPlaneDistance = currentWaypointPlaneNormal:Dot(nextWaypoint.Position)endreturn trueendlocal function resetWaypointData()humanoid:Move(Vector3.zero)currentWaypointPlaneNormal = Vector3.zerocurrentWaypointPlaneDistance = 0disconnectCurrentWaypointReachedConnection()pathfinderWorking = falseendlocal function waitForGround()while humanoid.FloorMaterial == Enum.Material.Air dotask.wait(GROUND_WAIT)endendfunction moveToNextWaypoint()if calculateNextWaypointApproach() thendisconnectCurrentWaypointReachedConnection()currentWaypointReachedConnection = RunService.Heartbeat:Connect(isCurrentWaypointReached)local nextWaypointPosition = waypoints[nextWaypointIndex].Positionlocal nextWaypointAction = waypoints[nextWaypointIndex].Actionhumanoid:Move(nextWaypointPosition - humanoid.RootPart.Position)if waypoints[nextWaypointIndex + 1] and waypoints[nextWaypointIndex + 1].Label == "UseBoat" thennextWaypointIndex += 1-- Call your own customized function to make agent use the boatelseif nextWaypointAction == Enum.PathWaypointAction.Jump thenhumanoid:ChangeState(Enum.HumanoidStateType.Jumping)while humanoid.FloorMaterial ~= Enum.Material.Air dotask.wait(GROUND_WAIT)endhumanoid:Move(nextWaypointPosition - humanoid.RootPart.Position)endelseresetWaypointData()endendlocal function findStartingPoint(waypoints)nextWaypointIndex = 1while nextWaypointIndex + 1 <= #waypoints dolocal dist = waypoints[nextWaypointIndex + 1].Position - humanoid.RootPart.Positiondist = Vector3.new(dist.X, 0, dist.Z)if dist.magnitude >= 2 thenreturnendnextWaypointIndex += 1endendlocal function followPath()-- Compute the pathpathfinderWorking = truewaitForGround()local success, errorMessage = pcall(function()path:ComputeAsync(character.PrimaryPart.Position, DESTINATION)end)if not success or path.Status ~= Enum.PathStatus.Success thenwarn("Caminho não computado!", errorMessage)returnend-- Get the path waypointswaypoints = path:GetWaypoints()-- Detect if path becomes blockedblockedConnection = path.Blocked:Connect(function(blockedWaypointIndex)-- Check if the obstacle is further down the pathif blockedWaypointIndex >= nextWaypointIndex then-- Stop detecting path blockage until path is re-computedblockedConnection:Disconnect()resetWaypointData()-- Call function to re-compute new pathfollowPath()endend)findStartingPoint(waypoints)moveToNextWaypoint()endfollowPath()Edite a variável DESTINATION (
LINHA 5) para um destino Vector3 dentro do mundo 3D que o personagem do jogador pode alcançar.Prossiga pelas seções seguintes para aprender sobre a computação de caminhos e o movimento do personagem.
Criação de caminho
A navegação é iniciada através de PathfindingService e seu método CreatePath() (
| Chave | Descrição | Tipo | Padrão |
|---|---|---|---|
| AgentRadius | Raio do agente, em studs. Útil para determinar a separação mínima de obstáculos. | inteiro | 2 |
| AgentHeight | Altura do agente, em studs. Espaço vazio menor que este valor, como o espaço sob escadas, será marcado como não transitável. | inteiro | 5 |
| AgentCanJump | Determina se pular durante a navegação é permitido. | booleano | true |
| AgentCanClimb | Determina se escalar TrussParts durante a navegação é permitido. Um caminho escalável tem um Label chamado Climb e o custo para um caminho escalável é 1 por padrão. | booleano | false |
| WaypointSpacing | Espaçamento entre waypoints intermediários no caminho. Se definido como math.huge, não haverá waypoints intermediários. | número | 4 |
| Costs | Tabela de materiais ou PathfindingModifiers definidos e seu custo para travessia. Útil para fazer o agente preferir certos materiais/regiões em vez de outros. Veja modificadores para detalhes. | tabela | nil |
Computação de caminho
Depois de criar um caminho válido com CreatePath(), ele deve ser computado chamando Path:ComputeAsync() com um Vector3 tanto para o ponto de partida quanto para o destino (

Uma vez que o Path é computado, ele conterá uma série de waypoints que traçam o caminho do início ao fim. Esses pontos podem ser coletados com o método Path:GetWaypoints() (

Movimento pelo caminho
Cada PathWaypoint consiste em uma Position (Vector3) e uma Action (PathWaypointAction). Para mover um personagem contendo um Humanoid, como um personagem típico do Roblox, a melhor maneira é chamar Humanoid:Move() de waypoint para waypoint e usar o callback isCurrentWaypointReached() do script (
Caminhos bloqueados
Muitos mundos do Roblox são dinâmicos; partes podem se mover ou cair e pisos podem desabar. Isso pode bloquear um caminho computado e impedir que o personagem alcance seu destino. Para lidar com isso, você pode conectar o evento Path.Blocked e recomputar o caminho ao redor do que o bloqueou (
Modificadores de navegação
Por padrão, Path:ComputeAsync() retorna o caminho mais curto entre o ponto de partida e o destino, com a exceção de que tenta evitar pulos. Isso parece antinatural em algumas situações; por exemplo, um caminho pode passar pela água do pântano em vez de contorná-la simplesmente porque o caminho pela água é geometricamente mais curto.

Para otimizar ainda mais a navegação, você pode implementar modificadores de navegação para computar caminhos mais inteligentes através de vários materiais, ao redor de regiões definidas, ou para ignorar obstáculos.
Custos de materiais
Ao trabalhar com materiais de Terrain e BasePart, você pode incluir uma tabela Costs dentro de CreatePath() para tornar certos materiais mais transitáveis do que outros. Todos os materiais têm um custo padrão de 1 e qualquer material pode ser definido como não transitável definindo seu valor como math.huge.
As chaves na tabela Costs devem ser nomes string representando nomes de Enum.Material, por exemplo Water para Enum.Material.Water ou CrackedLava para Enum.Material.CrackedLava.
local PathfindingService = game:GetService("PathfindingService")
local Players = game:GetService("Players")
local RunService = game:GetService("RunService")
local DESTINATION = Vector3.new(20, 0.5, 20)
local GROUND_WAIT = 0.01
local VELOCITY_MULTIPLIER = 0.0625
local path = PathfindingService:CreatePath({
AgentCanClimb = true,
Costs = {
Water = 20, CrackedLava = 100, Slate = 20
}
})Configurar regiões
Em alguns casos, a preferência de material não é suficiente. Por exemplo, você pode querer que os personagens evitem uma região definida, independentemente dos materiais sob os pés. Isso pode ser alcançado adicionando um objeto PathfindingModifier a uma parte.
Crie uma parte Anchored ao redor da região e defina sua propriedade CanCollide como false.

Insira uma instância PathfindingModifier na parte, localize sua propriedade Label e atribua um nome significativo como DangerZone.

Inclua uma chave correspondente DangerZone e um valor numérico associado dentro da tabela Costs de CreatePath(). Um modificador pode ser definido como não transitável definindo seu valor como math.huge.
PlayerPathFollow (LocalScript)local PathfindingService = game:GetService("PathfindingService")local Players = game:GetService("Players")local RunService = game:GetService("RunService")local DESTINATION = Vector3.new(20, 0.5, 20)local GROUND_WAIT = 0.01local VELOCITY_MULTIPLIER = 0.0625local path = PathfindingService:CreatePath({AgentCanClimb = true,Costs = {DangerZone = math.huge, Water = 20, CrackedLava = 20, Slate = 20}})
Ignorar obstáculos
Em alguns casos, é útil navegar através de obstáculos sólidos como se eles não existissem. Isso permite que você compute um caminho através de bloqueadores físicos específicos, em vez de a computação falhar completamente.
Crie uma parte Anchored ao redor do objeto e defina sua propriedade CanCollide como false.

Insira uma instância PathfindingModifier na parte e habilite sua propriedade PassThrough.

Agora, quando um caminho é computado do NPC zumbi para o personagem do jogador, o caminho se estende além da porta e você pode fazer o zumbi atravessá-la. Mesmo que o zumbi não consiga abrir a porta, ele reage como se "ouvisse" o personagem atrás da porta.

Links de navegação
Às vezes, é necessário encontrar um caminho através de um espaço que não pode ser normalmente atravessado, como através de um abismo, e realizar uma ação personalizada para alcançar o próximo waypoint. Isso pode ser alcançado através do objeto PathfindingLink.
Usando o exemplo acima, você pode fazer o agente usar um barco.

Para criar um PathfindingLink usando este exemplo:
- OPCIONALAtive Links de Navegação no widget de Opções de Visualização no canto superior direito da viewport 3D. Isso ajuda na visualização e depuração ao implementar links de navegação.
Crie dois Attachments, um no assento do barco e um perto do ponto de desembarque do barco.

Crie um objeto PathfindingLink no workspace e, em seguida, atribua suas propriedades Attachment0 e Attachment1 aos anexos de início e fim, respectivamente.


Atribua um nome significativo como UseBoat à sua propriedade Label. Este nome é usado como uma flag no script de navegação para acionar uma ação personalizada quando o agente alcança o ponto de início do link.

Inclua uma tabela Costs dentro de CreatePath() contendo tanto uma chave Water quanto uma chave personalizada que corresponda ao nome da propriedade Label. Atribua à chave personalizada um valor menor do que o de Water.
PlayerPathFollow (LocalScript)local PathfindingService = game:GetService("PathfindingService")local Players = game:GetService("Players")local RunService = game:GetService("RunService")local DESTINATION = Vector3.new(20, 0.5, 20)local GROUND_WAIT = 0.01local VELOCITY_MULTIPLIER = 0.0625local path = PathfindingService:CreatePath({AgentCanClimb = true,Costs = {UseBoat = 2, Water = 20}})Na função moveToNextWaypoint() (
LINHAS 93–114), uma verificação personalizada para o nome do modificador Label pode ser usada para realizar uma ação diferente de Humanoid:Move(); neste caso, você pode chamar uma função para colocar o agente no barco, mover o barco através da água, retirar o agente no ponto de desembarque do barco e, em seguida, continuar o caminho do agente até seu destino final.
Compatibilidade com streaming
O streaming de instâncias no jogo é um recurso poderoso que carrega e descarrega dinamicamente conteúdo 3D à medida que o personagem de um jogador se move pelo mundo. À medida que eles exploram o espaço 3D, novos subconjuntos do espaço são transmitidos para seu dispositivo e alguns dos subconjuntos existentes podem ser descarregados.
Considere as seguintes melhores práticas para usar PathfindingService em jogos com streaming habilitado:
O streaming pode bloquear ou desbloquear um determinado caminho à medida que um personagem se move ao longo dele. Por exemplo, enquanto um personagem corre por uma floresta, uma árvore pode ser transmitida em algum lugar à frente deles e obstruir o caminho. Para fazer a navegação funcionar perfeitamente com o streaming, é altamente recomendável que você use a técnica de manipulação de caminhos bloqueados e recompute o caminho quando necessário.
Uma abordagem comum na navegação é usar as coordenadas de objetos existentes para computação, como definir um destino de caminho para a posição de um modelo TreasureChest existente no mundo. Essa abordagem é totalmente compatível com Scripts do lado do servidor, uma vez que o servidor tem visão total do mundo o tempo todo, mas LocalScripts e ModuleScripts que são executados no cliente podem falhar se tentarem computar um caminho para um objeto que não está transmitido.
Para resolver esse problema, considere definir o destino para a posição de uma BasePart dentro de um modelo persistente. Modelos persistentes são carregados logo após o jogador entrar e nunca são descarregados, então um script do lado do cliente pode se conectar ao evento PersistentLoaded e acessar com segurança o modelo para criar waypoints após o evento ser disparado.
Limitações e fatores de falha
O mecanismo de navegação inclui limitações específicas para garantir processamento eficiente e desempenho ideal. Além disso, as computações de navegação podem falhar por vários motivos, conforme descrito abaixo.