Varredura de forma

Família: Física 3D · Grupo: Consultas · Identificador: astra.physics.shapecast · 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

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.

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

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.

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 radius	número · m	0.5	0.001 … 1000
Meia altura half_height	número · m	0.5	0.001 … 1000
Meia extensão X half_x	número · m	0.5	0.001 … 1000
Meia extensão Y half_y	número · m	0.5	0.001 … 1000
Meia extensão Z half_z	número · m	0.5	0.001 … 1000
Forma 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 target_x	número · m	0	-10000 … 10000
Alvo Y target_y	número · m	-1	-10000 … 10000
Alvo Z target_z	número · m	0	-10000 … 10000
Ativo 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 exclude_self	booleano	verdadeiro	verdadeiro | falso
Incluir sensores include_sensors	booleano	falso	verdadeiro | falso
Incluir estáticos include_static	booleano	verdadeiro	verdadeiro | falso
Incluir dinâmicos include_dynamic	booleano	verdadeiro	verdadeiro | falso
Camada 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. 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. 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