--- title: "Raio" 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-raycast/ --- # Raio Consulta um raio a cada quadro e guarda o primeiro acerto **Família:** Física 3D · **Grupo:** Consultas · **Identificador:** `astra.physics.raycast` · **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 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](/pt-br/snapshot-2026-10-07/api/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](/pt-br/snapshot-2026-10-06/versoes/preview-2026-10-07/#raio-varredura-de-forma-e-braço-de-mola) ## 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](/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. ### 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 → **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**](#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 → **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](/pt-br/snapshot-2026-10-06/roadmap/fisica-3d/). 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](https://docs.godotengine.org/en/4.5/classes/class_raycast3d.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 RayCast](/pt-br/snapshot-2026-10-07/api/astra-components-raycast/#membros)