Agente de navegação

Família: Navegação · Grupo: Movimento · Identificador: astra.navigation.agent · Payload: 1

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.

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 · 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<NavAgent>()!.Value; agente.SetDestination(new Vector3(7,0,-7)); e inscreva OnDestinationReached.

Dependências

Nenhuma regra adicional declarada no schema deste componente.

Conflitos

• Path Follow: Agente e Seguir caminho escreveriam a mesma pose
• Obstáculo de navegação: 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.

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 speed	número · m/s	3.5	0 … 1000
Aceleração acceleration	número · m/s²	8	0 … 1000
Giro angular_speed	número · °/s	120	0 … 3600
Distância de parada stopping_distance	número · m	0	0 … 1000
Refazer caminho a repath_distance	número · m	0.5	0.05 … 100
Frear ao chegar auto_braking	booleano	verdadeiro	verdadeiro | falso
Girar para o movimento 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 radius	número · m	0.5	0.05 … 50
Altura height	número · m	2	0.05 … 100
Deslocamento da base base_offset	número · m	0	-100 … 100
Desvio de agentes 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 jump_cost	número · ×	1	1 … 1000
Custo da área difícil difficult_cost	número · ×	4	1 … 1000
Usar links e áreas de salto use_jump	booleano	verdadeiro	verdadeiro | falso
Atravessar área difícil 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 enabled	booleano	verdadeiro	verdadeiro | falso
Superfície surface	referência	Mais próxima	astra.navigation.surface
Seguir objeto 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. 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. 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

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