--- title: "Braço de mola" 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-spring-arm/ --- # Braço de mola Afasta os filhos até a primeira colisão, como câmera em terceira pessoa **Família:** Física 3D · **Grupo:** Consultas · **Identificador:** `astra.physics.spring_arm` · **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 Retrata filhos ao longo de um braço quando há obstáculos. Use para sustentar uma câmera filha sem atravessar uma parede física. Crie o braço em um objeto e coloque a câmera como filha. Comprimento segue +Z local; a orientação do braço decide o lado. Use margem para manter distância da superfície e raio maior que zero para varredura esférica. ## Criar e configurar Hierarquia → selecione o objeto → Inspector → Adicionar componente → **Física 3D** / **Consultas** → **Braço de mola**. O schema permite uma única instância desse tipo por objeto. A fachada C# correspondente é [Astra.Components.SpringArm](/pt-br/snapshot-2026-10-07/api/astra-components-springarm/). Raio zero usa consulta por linha. Não controla automaticamente lente, mira ou prioridade de câmera. A câmera virtual com Evitar obstáculos é outro fluxo: não empilhe ambos sem resolver quem escreve a pose. **Guia relacionado:** [Montagem de câmera filha](/pt-br/snapshot-2026-10-06/versoes/preview-2026-10-07/#raio-varredura-de-forma-e-braço-de-mola) ## Exemplo de uso Use comprimento 4 m, margem .1 m e raio .2 m. Aproxime o braço de uma parede com collider em Play e confira a distância efetiva dos filhos. Se outro controlador escreve a pose da câmera, retire esse conflito antes de interpretar o resultado. ## 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. ### Braço | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Comprimento**](#field-length)
`length` | número · m | 3 | 0.001 … 1000 | | [**Margem**](#field-margin)
`margin` | número · m | 0.1 | 0 … 10 | | [**Raio da esfera**](#field-radius)
`radius` | número · m | 0 | 0 … 100 |

Comprimento · length

**Onde:** Inspector → **Braço de mola** → **Braço** → **Comprimento**. **Uso e efeito:** Comprimento desejado em metros no eixo +Z local. Obstáculos reduzem a distância efetiva dos filhos. **Valor:** 3 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 1000.

Margem · margin

**Onde:** Inspector → **Braço de mola** → **Braço** → **Margem**. **Uso e efeito:** Margem em metros descontada no acerto, para conservar afastamento do obstáculo. **Valor:** 0.1 · **Tipo:** número · **Unidade:** m · **Domínio:** 0 … 10.

Raio da esfera · radius

**Onde:** Inspector → **Braço de mola** → **Braço** → **Raio da esfera**. **Uso e efeito:** Raio em metros do volume varrido. Zero usa linha; maior considera um volume esférico e ajuda em quinas. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** 0 … 100. ### Consulta | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Ativo**](#field-enabled)
`enabled` | booleano | verdadeiro | verdadeiro \| falso |

Ativo · enabled

**Onde:** Inspector → **Braço de mola** → **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 → **Braço de mola** → **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 → **Braço de mola** → **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 → **Braço de mola** → **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 → **Braço de mola** → **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 → **Braço de mola** → **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/). Retração física do braço presente na prévia. Desoclusão universal, composição e estabilidade em qualquer cena não são declaradas. Sem data de 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 **Braço de mola** 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_springarm3d.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 | |---|---|---|---| | **Comprimento atual** · `hit_length` | Distância livre do último quadro, já descontada a margem | Nenhum | número | [Assinaturas da fachada SpringArm](/pt-br/snapshot-2026-10-07/api/astra-components-springarm/#membros)