Câmera virtual

Família: Câmera · Grupo: Câmera virtual · Identificador: astra.camera.virtual · 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

Define uma candidata de pose e lente para a câmera do jogo. Ela segue ou orbita um alvo; o Cérebro escolhe a candidata ao vivo e aplica o resultado à câmera real.

Crie um objeto separado para a câmera virtual. Escolha Alvo rastreado, Posição = Órbita e Rotação = Olhar para o alvo para terceira pessoa. O objeto da câmera real recebe Câmera + Cérebro; não coloque ambos no objeto do jogador físico.

Criar e configurar

Hierarquia → selecione o objeto → Inspector → Adicionar componente → Câmera / Câmera virtual → Câmera virtual.

O schema permite uma única instância desse tipo por objeto. A fachada C# correspondente é Astra.Components.VirtualCamera.

Atalho de criação: selecione o personagem → + → Básicos → Câmera virtual. O atalho cria uma filha em órbita e adiciona Cérebro à câmera da cena se necessário. A criação genérica pelo Inspector conserva os padrões da tabela (Posição/Rotação fixas e Evitar obstáculos desligado). No Play, o cartão indica Ao vivo ou Em espera. A virtual não cria um segundo viewport.

Guia relacionado: Câmera e Cérebro · Exemplo do laboratório

Exemplo de uso

Use um alvo na altura do tronco, Raio da órbita 5 m e Ângulo vertical 20°. Ligue Evitar obstáculos, raio .25 m e selecione a camada de paredes. Tenha colliders reais. Crie outra virtual com prioridade maior para observar a troca no Cérebro. Os valores são receita, não novos padrões do componente.

Dependências

Nenhuma regra adicional declarada no schema deste componente.

Conflitos

• Corpo físico: A câmera virtual não pode receber pose do corpo físico
• Personagem: A câmera virtual não pode receber pose do personagem

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.

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.

Geral

Propriedade	Tipo / unidade	Padrão	Domínio
Prioridade priority	número	0	-10000 … 10000
Ativa enabled	booleano	verdadeiro	verdadeiro | falso
Alvo rastreado tracking_target	referência	Nenhum	qualquer objeto · fora da subárvore
Alvo de mira look_at_target	referência	O rastreado	qualquer objeto · fora da subárvore

Prioridade · priority

Onde: Inspector → Câmera virtual → Geral → Prioridade.

Uso e efeito: A maior entre as câmeras virtuais ativas fica ao vivo; no empate vence a ativada por último

Valor: 0 · Tipo: número · Domínio: -10000 … 10000.

Ativa · enabled

Onde: Inspector → Câmera virtual → Geral → Ativa.

Uso e efeito: Desligada deixa de concorrer; a configuração é preservada

Valor: verdadeiro · Tipo: booleano · Domínio: verdadeiro | falso.

Alvo rastreado · tracking_target

Onde: Inspector → Câmera virtual → Geral → Alvo rastreado.

Uso e efeito: Objeto que Seguir e Órbita acompanham

Valor: Nenhum · Tipo: referência · Domínio: qualquer objeto · fora da subárvore.

Alvo de mira · look_at_target

Onde: Inspector → Câmera virtual → Geral → Alvo de mira.

Uso e efeito: Ponto que Olhar para o alvo e a desoclusão usam

Valor: O rastreado · Tipo: referência · Domínio: qualquer objeto · fora da subárvore.

Lente

Propriedade	Tipo / unidade	Padrão	Domínio
Campo vertical vertical_fov	número · °	60	1 … 170
Meia altura orthographic_half_height	número · m	5	0.001 … 100000
Próximo near_plane	número · m	0.1	0.001 … 10000
Distante far_plane	número · m	2000	0.01 … 1000000
Inclinação holandesa dutch	número · °	0	-180 … 180

Campo vertical · vertical_fov

Onde: Inspector → Câmera virtual → Lente → Campo vertical.

Uso e efeito: Usado quando a Câmera do Cérebro é perspectiva

Valor: 60 · Tipo: número · Unidade: ° · Domínio: 1 … 170.

Aceita tween numérico via contrato de propriedade.

Meia altura · orthographic_half_height

Onde: Inspector → Câmera virtual → Lente → Meia altura.

Uso e efeito: Usado quando a Câmera do Cérebro é ortográfica

Valor: 5 · Tipo: número · Unidade: m · Domínio: 0.001 … 100000.

Aceita tween numérico via contrato de propriedade.

Próximo · near_plane

Onde: Inspector → Câmera virtual → Lente → Próximo.

Uso e efeito: Plano de corte próximo; valor exageradamente baixo reduz precisão de depth.

Valor: 0.1 · Tipo: número · Unidade: m · Domínio: 0.001 … 10000.

Distante · far_plane

Onde: Inspector → Câmera virtual → Lente → Distante.

