--- title: "Superfície 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-surface/ --- # Superfície de navegação Assa a malha de navegação dos colisores estáticos e a carrega no Play **Família:** Navegação · **Grupo:** Malha · **Identificador:** `astra.navigation.surface` · **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 Assa a malha de navegação a partir dos colisores estáticos da cena e a carrega no Play. Agentes só andam onde existe malha assada. Crie pela folha Criar → Navegação → Superfície ou adicione a um objeto vazio. Ajuste as medidas do agente (raio, altura, degrau, inclinação) e toque **Assar** na Inspeção. O resultado vira o recurso Navegação/.navmesh do projeto. ## Criar e configurar Hierarquia → selecione o objeto → Inspector → Adicionar componente → **Navegação** / **Malha** → **Superfície de navegação**. O schema permite uma única instância desse tipo por objeto. A fachada C# correspondente é [Astra.Components.NavSurface](/pt-br/snapshot-2026-10-09/api/astra-components-navsurface/). Coleta: toda a cena, só os filhos ou um volume (centro/tamanho no espaço do objeto); a camada física filtra os colisores. Objetos com Agente ou Obstáculo não viram chão. O bake roda em segundo plano com progresso e Cancelar; assar de novo reescreve o mesmo recurso. A atribuição do recurso é um passo de Desfazer. A malha fica onde foi assada: mover o objeto da Superfície não a desloca. **Guia relacionado:** [Guia de navegação](/pt-br/snapshot-2026-10-09/sistemas/navegacao/) · [Notas 0.3.0](/pt-br/snapshot-2026-10-06/versoes/preview-0-3-0/#navegação) ## Exemplo de uso Com um chão estático 20×20 m e uma parede de 12 m, mantenha raio .5, altura 2, degrau .4 e inclinação 45°. Asse: o cartão mostra polígonos, área e tiles, e o viewport desenha a malha com um vão ao redor da parede. Mova a parede e veja o cartão passar a "Desatualizada"; asse de novo. ## Dependências Nenhuma regra adicional declarada no schema deste componente. ## Conflitos Nenhuma regra adicional declarada no schema deste componente. ## 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. ### Recursos do projeto Estes seletores ficam no componente e não entram na contagem dos campos numéricos. Use recursos registrados do projeto; nome ou caminho externo não substitui uma referência válida. | Recurso | Onde | Tipo | Uso | |---|---|---|---| | **Malha assada** · `data` | Inspector → Superfície de navegação → Geral | navmesh | Recurso .navmesh produzido pelo bake; o Play carrega este arquivo | ### Agente | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Raio do agente**](#field-agent-radius)
`agent_radius` | número · m | 0.5 | 0 … 50 | | [**Altura do agente**](#field-agent-height)
`agent_height` | número · m | 2 | 0.05 … 100 | | [**Altura do degrau**](#field-agent-max-climb)
`agent_max_climb` | número · m | 0.4 | 0 … 50 | | [**Inclinação máxima**](#field-agent-max-slope)
`agent_max_slope` | número · ° | 45 | 0 … 89 |

Raio do agente · agent_radius

**Onde:** Inspector → **Superfície de navegação** → **Agente** → **Raio do agente**. **Uso e efeito:** Raio do agente para o bake, em metros: a malha recua essa distância das paredes. Agentes maiores que ele podem raspar; asse de novo ao mudar. **Valor:** 0.5 · **Tipo:** número · **Unidade:** m · **Domínio:** 0 … 50.

Altura do agente · agent_height

**Onde:** Inspector → **Superfície de navegação** → **Agente** → **Altura do agente**. **Uso e efeito:** Espaço livre mínimo acima do chão, em metros. Passagens mais baixas ficam fora da malha. **Valor:** 2 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.05 … 100.

Altura do degrau · agent_max_climb

**Onde:** Inspector → **Superfície de navegação** → **Agente** → **Altura do degrau**. **Uso e efeito:** Desnível que o agente vence sem link, em metros (degrau). Maior junta plataformas próximas; menor exige rampas ou links. **Valor:** 0.4 · **Tipo:** número · **Unidade:** m · **Domínio:** 0 … 50.

Inclinação máxima · agent_max_slope

**Onde:** Inspector → **Superfície de navegação** → **Agente** → **Inclinação máxima**. **Uso e efeito:** Inclinação máxima caminhável, em graus. Rampas mais íngremes não entram na malha. **Valor:** 45 · **Tipo:** número · **Unidade:** ° · **Domínio:** 0 … 89. ### Coleta | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Centro X**](#field-volume-center-x)
`volume_center_x` | número · m | 0 | -100000 … 100000 | | [**Centro Y**](#field-volume-center-y)
`volume_center_y` | número · m | 0 | -100000 … 100000 | | [**Centro Z**](#field-volume-center-z)
`volume_center_z` | número · m | 0 | -100000 … 100000 | | [**Tamanho X**](#field-volume-size-x)
`volume_size_x` | número · m | 20 | 0.1 … 100000 | | [**Tamanho Y**](#field-volume-size-y)
`volume_size_y` | número · m | 6 | 0.1 … 100000 | | [**Tamanho Z**](#field-volume-size-z)
`volume_size_z` | número · m | 20 | 0.1 … 100000 | | [**Coletar**](#field-collect)
`collect` | enumeração | Toda a cena | Toda a cena \| Este objeto e filhos \| Volume | | [**Camada dos colisores**](#field-layer)
`layer` | enumeração | Todas | Todas \| Camada 0 \| Camada 1 \| Camada 2 \| Camada 3 \| Camada 4 \| Camada 5 \| Camada 6 \| Camada 7 \| Camada 8 \| Camada 9 \| Camada 10 \| Camada 11 \| Camada 12 \| Camada 13 \| Camada 14 \| Camada 15 \| Camada 16 \| Camada 17 \| Camada 18 \| Camada 19 \| Camada 20 \| Camada 21 \| Camada 22 \| Camada 23 \| Camada 24 \| Camada 25 \| Camada 26 \| Camada 27 \| Camada 28 \| Camada 29 \| Camada 30 \| Camada 31 |

Centro X · volume_center_x

**Onde:** Inspector → **Superfície de navegação** → **Coleta** → **Centro X**. **Uso e efeito:** Coordenada X do centro do volume de coleta, no espaço do objeto da Superfície. Usada só com Coletar = Volume. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -100000 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Centro Y · volume_center_y

**Onde:** Inspector → **Superfície de navegação** → **Coleta** → **Centro Y**. **Uso e efeito:** Coordenada Y do centro do volume de coleta, no espaço do objeto. Usada só com Coletar = Volume. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -100000 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Centro Z · volume_center_z

**Onde:** Inspector → **Superfície de navegação** → **Coleta** → **Centro Z**. **Uso e efeito:** Coordenada Z do centro do volume de coleta, no espaço do objeto. Usada só com Coletar = Volume. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -100000 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Tamanho X · volume_size_x

**Onde:** Inspector → **Superfície de navegação** → **Coleta** → **Tamanho X**. **Uso e efeito:** Largura do volume de coleta em metros (eixo X do objeto). Colisores fora dele não entram no bake. **Valor:** 20 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.1 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Tamanho Y · volume_size_y

**Onde:** Inspector → **Superfície de navegação** → **Coleta** → **Tamanho Y**. **Uso e efeito:** Altura do volume de coleta em metros. Inclua o chão e o espaço livre do agente. **Valor:** 6 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.1 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Tamanho Z · volume_size_z

**Onde:** Inspector → **Superfície de navegação** → **Coleta** → **Tamanho Z**. **Uso e efeito:** Profundidade do volume de coleta em metros (eixo Z do objeto). **Valor:** 20 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.1 … 100000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Coletar · collect

**Onde:** Inspector → **Superfície de navegação** → **Coleta** → **Coletar**. **Uso e efeito:** Quais colisores estáticos entram: toda a cena, este objeto e filhos, ou só os que tocam o Volume. **Valor:** Toda a cena · **Tipo:** enumeração · **Domínio:** Toda a cena \| Este objeto e filhos \| Volume.

Camada dos colisores · layer

**Onde:** Inspector → **Superfície de navegação** → **Coleta** → **Camada dos colisores**. **Uso e efeito:** Todas as camadas físicas ou só uma. Colisores de outras camadas não viram chão. **Valor:** Todas · **Tipo:** enumeração · **Domínio:** Todas \| Camada 0 \| Camada 1 \| Camada 2 \| Camada 3 \| Camada 4 \| Camada 5 \| Camada 6 \| Camada 7 \| Camada 8 \| Camada 9 \| Camada 10 \| Camada 11 \| Camada 12 \| Camada 13 \| Camada 14 \| Camada 15 \| Camada 16 \| Camada 17 \| Camada 18 \| Camada 19 \| Camada 20 \| Camada 21 \| Camada 22 \| Camada 23 \| Camada 24 \| Camada 25 \| Camada 26 \| Camada 27 \| Camada 28 \| Camada 29 \| Camada 30 \| Camada 31. ### Precisão | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Tamanho da célula**](#field-cell-size)
`cell_size` | número · m | 0.2 | 0.01 … 10 | | [**Altura da célula**](#field-cell-height)
`cell_height` | número · m | 0.1 | 0.01 … 10 | | [**Área mínima de região**](#field-min-region-area)
`min_region_area` | número · m² | 2 | 0 … 10000 | | [**Tile**](#field-tile-size)
`tile_size` | número · células | 64 | 16 … 128 |

Tamanho da célula · cell_size

**Onde:** Inspector → **Superfície de navegação** → **Precisão** → **Tamanho da célula**. **Uso e efeito:** Tamanho horizontal da célula de voxel, em metros. Menor aumenta precisão e tempo de bake; maior pode fechar vãos estreitos. **Valor:** 0.2 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.01 … 10.

Altura da célula · cell_height

**Onde:** Inspector → **Superfície de navegação** → **Precisão** → **Altura da célula**. **Uso e efeito:** Altura da célula de voxel, em metros. Define a precisão vertical dos degraus. **Valor:** 0.1 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.01 … 10.

Área mínima de região · min_region_area

**Onde:** Inspector → **Superfície de navegação** → **Precisão** → **Área mínima de região**. **Uso e efeito:** Área mínima, em m², de uma ilha de malha. Ilhas menores (topos de caixas, quinas) são descartadas. **Valor:** 2 · **Tipo:** número · **Unidade:** m² · **Domínio:** 0 … 10000.

Tile · tile_size

**Onde:** Inspector → **Superfície de navegação** → **Precisão** → **Tile**. **Uso e efeito:** Lado do tile em células. Obstáculos e links reconstroem só os tiles que tocam; tiles menores reconstroem menos por vez. **Valor:** 64 · **Tipo:** número · **Unidade:** células · **Domínio:** 16 … 128. ### Avançado | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Aresta máxima**](#field-edge-max-length)
`edge_max_length` | número · m | 12 | 0 … 1000 | | [**Erro de borda**](#field-edge-max-error)
`edge_max_error` | número · células | 1.3 | 0.1 … 10 | | [**Amostra de detalhe**](#field-detail-sample-distance)
`detail_sample_distance` | número · células | 6 | 0 … 100 | | [**Erro de detalhe**](#field-detail-sample-max-error)
`detail_sample_max_error` | número · células | 1 | 0 … 100 |

Aresta máxima · edge_max_length

**Onde:** Inspector → **Superfície de navegação** → **Avançado** → **Aresta máxima**. **Uso e efeito:** Comprimento máximo das bordas da malha, em metros; zero não limita. **Valor:** 12 · **Tipo:** número · **Unidade:** m · **Domínio:** 0 … 1000.

Erro de borda · edge_max_error

**Onde:** Inspector → **Superfície de navegação** → **Avançado** → **Erro de borda**. **Uso e efeito:** Quanto o contorno simplificado pode se afastar das paredes, em células. Maior gera menos vértices. **Valor:** 1.3 · **Tipo:** número · **Unidade:** células · **Domínio:** 0.1 … 10.

Amostra de detalhe · detail_sample_distance

**Onde:** Inspector → **Superfície de navegação** → **Avançado** → **Amostra de detalhe**. **Uso e efeito:** Distância de amostragem da malha de detalhe de altura, em células. Abaixo de 1 desliga o detalhe. **Valor:** 6 · **Tipo:** número · **Unidade:** células · **Domínio:** 0 … 100.

Erro de detalhe · detail_sample_max_error

**Onde:** Inspector → **Superfície de navegação** → **Avançado** → **Erro de detalhe**. **Uso e efeito:** Erro máximo de altura da malha de detalhe, em células. **Valor:** 1 · **Tipo:** número · **Unidade:** células · **Domínio:** 0 … 100. ### Geral | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Ativa**](#field-enabled)
`enabled` | booleano | verdadeiro | verdadeiro \| falso |

Ativa · enabled

**Onde:** Inspector → **Superfície de navegação** → **Geral** → **Ativa**. **Uso e efeito:** Desligada não carrega a malha no Play; o recurso assado é preservado. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. ## Roadmap deste componente [Câmera e navegação](/pt-br/snapshot-2026-10-06/roadmap/camera-e-navegacao/). Presente na 0.3.0. Áreas nomeadas por projeto, volume modificador e superfície que acompanha o objeto 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 **Superfície 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/Packages/com.unity.ai.navigation@2.0/manual/NavMeshSurface.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 | |---|---|---|---| | **Pronta** · `is_ready` | Verdadeiro quando a malha desta superfície está carregada no Play | Nenhum | booleano | | **Polígonos** · `polygon_count` | Polígonos da malha carregada, com recortes de obstáculos | Nenhum | inteiro | [Assinaturas da fachada NavSurface](/pt-br/snapshot-2026-10-09/api/astra-components-navsurface/#membros)