--- title: "Agente de navegação" version: snapshot-2026-10-09 engineGeneration: astra-current language: C# status: source-reviewed reviewedAt: 2026-10-09 appRelease: "0.3.0-preview.20261009" runtimeVerified: false platformEvidence: [] url: https://astraengine.com.br/pt-br/snapshot-2026-10-09/componentes/astra-navigation-agent/ --- # Agente de navegação Anda pela malha até um destino, desviando de outros agentes **Família:** Navegação · **Grupo:** Movimento · **Identificador:** `astra.navigation.agent` · **Payload:** 1 :::note[Escopo da evidência] Este contrato foi extraído dos descritores compilados da engine, incluindo padrões resolvidos. A presença do contrato não substitui a validação do comportamento em um aparelho. ::: ## Para que usar Anda pela malha até um destino ou persegue um objeto, desviando de outros agentes. Entrega a velocidade a quem move o objeto. Em um objeto com Personagem, Motor dinâmico, corpo móvel ou sem física, adicione o Agente. Defina Velocidade, Aceleração e Distância de parada. Para perseguir sem script, escolha **Seguir objeto**; por script use SetDestination(Vector3). ## Criar e configurar Hierarquia → selecione o objeto → Inspector → Adicionar componente → **Navegação** / **Movimento** → **Agente de navegação**. O schema permite uma única instância desse tipo por objeto. A fachada C# correspondente é [Astra.Components.NavAgent](/pt-br/snapshot-2026-10-09/api/astra-components-navagent/). Personagem e Motor dinâmico recebem a velocidade pela posse de controle, fonte IA (a menor prioridade: jogador e scripts vencem); corpo móvel recebe velocidade linear; sem física, o agente move a própria pose (um filho com corpo físico impede isso e o cartão avisa). Frear ao chegar desacelera antes da distância de parada. Stop guarda o destino para Resume; Warp teleporta Personagem ou pose para a malha. **Guia relacionado:** [Guia de navegação](/pt-br/snapshot-2026-10-09/sistemas/navegacao/) · [Posse de controle](/pt-br/snapshot-2026-10-07/sistemas/posse-de-controle/) ## Exemplo de uso Crie Criar → Navegação → Agente perseguidor com o alvo selecionado. Em Play, o Personagem contorna a parede até ficar à distância de parada. Pelo Behavior: `var agente = Object.GetComponent()!.Value; agente.SetDestination(new Vector3(7,0,-7));` e inscreva `OnDestinationReached`. ## Dependências Nenhuma regra adicional declarada no schema deste componente. ## Conflitos - [Path Follow](/pt-br/snapshot-2026-10-09/componentes/astra-path-follow/): Agente e Seguir caminho escreveriam a mesma pose - [Obstáculo de navegação](/pt-br/snapshot-2026-10-09/componentes/astra-navigation-obstacle/): Um objeto é agente ou obstáculo, não os dois ## Edição e ciclo de vida | Operação | Contrato | |---|---| | Adicionar/remover em Play | ponto seguro | | Alterar propriedades em Play | ponto seguro | | Múltiplas instâncias | Não | | Versão do payload | 1 | Alterações em ponto seguro são aplicadas entre passos da simulação. Um componente exigido por outro não pode ser removido enquanto a dependência existir. Salvar a cena autoral e modificar o mundo de Play são operações distintas; veja [Play e cena autoral](/pt-br/snapshot-2026-10-06/conceitos/play-e-cena-autoral/). ## Propriedades Valores abaixo são resolvidos pelo descritor de um componente recém-criado. Campos por slot dependem dos recursos atribuídos. Um campo sem padrão significa que o descritor não fornece um valor independente de contexto. ### Movimento | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Velocidade**](#field-speed)
`speed` | número · m/s | 3.5 | 0 … 1000 | | [**Aceleração**](#field-acceleration)
`acceleration` | número · m/s² | 8 | 0 … 1000 | | [**Giro**](#field-angular-speed)
`angular_speed` | número · °/s | 120 | 0 … 3600 | | [**Distância de parada**](#field-stopping-distance)
`stopping_distance` | número · m | 0 | 0 … 1000 | | [**Refazer caminho a**](#field-repath-distance)
`repath_distance` | número · m | 0.5 | 0.05 … 100 | | [**Frear ao chegar**](#field-auto-braking)
`auto_braking` | booleano | verdadeiro | verdadeiro \| falso | | [**Girar para o movimento**](#field-update-rotation)
`update_rotation` | booleano | verdadeiro | verdadeiro \| falso |

Velocidade · speed

**Onde:** Inspector → **Agente de navegação** → **Movimento** → **Velocidade**. **Uso e efeito:** Velocidade máxima pedida à multidão, em m/s. Com Personagem, o agente nunca passa da velocidade do próprio Personagem. **Valor:** 3.5 · **Tipo:** número · **Unidade:** m/s · **Domínio:** 0 … 1000.

Aceleração · acceleration

**Onde:** Inspector → **Agente de navegação** → **Movimento** → **Aceleração**. **Uso e efeito:** Quanto a velocidade pode mudar por segundo, em m/s². Também limita a frenagem ao chegar. **Valor:** 8 · **Tipo:** número · **Unidade:** m/s² · **Domínio:** 0 … 1000.

Giro · angular_speed

**Onde:** Inspector → **Agente de navegação** → **Movimento** → **Giro**. **Uso e efeito:** Velocidade de giro, em graus/s, para virar o objeto na direção do movimento (Personagem e própria pose). **Valor:** 120 · **Tipo:** número · **Unidade:** °/s · **Domínio:** 0 … 3600. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Distância de parada · stopping_distance

**Onde:** Inspector → **Agente de navegação** → **Movimento** → **Distância de parada**. **Uso e efeito:** Distância do destino em que o agente considera que chegou e para; emite o evento de chegada uma vez. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** 0 … 1000.

Refazer caminho a · repath_distance

**Onde:** Inspector → **Agente de navegação** → **Movimento** → **Refazer caminho a**. **Uso e efeito:** Quanto o objeto seguido precisa se mover, em metros, para o caminho ser refeito. **Valor:** 0.5 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.05 … 100. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Frear ao chegar · auto_braking

**Onde:** Inspector → **Agente de navegação** → **Movimento** → **Frear ao chegar**. **Uso e efeito:** Desacelera antes do destino para parar na distância de parada. Desligado mantém a velocidade até chegar. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Girar para o movimento · update_rotation

**Onde:** Inspector → **Agente de navegação** → **Movimento** → **Girar para o movimento**. **Uso e efeito:** Gira o objeto em Y para a direção do movimento (Personagem e própria pose). **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. ### Corpo | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Raio**](#field-radius)
`radius` | número · m | 0.5 | 0.05 … 50 | | [**Altura**](#field-height)
`height` | número · m | 2 | 0.05 … 100 | | [**Deslocamento da base**](#field-base-offset)
`base_offset` | número · m | 0 | -100 … 100 | | [**Desvio de agentes**](#field-avoidance)
`avoidance` | enumeração | Alto | Nenhum \| Baixo \| Médio \| Bom \| Alto |

Raio · radius

**Onde:** Inspector → **Agente de navegação** → **Corpo** → **Raio**. **Uso e efeito:** Raio usado no desvio entre agentes, em metros. Não altera a malha assada; use o raio da Superfície para isso. **Valor:** 0.5 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.05 … 50.

Altura · height

**Onde:** Inspector → **Agente de navegação** → **Corpo** → **Altura**. **Uso e efeito:** Altura do agente para o desvio, em metros. **Valor:** 2 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.05 … 100.

Deslocamento da base · base_offset

**Onde:** Inspector → **Agente de navegação** → **Corpo** → **Deslocamento da base**. **Uso e efeito:** Altura do pivô acima da malha, em metros, quando o agente move a própria pose. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -100 … 100.

Desvio de agentes · avoidance

**Onde:** Inspector → **Agente de navegação** → **Corpo** → **Desvio de agentes**. **Uso e efeito:** Qualidade do desvio entre agentes: Nenhum desliga; Alto amostra mais velocidades e custa mais. **Valor:** Alto · **Tipo:** enumeração · **Domínio:** Nenhum \| Baixo \| Médio \| Bom \| Alto. ### Áreas | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Custo do salto**](#field-jump-cost)
`jump_cost` | número · × | 1 | 1 … 1000 | | [**Custo da área difícil**](#field-difficult-cost)
`difficult_cost` | número · × | 4 | 1 … 1000 | | [**Usar links e áreas de salto**](#field-use-jump)
`use_jump` | booleano | verdadeiro | verdadeiro \| falso | | [**Atravessar área difícil**](#field-use-difficult)
`use_difficult` | booleano | verdadeiro | verdadeiro \| falso |

Custo do salto · jump_cost

**Onde:** Inspector → **Agente de navegação** → **Áreas** → **Custo do salto**. **Uso e efeito:** Multiplicador do custo de links e áreas de Salto. Maior faz o caminho evitar saltos quando há alternativa. **Valor:** 1 · **Tipo:** número · **Unidade:** × · **Domínio:** 1 … 1000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Custo da área difícil · difficult_cost

**Onde:** Inspector → **Agente de navegação** → **Áreas** → **Custo da área difícil**. **Uso e efeito:** Multiplicador do custo da área Difícil. Com 1 atravessa; valores altos contornam. **Valor:** 4 · **Tipo:** número · **Unidade:** × · **Domínio:** 1 … 1000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Usar links e áreas de salto · use_jump

**Onde:** Inspector → **Agente de navegação** → **Áreas** → **Usar links e áreas de salto**. **Uso e efeito:** Permite usar links e áreas de Salto no caminho. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Atravessar área difícil · use_difficult

**Onde:** Inspector → **Agente de navegação** → **Áreas** → **Atravessar área difícil**. **Uso e efeito:** Permite atravessar a área Difícil, com o custo configurado. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. ### Geral | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Ativo**](#field-enabled)
`enabled` | booleano | verdadeiro | verdadeiro \| falso | | [**Superfície**](#field-surface)
`surface` | referência | Mais próxima | astra.navigation.surface | | [**Seguir objeto**](#field-target)
`target` | referência | Nenhum | qualquer objeto · outro objeto |

Ativo · enabled

**Onde:** Inspector → **Agente de navegação** → **Geral** → **Ativo**. **Uso e efeito:** Desligado sai da multidão e para de mover o objeto; o destino guardado continua no Play. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Superfície · surface

**Onde:** Inspector → **Agente de navegação** → **Geral** → **Superfície**. **Uso e efeito:** Superfície cuja malha o agente usa; vazio escolhe a que contém o objeto no início do Play. **Valor:** Mais próxima · **Tipo:** referência · **Domínio:** astra.navigation.surface.

Seguir objeto · target

**Onde:** Inspector → **Agente de navegação** → **Geral** → **Seguir objeto**. **Uso e efeito:** Objeto perseguido sem script. SetDestination substitui o alvo até Resume. **Valor:** Nenhum · **Tipo:** referência · **Domínio:** qualquer objeto · outro objeto. ## Roadmap deste componente [Câmera e navegação](/pt-br/snapshot-2026-10-06/roadmap/camera-e-navegacao/). Presente na 0.3.0. Prioridade de desvio, tipos de agente e animação de travessia de link personalizada não estão implementados. Sem data prometida. Os campos acima pertencem ao contrato existente; novas funções dependem do fechamento da família. Não há datas individuais prometidas para cada propriedade. ## Conferir na sua cena 1. Crie **Agente de navegação** pelo fluxo indicado e resolva as dependências. 2. Altere uma propriedade por vez e observe o efeito esperado na cena. 3. Salve, reabra e confira os valores autorais. 4. Entre em Play e verifique o comportamento com os recursos reais do projeto. 5. Pare o Play e confira a cena autoral. Este é um roteiro de conferência; não representa um teste executado nesta publicação. ## Limitações da referência A tabela cobre os tipos de propriedade disponíveis no descritor de reflexão. Não presume persistência de campos transitórios, equivalência com outras engines ou suporte em todos os aparelhos. Recursos, coleções e operações podem exigir APIs específicas. **Referência de arquitetura registrada pela engine:** [documentação oficial](https://docs.unity3d.com/6000.0/Documentation/Manual/class-NavMeshAgent.html). Essa referência não representa paridade funcional. ## Comandos e leituras em Play Os IDs abaixo são operações nativas do componente existente. Não são novos botões de autoria. Use a fachada C# correspondente para nomes e assinaturas; Conexão de evento oferece as ações compatíveis no seletor. Confira o componente e o mundo vivos antes de chamar. | Operação / ID | Uso e efeito | Argumentos | Retorno | |---|---|---|---| | **Ir para** · `set_destination` | Calcula o caminho e começa a andar; falso quando o ponto está longe da malha | Ponto: vetor (m) | booleano | | **Parar** · `stop` | Para no lugar e guarda o destino para Retomar | Nenhum | nada | | **Retomar** · `resume` | Volta ao último destino depois de Parar | Nenhum | nada | | **Teleportar** · `warp` | Move o objeto e o agente para o ponto mais próximo da malha | Ponto: vetor (m) | booleano | | **Distância restante** · `remaining_distance` | Comprimento do caminho até o destino; infinito sem caminho | Nenhum | número | | **Estado do caminho** · `path_status` | 0 sem caminho, 1 completo, 2 parcial, 3 inválido | Nenhum | inteiro | | **Tem caminho** · `has_path` | Verdadeiro enquanto há um destino válido | Nenhum | booleano | | **Em link** · `is_on_link` | Verdadeiro durante a travessia de um Link | Nenhum | booleano | | **Velocidade** · `velocity` | Velocidade pedida pela multidão neste quadro | Nenhum | vetor | [Assinaturas da fachada NavAgent](/pt-br/snapshot-2026-10-09/api/astra-components-navagent/#membros) ## Eventos do componente No Behavior, a fachada permite inscrever um receptor usando o owner vivo; a inscrição pertence ao lifecycle daquela execução. Uma Conexão de evento precisa de emissor, evento, receptor e ação: adicionar a conexão não define a regra do jogo. | Evento / ID | Quando ocorre | Dados enviados | |---|---|---| | **Chegou** · `destination_reached` | Emitido uma vez quando o caminho restante fica abaixo da distância de parada | Nenhum | | **Caminho falhou** · `path_failed` | Emitido quando o destino não tem caminho | Nenhum | | **Entrou no link** · `link_entered` | Emitido quando o agente começa a atravessar um Link | Nenhum |