Uso e efeito: Plano de corte distante; objetos além ficam cortados.

Valor: 2000 · Tipo: número · Unidade: m · Domínio: 0.01 … 1000000.

Inclinação holandesa · dutch

Onde: Inspector → Câmera virtual → Lente → Inclinação holandesa.

Uso e efeito: Giro em torno da direção de visão

Valor: 0 · Tipo: número · Unidade: ° · Domínio: -180 … 180.

Aceita tween numérico via contrato de propriedade.

Posição

Propriedade	Tipo / unidade	Padrão	Domínio
Deslocamento X offset_x	número · m	0	-1000 … 1000
Deslocamento Y offset_y	número · m	2	-1000 … 1000
Deslocamento Z offset_z	número · m	-5	-1000 … 1000
Raio da órbita orbit_radius	número · m	5	0.01 … 1000
Ângulo horizontal orbit_yaw	número · °	0	-180 … 180
Ângulo vertical orbit_pitch	número · °	20	-89 … 89
Vertical mínimo orbit_pitch_min	número · °	-10	-89 … 89
Vertical máximo orbit_pitch_max	número · °	70	-89 … 89
Sensibilidade horizontal orbit_yaw_sensitivity	número · °	300	0 … 2000
Sensibilidade vertical orbit_pitch_sensitivity	número · °	195	0 … 2000
Amortecimento da posição position_damping	número · s	0.2	0 … 10
Controlar pela entrada de olhar orbit_input	booleano	verdadeiro	verdadeiro | falso
Posição position_mode	enumeração	Fixa (pose autorada)	Fixa (pose autorada) | Seguir | Órbita
Referencial do deslocamento binding	enumeração	Eixos do mundo	Eixos do mundo | Guinada do alvo

Deslocamento X · offset_x

Onde: Inspector → Câmera virtual → Posição → Deslocamento X.

Uso e efeito: Componente do deslocamento em metros para Seguir. Referencial decide eixos de mundo ou guinada do alvo; não substitui o raio da Órbita.

Valor: 0 · Tipo: número · Unidade: m · Domínio: -1000 … 1000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Deslocamento Y · offset_y

Onde: Inspector → Câmera virtual → Posição → Deslocamento Y.

Uso e efeito: Componente do deslocamento em metros para Seguir. Referencial decide eixos de mundo ou guinada do alvo; não substitui o raio da Órbita.

Valor: 2 · Tipo: número · Unidade: m · Domínio: -1000 … 1000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Deslocamento Z · offset_z

Onde: Inspector → Câmera virtual → Posição → Deslocamento Z.

Uso e efeito: Componente do deslocamento em metros para Seguir. Referencial decide eixos de mundo ou guinada do alvo; não substitui o raio da Órbita.

Valor: -5 · Tipo: número · Unidade: m · Domínio: -1000 … 1000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Raio da órbita · orbit_radius

Onde: Inspector → Câmera virtual → Posição → Raio da órbita.

Uso e efeito: Distância ao alvo rastreado

Valor: 5 · Tipo: número · Unidade: m · Domínio: 0.01 … 1000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. Aceita tween numérico via contrato de propriedade.

Ângulo horizontal · orbit_yaw

Onde: Inspector → Câmera virtual → Posição → Ângulo horizontal.

Uso e efeito: Giro em torno do eixo Y do mundo; zero fica atrás do alvo (−Z)

Valor: 0 · Tipo: número · Unidade: ° · Domínio: -180 … 180.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. Aceita tween numérico via contrato de propriedade.

Ângulo vertical · orbit_pitch

Onde: Inspector → Câmera virtual → Posição → Ângulo vertical.

Uso e efeito: Positivo põe a câmera acima do alvo

Valor: 20 · Tipo: número · Unidade: ° · Domínio: -89 … 89.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. Aceita tween numérico via contrato de propriedade.

Vertical mínimo · orbit_pitch_min

Onde: Inspector → Câmera virtual → Posição → Vertical mínimo.

Uso e efeito: Limite em graus do pitch da Órbita. Mantenha mínimo menor ou igual ao máximo; um ângulo extremo pode recortar o personagem.

Valor: -10 · Tipo: número · Unidade: ° · Domínio: -89 … 89.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Vertical máximo · orbit_pitch_max

Onde: Inspector → Câmera virtual → Posição → Vertical máximo.

Uso e efeito: Limite em graus do pitch da Órbita. Mantenha mínimo menor ou igual ao máximo; um ângulo extremo pode recortar o personagem.

Valor: 70 · Tipo: número · Unidade: ° · Domínio: -89 … 89.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Sensibilidade horizontal · orbit_yaw_sensitivity

Onde: Inspector → Câmera virtual → Posição → Sensibilidade horizontal.

Uso e efeito: Graus por largura de tela arrastada

