Raio

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

Consulta o primeiro obstáculo sólido ao longo de um segmento. Use para apontar, detectar chão ou medir uma distância física.

Alvo X/Y/Z é o vetor local completo: direção e comprimento. A rotação do objeto muda a direção em mundo. O chão precisa participar da física; uma malha apenas visual não é detectada.

Criar e configurar

Hierarquia → selecione o objeto → Inspector → Adicionar componente → Física 3D / Consultas → Raio.

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.RayCast.

Atualiza após a física em Play. A API especializada e a Conexão de evento permitem pedir atualização imediata quando há avaliador válido. Não representa contato ou força e não retorna todos os obstáculos do caminho.

Guia relacionado: Consultas e montagem

Exemplo de uso

Coloque a consulta 2 m acima de um chão com corpo/colisor. Com eixos locais alinhados ao mundo, use Alvo 0 / −3 / 0. Em Play, confira o cartão de acerto. Se não houver resultado, verifique comprimento, camada, tipo de corpo e sensores antes de alterar a geometria.

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.

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 → Raio → 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 → Raio → 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 → Raio → 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 → Raio → 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 → Raio → 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 → Raio → 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 → Raio → 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 → Raio → 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 → Raio → 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. Primeiro acerto e filtros presentes na prévia. Consultas com vários resultados exigem a API correspondente; não deduza uma coleção pelo componente. Sem expansão datada.

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 Raio 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 RayCast