--- title: "Sonda de reflexo" version: snapshot-2026-10-28 engineGeneration: astra-current language: C# status: source-reviewed reviewedAt: 2026-10-28 appRelease: "0.4.0-preview.20261028" runtimeVerified: false platformEvidence: [] url: https://astraengine.com.br/pt-br/snapshot-2026-10-28/componentes/astra-render-reflection-probe/ --- # Sonda de reflexo Captura a cena num cubemap: metal e vidro refletem o cômodo em vez do céu **Família:** Luz · **Grupo:** Sondas · **Identificador:** `astra.render.reflection_probe` · **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 Captura o cômodo num cubemap para metal e vidro refletirem a sala certa em vez do céu. Assada (uma vez, só objetos Static) ou em tempo real. Crie por + › Luzes › Sonda de reflexo. Ajuste Tamanho e Deslocamento da caixa pelas alças até as paredes, ligue Projeção na caixa num interior e toque Assar: o cubemap vai para Iluminação/.aeprobe. Em Tempo real, escolha Atualização (Ao acordar, Todo quadro ou Por script) e o Fatiamento no tempo. ## Vindo de outra engine Na Unity, o conceito mais próximo está em [ReflectionProbe](https://docs.unity3d.com/6000.0/Documentation/Manual/class-ReflectionProbe.html). A Astra estudou essa referência; os campos e o comportamento são os desta página, sem paridade garantida. Palavras que a busca de Adicionar componente aceita: `Reflection`, `Probe`, `ReflectionProbe`, `Cubemap`, `Box`, `Projection`, `Reflexo`, `Sonda`. ## Criar e configurar Hierarquia → selecione o objeto → Inspector → Adicionar componente → **Luz** / **Sondas** → **Sonda de reflexo**. O schema permite uma única instância desse tipo por objeto. A fachada C# correspondente é [Astra.Components.ReflectionProbe](/pt-br/snapshot-2026-10-28/api/astra-components-reflectionprobe/). Cada objeto mistura as duas sondas de maior Importância que contêm o centro dele (empate: a menor caixa) e cai no reflexo do céu fora delas. Fundo, Máscara de culling e Planos próximo/distante valem para a captura. Por script, RenderProbe() recaptura; o fim da recaptura ainda não é notificado. Custo no POCO F7 com 111 desenhos refletindo: cerca de +0,6 ms de GPU. **Guia relacionado:** [Sondas](/pt-br/snapshot-2026-10-06/versoes/preview-0-4-0/#sondas-e-luz-assada) ## Exemplo de uso Numa sala de 10×4×10 m com um piso metálico, ponha a sonda no centro, caixa 10/4/10, Projeção na caixa ligada, Resolução 128 e Asse. A esfera de metal reflete as paredes alinhadas. Uma segunda sonda no corredor com Distância de mistura 1 faz a transição entre as duas. ## 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 | |---|---|---|---| | **Cubemap assado** · `baked_texture` | Inspector → Sonda de reflexo → Captura | reflection_probe | Escrito pelo Assar; Tempo real não usa | ### Tempo de execução | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Importância**](#field-importance)
`importance` | número | 1 | 0 … 32767 | | [**Intensidade**](#field-intensity)
`intensity` | número | 1 | 0 … 10 | | [**Distância de mistura**](#field-blend-distance)
`blend_distance` | número · m | 1 | 0 … 100 | | [**Tamanho X**](#field-box-size-x)
`box_size.x` | número · m | 10 | 0.01 … 10000 | | [**Tamanho Y**](#field-box-size-y)
`box_size.y` | número · m | 10 | 0.01 … 10000 | | [**Tamanho Z**](#field-box-size-z)
`box_size.z` | número · m | 10 | 0.01 … 10000 | | [**Deslocamento X**](#field-box-offset-x)
`box_offset.x` | número · m | 0 | -10000 … 10000 | | [**Deslocamento Y**](#field-box-offset-y)
`box_offset.y` | número · m | 0 | -10000 … 10000 | | [**Deslocamento Z**](#field-box-offset-z)
`box_offset.z` | número · m | 0 | -10000 … 10000 | | [**Ativa**](#field-enabled)
`enabled` | booleano | verdadeiro | verdadeiro \| falso | | [**Projeção na caixa**](#field-box-projection)
`box_projection` | booleano | falso | verdadeiro \| falso |

Importância · importance

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Importância**. **Uso e efeito:** Entre sondas sobrepostas, o objeto mistura as duas de maior importância **Valor:** 1 · **Tipo:** número · **Domínio:** 0 … 32767. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Intensidade · intensity

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Intensidade**. **Uso e efeito:** Multiplica o reflexo desta sonda nos materiais **Valor:** 1 · **Tipo:** número · **Domínio:** 0 … 10. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Distância de mistura · blend_distance

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Distância de mistura**. **Uso e efeito:** Faixa dentro da caixa em que o reflexo passa desta sonda para a vizinha ou para o céu **Valor:** 1 · **Tipo:** número · **Unidade:** m · **Domínio:** 0 … 100. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Tamanho X · box_size.x

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Tamanho X**. **Uso e efeito:** Tamanho da caixa de influência no eixo X, em metros. Com Projeção na caixa, deve coincidir com as paredes. **Valor:** 10 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.01 … 10000. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Tamanho Y · box_size.y

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Tamanho Y**. **Uso e efeito:** Tamanho da caixa de influência no eixo Y, em metros. Com Projeção na caixa, deve coincidir com as paredes. **Valor:** 10 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.01 … 10000. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Tamanho Z · box_size.z

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Tamanho Z**. **Uso e efeito:** Tamanho da caixa de influência no eixo Z, em metros. Com Projeção na caixa, deve coincidir com as paredes. **Valor:** 10 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.01 … 10000. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Deslocamento X · box_offset.x

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Deslocamento X**. **Uso e efeito:** Deslocamento da caixa em relação ao objeto no eixo X; a captura continua na posição do objeto. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Deslocamento Y · box_offset.y

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Deslocamento Y**. **Uso e efeito:** Deslocamento da caixa em relação ao objeto no eixo Y; a captura continua na posição do objeto. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Deslocamento Z · box_offset.z

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Deslocamento Z**. **Uso e efeito:** Deslocamento da caixa em relação ao objeto no eixo Z; a captura continua na posição do objeto. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Ativa · enabled

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Ativa**. **Uso e efeito:** Desligado, o componente para de agir e conserva os dados. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Projeção na caixa · box_projection

**Onde:** Inspector → **Sonda de reflexo** → **Tempo de execução** → **Projeção na caixa**. **Uso e efeito:** Paredes a distância finita: o reflexo muda com a posição na sala, em vez de ficar no infinito **Valor:** falso · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/). ### Captura | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Fundo R**](#field-background-r)
`background.r` | número | 0.192 | 0 … 1 | | [**Fundo G**](#field-background-g)
`background.g` | número | 0.302 | 0 … 1 | | [**Fundo B**](#field-background-b)
`background.b` | número | 0.475 | 0 … 1 | | [**Plano próximo**](#field-near-clip)
`near_clip` | número · m | 0.3 | 0.01 … 1000 | | [**Plano distante**](#field-far-clip)
`far_clip` | número · m | 1000 | 0.1 … 100000 | | [**HDR**](#field-hdr)
`hdr` | booleano | verdadeiro | verdadeiro \| falso | | [**Resolução**](#field-resolution)
`resolution` | enumeração · px | 128 | 16 \| 32 \| 64 \| 128 \| 256 | | [**Fundo**](#field-clear-flags)
`clear_flags` | enumeração | Céu | Céu \| Cor sólida | | [**Máscara de culling**](#field-culling-mask)
`culling_mask` | enumeração | Tudo | máscara: Padrão + 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 |

Fundo R · background.r

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **Fundo R**. **Uso e efeito:** Canal vermelho da cor de fundo da captura quando Fundo = Cor sólida. **Valor:** 0.192 · **Tipo:** número · **Domínio:** 0 … 1. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Fundo G · background.g

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **Fundo G**. **Uso e efeito:** Canal verde da cor de fundo da captura quando Fundo = Cor sólida. **Valor:** 0.302 · **Tipo:** número · **Domínio:** 0 … 1. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Fundo B · background.b

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **Fundo B**. **Uso e efeito:** Canal azul da cor de fundo da captura quando Fundo = Cor sólida. **Valor:** 0.475 · **Tipo:** número · **Domínio:** 0 … 1. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Plano próximo · near_clip

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **Plano próximo**. **Uso e efeito:** Nada mais perto da sonda que isto entra no reflexo **Valor:** 0.3 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.01 … 1000. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Plano distante · far_clip

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **Plano distante**. **Uso e efeito:** Nada mais longe que isto entra no reflexo; além dele aparece o fundo **Valor:** 1000 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.1 … 100000. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

HDR · hdr

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **HDR**. **Uso e efeito:** Guarda brilho acima de 1 (sol, lâmpadas); desligado, a captura é cortada em 0..1 e o recurso ocupa metade **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Resolução · resolution

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **Resolução**. **Uso e efeito:** Lado de cada face capturada; mais nitidez em metal liso, mais custo de captura **Valor:** 128 · **Tipo:** enumeração · **Unidade:** px · **Domínio:** 16 \| 32 \| 64 \| 128 \| 256. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Fundo · clear_flags

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **Fundo**. **Uso e efeito:** O que aparece onde não há objeto: o céu da cena ou uma cor **Valor:** Céu · **Tipo:** enumeração · **Domínio:** Céu \| Cor sólida. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Máscara de culling · culling_mask

**Onde:** Inspector → **Sonda de reflexo** → **Captura** → **Máscara de culling**. **Uso e efeito:** Só objetos destas camadas entram no reflexo **Valor:** Tudo · **Tipo:** enumeração · **Domínio:** máscara: Padrão + 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. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/). ### Geral | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Tipo**](#field-type)
`type` | enumeração | Assada | Assada \| Tempo real |

Tipo · type

**Onde:** Inspector → **Sonda de reflexo** → **Geral** → **Tipo**. **Uso e efeito:** Assada é capturada no editor e guardada no projeto; Tempo real recaptura no aparelho **Valor:** Assada · **Tipo:** enumeração · **Domínio:** Assada \| Tempo real. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/). ### Tempo real | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Atualização**](#field-refresh-mode)
`refresh_mode` | enumeração | Ao acordar | Ao acordar \| Todo quadro \| Por script | | [**Fatiamento no tempo**](#field-time-slicing)
`time_slicing` | enumeração | Todas as faces de uma vez | Todas as faces de uma vez \| Uma face por quadro \| Sem fatiamento |

Atualização · refresh_mode

**Onde:** Inspector → **Sonda de reflexo** → **Tempo real** → **Atualização**. **Uso e efeito:** Ao acordar captura uma vez no início do Play; Todo quadro recaptura sem parar; Por script espera RenderProbe() **Valor:** Ao acordar · **Tipo:** enumeração · **Domínio:** Ao acordar \| Todo quadro \| Por script. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/).

Fatiamento no tempo · time_slicing

**Onde:** Inspector → **Sonda de reflexo** → **Tempo real** → **Fatiamento no tempo**. **Uso e efeito:** Espalha a captura e o filtro por vários quadros para não pesar num quadro só **Valor:** Todas as faces de uma vez · **Tipo:** enumeração · **Domínio:** Todas as faces de uma vez \| Uma face por quadro \| Sem fatiamento. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. 8 sondas por quadro, 256 px por face; sem tipo Custom, Shadow Distance nem oclusão própria da captura Capacidade necessária: `render.probe.reflection`; veja [estado do renderer](/pt-br/snapshot-2026-10-06/roadmap/capacidades-do-renderer/). ## Roadmap deste componente [Renderização e materiais](/pt-br/snapshot-2026-10-06/roadmap/renderizacao-e-materiais/). Presente na 0.4.0. Sonda Custom, Anchor Override e reflexos em espaço de tela não existem. 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 **Sonda de reflexo** 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/6000.0/Documentation/Manual/class-ReflectionProbe.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 | |---|---|---|---| | **Capturar agora** · `render_probe` | Recaptura a sonda de tempo real no próximo quadro (RenderProbe da Unity) | Nenhum | nada | [Assinaturas da fachada ReflectionProbe](/pt-br/snapshot-2026-10-28/api/astra-components-reflectionprobe/#membros)