Valor: 300 · Tipo: número · Unidade: ° · Domínio: 0 … 2000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Sensibilidade vertical · orbit_pitch_sensitivity

Onde: Inspector → Câmera virtual → Posição → Sensibilidade vertical.

Uso e efeito: Graus por altura de tela arrastada

Valor: 195 · Tipo: número · Unidade: ° · Domínio: 0 … 2000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Amortecimento da posição · position_damping

Onde: Inspector → Câmera virtual → Posição → Amortecimento da posição.

Uso e efeito: Tempo para alcançar o alvo; zero acompanha sem atraso

Valor: 0.2 · Tipo: número · Unidade: s · Domínio: 0 … 10.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Controlar pela entrada de olhar · orbit_input

Onde: Inspector → Câmera virtual → Posição → Controlar pela entrada de olhar.

Uso e efeito: A ação Olhar do mapa de entrada gira a órbita enquanto esta câmera está ao vivo

Valor: verdadeiro · Tipo: booleano · Domínio: verdadeiro | falso.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Posição · position_mode

Onde: Inspector → Câmera virtual → Posição → Posição.

Uso e efeito: Seguir e Órbita usam o alvo rastreado; sem alvo a câmera fica na pose autorada

Valor: Fixa (pose autorada) · Tipo: enumeração · Domínio: Fixa (pose autorada) | Seguir | Órbita.

Referencial do deslocamento · binding

Onde: Inspector → Câmera virtual → Posição → Referencial do deslocamento.

Uso e efeito: Guinada do alvo gira o deslocamento junto com o alvo (Lock To Target With World Up)

Valor: Eixos do mundo · Tipo: enumeração · Domínio: Eixos do mundo | Guinada do alvo.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Rotação

Propriedade	Tipo / unidade	Padrão	Domínio
Mira X aim_offset_x	número · m	0	-1000 … 1000
Mira Y aim_offset_y	número · m	0	-1000 … 1000
Mira Z aim_offset_z	número · m	0	-1000 … 1000
Amortecimento da rotação rotation_damping	número · s	0	0 … 10
Rotação rotation_mode	enumeração	Fixa (rotação autorada)	Fixa (rotação autorada) | Olhar para o alvo | Rotação do alvo

Mira X · aim_offset_x

Onde: Inspector → Câmera virtual → Rotação → Mira X.

Uso e efeito: Deslocamento de mira em metros aplicado ao ponto do alvo; ajusta enquadramento sem mover o alvo físico.

Valor: 0 · Tipo: número · Unidade: m · Domínio: -1000 … 1000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Mira Y · aim_offset_y

Onde: Inspector → Câmera virtual → Rotação → Mira Y.

Uso e efeito: Deslocamento de mira em metros aplicado ao ponto do alvo; ajusta enquadramento sem mover o alvo físico.

Valor: 0 · Tipo: número · Unidade: m · Domínio: -1000 … 1000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Mira Z · aim_offset_z

Onde: Inspector → Câmera virtual → Rotação → Mira Z.

Uso e efeito: Deslocamento de mira em metros aplicado ao ponto do alvo; ajusta enquadramento sem mover o alvo físico.

Valor: 0 · Tipo: número · Unidade: m · Domínio: -1000 … 1000.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Amortecimento da rotação · rotation_damping

Onde: Inspector → Câmera virtual → Rotação → Amortecimento da rotação.

Uso e efeito: Amortecimento para aproximar a orientação desejada; zero acompanha sem atraso. Não é velocidade angular do corpo.

Valor: 0 · Tipo: número · Unidade: s · Domínio: 0 … 10.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Rotação · rotation_mode

Onde: Inspector → Câmera virtual → Rotação → Rotação.

Uso e efeito: Olhar para o alvo usa o alvo de mira, ou o rastreado quando ele está vazio

Valor: Fixa (rotação autorada) · Tipo: enumeração · Domínio: Fixa (rotação autorada) | Olhar para o alvo | Rotação do alvo.

Colisão

Propriedade	Tipo / unidade	Padrão	Domínio
Raio da câmera camera_radius	número · m	0.2	0 … 10
Distância mínima do alvo minimum_distance	número · m	0.5	0 … 100
Amortecimento ao liberar collision_damping	número · s	0.3	0 … 10
Evitar obstáculos avoid_obstacles	booleano	falso	verdadeiro | falso
Camada dos obstáculos collision_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

Raio da câmera · camera_radius

Onde: Inspector → Câmera virtual → Colisão → Raio da câmera.

Uso e efeito: Distância mantida dos obstáculos; zero usa um raio de luz

Valor: 0.2 · Tipo: número · Unidade: m · Domínio: 0 … 10.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Distância mínima do alvo · minimum_distance

Onde: Inspector → Câmera virtual → Colisão → Distância mínima do alvo.

