--- title: "Varredura de forma" version: snapshot-2026-10-07 engineGeneration: astra-current language: C# status: source-reviewed reviewedAt: 2026-10-07 appRelease: "0.2.3-preview.20261007" runtimeVerified: false platformEvidence: [] url: https://astraengine.com.br/pt-br/snapshot-2026-10-07/componentes/astra-physics-shapecast/ --- # Varredura de forma Varre uma forma até o alvo e guarda o primeiro acerto **Família:** Física 3D · **Grupo:** Consultas · **Identificador:** `astra.physics.shapecast` · **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 Varre uma esfera, cápsula, caixa ou cilindro até o primeiro obstáculo. Use quando uma linha é estreita demais para representar o volume que precisa passar. Escolha Forma, preencha suas dimensões e o vetor local Alvo. Dimensões não são a distância percorrida. Resolva filtros como no Raio; mude a forma para revelar os campos condicionais. ## Criar e configurar Hierarquia → selecione o objeto → Inspector → Adicionar componente → **Física 3D** / **Consultas** → **Varredura de forma**. O schema permite múltiplas instâncias no mesmo objeto; identifique a instância antes de editar ou remover. A fachada C# correspondente é [Astra.Components.ShapeCast](/pt-br/snapshot-2026-10-07/api/astra-components-shapecast/). O resultado é de varredura, não uma lista de overlaps nem um corpo dinâmico. A consulta atualiza após a física. Sem avaliador físico válido, não há resultado fictício fora do Play. **Guia relacionado:** [Raio e varredura](/pt-br/snapshot-2026-10-06/versoes/preview-2026-10-07/#raio-varredura-de-forma-e-braço-de-mola) ## Exemplo de uso Compare uma esfera de raio .25 m com um raio ao atravessar uma quina; use o mesmo vetor local 0 / 0 / 3 m. Para uma caixa de largura 1 m, Meia extensão X é .5 m. Observe o primeiro acerto em Play com colliders reais. ## 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 | Sim | | 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. ### Forma | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Raio**](#field-radius)
`radius` | número · m | 0.5 | 0.001 … 1000 | | [**Meia altura**](#field-half-height)
`half_height` | número · m | 0.5 | 0.001 … 1000 | | [**Meia extensão X**](#field-half-x)
`half_x` | número · m | 0.5 | 0.001 … 1000 | | [**Meia extensão Y**](#field-half-y)
`half_y` | número · m | 0.5 | 0.001 … 1000 | | [**Meia extensão Z**](#field-half-z)
`half_z` | número · m | 0.5 | 0.001 … 1000 | | [**Forma**](#field-shape)
`shape` | enumeração | Esfera | Esfera \| Caixa \| Cápsula \| Cilindro |

Raio · radius

**Onde:** Inspector → **Varredura de forma** → **Forma** → **Raio**. **Uso e efeito:** Raio em metros da esfera/cápsula, visível conforme Forma. Não é comprimento do segmento. **Valor:** 0.5 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 1000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Meia altura · half_height

**Onde:** Inspector → **Varredura de forma** → **Forma** → **Meia altura**. **Uso e efeito:** Meia altura do volume em metros, para cápsula/cilindro conforme Forma. Não é a altura inteira de um modelo. **Valor:** 0.5 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 1000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Meia extensão X · half_x

**Onde:** Inspector → **Varredura de forma** → **Forma** → **Meia extensão X**. **Uso e efeito:** Meia extensão da caixa neste eixo, em metros. Uma extensão .5 representa tamanho total 1 nesse eixo. **Valor:** 0.5 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 1000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Meia extensão Y · half_y

**Onde:** Inspector → **Varredura de forma** → **Forma** → **Meia extensão Y**. **Uso e efeito:** Meia extensão da caixa neste eixo, em metros. Uma extensão .5 representa tamanho total 1 nesse eixo. **Valor:** 0.5 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 1000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Meia extensão Z · half_z

**Onde:** Inspector → **Varredura de forma** → **Forma** → **Meia extensão Z**. **Uso e efeito:** Meia extensão da caixa neste eixo, em metros. Uma extensão .5 representa tamanho total 1 nesse eixo. **Valor:** 0.5 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 1000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Forma · shape

**Onde:** Inspector → **Varredura de forma** → **Forma** → **Forma**. **Uso e efeito:** Escolhe Esfera, Caixa, Cápsula ou Cilindro para a varredura. Configure somente as dimensões relevantes da forma; isso não cria um collider persistente. **Valor:** Esfera · **Tipo:** enumeração · **Domínio:** Esfera \| Caixa \| Cápsula \| Cilindro. ### Consulta | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Alvo X**](#field-target-x)
`target_x` | número · m | 0 | -10000 … 10000 | | [**Alvo Y**](#field-target-y)
`target_y` | número · m | -1 | -10000 … 10000 | | [**Alvo Z**](#field-target-z)
`target_z` | número · m | 0 | -10000 … 10000 | | [**Ativo**](#field-enabled)
`enabled` | booleano | verdadeiro | verdadeiro \| falso |

Alvo X · target_x

**Onde:** Inspector → **Varredura de forma** → **Consulta** → **Alvo X**. **Uso e efeito:** Componente do vetor local do segmento em metros. Seu módulo define alcance; girar o objeto gira a direção em mundo. Não é uma posição absoluta do alvo. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000.

Alvo Y · target_y

**Onde:** Inspector → **Varredura de forma** → **Consulta** → **Alvo Y**. **Uso e efeito:** Componente do vetor local do segmento em metros. Seu módulo define alcance; girar o objeto gira a direção em mundo. Não é uma posição absoluta do alvo. **Valor:** -1 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000.

Alvo Z · target_z

**Onde:** Inspector → **Varredura de forma** → **Consulta** → **Alvo Z**. **Uso e efeito:** Componente do vetor local do segmento em metros. Seu módulo define alcance; girar o objeto gira a direção em mundo. Não é uma posição absoluta do alvo. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000.

Ativo · enabled

**Onde:** Inspector → **Varredura de forma** → **Consulta** → **Ativo**. **Uso e efeito:** Desligado não consulta e mantém o último resultado como vazio **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. ### Filtro | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Ignorar o próprio corpo**](#field-exclude-self)
`exclude_self` | booleano | verdadeiro | verdadeiro \| falso | | [**Incluir sensores**](#field-include-sensors)
`include_sensors` | booleano | falso | verdadeiro \| falso | | [**Incluir estáticos**](#field-include-static)
`include_static` | booleano | verdadeiro | verdadeiro \| falso | | [**Incluir dinâmicos**](#field-include-dynamic)
`include_dynamic` | booleano | verdadeiro | verdadeiro \| falso | | [**Camada**](#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 |

Ignorar o próprio corpo · exclude_self

**Onde:** Inspector → **Varredura de forma** → **Filtro** → **Ignorar o próprio corpo**. **Uso e efeito:** Exclui o primeiro Corpo físico encontrado neste objeto ou subindo por seus ancestrais. Use para não atingir o jogador que sustenta a consulta; sem esse corpo ancestral, não há exclusão automática de todos os colliders do ramo. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Incluir sensores · include_sensors

**Onde:** Inspector → **Varredura de forma** → **Filtro** → **Incluir sensores**. **Uso e efeito:** Inclui formas sensoras no resultado. Desligado evita tratar volumes de trigger como paredes. **Valor:** falso · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Incluir estáticos · include_static

**Onde:** Inspector → **Varredura de forma** → **Filtro** → **Incluir estáticos**. **Uso e efeito:** Inclui corpos estáticos, como chão e paredes. Desligar pode explicar ausência de acerto. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Incluir dinâmicos · include_dynamic

**Onde:** Inspector → **Varredura de forma** → **Filtro** → **Incluir dinâmicos**. **Uso e efeito:** Inclui corpos dinâmicos no resultado; não aplica força nem impede movimento por conta própria. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Camada · layer

**Onde:** Inspector → **Varredura de forma** → **Filtro** → **Camada**. **Uso e efeito:** Todas aceita camadas do projeto; escolher uma limita a consulta. A camada da malha visual não cria forma física. **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. ## Roadmap deste componente [Física 3D e motores](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). Formas e primeiro acerto presentes na prévia. Não presume toda combinação de formas/filtros de outras engines; conferir o cenário real. Sem data para expansão. 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 **Varredura de forma** 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.godotengine.org/en/4.5/classes/class_shapecast3d.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 | |---|---|---|---| | **Acertando** · `colliding` | Verdadeiro quando a última consulta encontrou algo | Nenhum | booleano | | **Objeto atingido** · `collider` | Dono do corpo atingido; vazio sem acerto | Nenhum | objeto | | **Ponto** · `point` | Ponto do acerto no mundo | Nenhum | vetor | | **Normal** · `normal` | Normal da superfície atingida | Nenhum | vetor | | **Distância** · `distance` | Distância do acerto ao início, em metros | Nenhum | número | | **Atualizar agora** · `update` | Refaz a consulta neste instante (force_raycast_update do Godot) | Nenhum | nada | [Assinaturas da fachada ShapeCast](/pt-br/snapshot-2026-10-07/api/astra-components-shapecast/#membros)