Uso e efeito: Obstáculos mais perto do alvo que isto são ignorados

Valor: 0.5 · Tipo: número · Unidade: m · Domínio: 0 … 100.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Amortecimento ao liberar · collision_damping

Onde: Inspector → Câmera virtual → Colisão → Amortecimento ao liberar.

Uso e efeito: Tempo para voltar à distância livre; a aproximação é imediata

Valor: 0.3 · Tipo: número · Unidade: s · Domínio: 0 … 10.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Evitar obstáculos · avoid_obstacles

Onde: Inspector → Câmera virtual → Colisão → Evitar obstáculos.

Uso e efeito: Aproxima a câmera do alvo quando um colisor bloqueia a linha de visão

Valor: falso · Tipo: booleano · Domínio: verdadeiro | falso.

Camada dos obstáculos · collision_layer

Onde: Inspector → Câmera virtual → Colisão → Camada dos obstáculos.

Uso e efeito: Todas ou só uma camada física do projeto

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.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Tremor

Propriedade	Tipo / unidade	Padrão	Domínio
Tremor da rotação noise_amplitude	número · °	0	0 … 90
Tremor da posição noise_position_amplitude	número · m	0	0 … 10
Frequência noise_frequency	número · Hz	1	0 … 50

Tremor da rotação · noise_amplitude

Onde: Inspector → Câmera virtual → Tremor → Tremor da rotação.

Uso e efeito: Amplitude do tremor angular em graus. Zero desliga esta contribuição; combine com Frequência sem confundir com entrada de olhar.

Valor: 0 · Tipo: número · Unidade: ° · Domínio: 0 … 90.

Aceita tween numérico via contrato de propriedade.

Tremor da posição · noise_position_amplitude

Onde: Inspector → Câmera virtual → Tremor → Tremor da posição.

Uso e efeito: Amplitude do tremor de posição em metros. Não move o alvo nem garante evitar obstáculos por todo tremor.

Valor: 0 · Tipo: número · Unidade: m · Domínio: 0 … 10.

Aceita tween numérico via contrato de propriedade.

Frequência · noise_frequency

Onde: Inspector → Câmera virtual → Tremor → Frequência.

Uso e efeito: Frequência do tremor. Compare no mesmo enquadramento; só produz contribuição quando a amplitude correspondente é maior que zero.

Valor: 1 · Tipo: número · Unidade: Hz · Domínio: 0 … 50.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade. Aceita tween numérico via contrato de propriedade.

Transição

Propriedade	Tipo / unidade	Padrão	Domínio
Duração da entrada blend_time	número · s	1	0 … 60
Entrada blend_style	enumeração	Padrão do Cérebro	Padrão do Cérebro | Corte | Suave | Linear | Entrada suave | Saída suave | Entrada brusca | Saída brusca

Duração da entrada · blend_time

Onde: Inspector → Câmera virtual → Transição → Duração da entrada.

Uso e efeito: Duração em segundos da entrada desta virtual quando sua curva substitui o padrão do Cérebro.

Valor: 1 · Tipo: número · Unidade: s · Domínio: 0 … 60.

Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Entrada · blend_style

Onde: Inspector → Câmera virtual → Transição → Entrada.

Uso e efeito: Curva usada quando esta câmera entra ao vivo

Valor: Padrão do Cérebro · Tipo: enumeração · Domínio: Padrão do Cérebro | Corte | Suave | Linear | Entrada suave | Saída suave | Entrada brusca | Saída brusca.

Roadmap deste componente

Câmera e navegação. Órbita, seguimento, lente, mistura e desvio físico estão na prévia 0.2.3. Fade de oclusores, enquadramento automático geral e garantia contra spawn penetrado não estão implementados. Sem data prometida.

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 Câmera virtual 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
Priorizar · prioritize	Vence o empate com outras câmeras de mesma prioridade, como se tivesse sido ativada agora	Nenhum	nada
Encaixar · snap	Descarta o amortecimento no próximo quadro (depois de teletransportar o alvo)	Nenhum	nada
Ao vivo · is_live	Verdadeiro quando algum Cérebro está mostrando esta câmera	Nenhum	booleano

Assinaturas da fachada VirtualCamera

Eventos do componente

No Behavior, a fachada permite inscrever um receptor usando o owner vivo; a inscrição pertence ao lifecycle daquela execução. Uma Conexão de evento precisa de emissor, evento, receptor e ação: adicionar a conexão não define a regra do jogo.

Evento / ID	Quando ocorre	Dados enviados
Entrou ao vivo · activated	Emitido quando um Cérebro passa a mostrar esta câmera; carrega a câmera anterior	Outra câmera: objeto
Saiu do ar · deactivated	Emitido quando outra câmera assume o Cérebro; carrega a nova câmera	Outra câmera: objeto