--- title: "Campo de gravidade" version: snapshot-2026-10-06 engineGeneration: astra-current language: C# status: source-reviewed runtimeVerified: false platformEvidence: [] url: https://astraengine.com.br/pt-br/snapshot-2026-10-06/componentes/astra-physics-field-gravity/ --- # Campo de gravidade Gravidade local em volume sobre corpos dinâmicos **Família:** Física 3D · **Grupo:** Campos · **Identificador:** `astra.physics.field.gravity` · **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 Gravidade local em volume sobre corpos dinâmicos Resolva Corpo físico, Colisor e autoridade de pose antes de aplicar forças, motores ou juntas. Corpo dinâmico recebe forças; sensor emite sobreposição. Character e Motor dinâmico têm contratos próprios. ## Criar e configurar Hierarquia → selecione o objeto → Inspector → Adicionar componente → **Física 3D** / **Campos** → **Campo de gravidade**. O schema permite uma única instância desse tipo por objeto. A fachada C# correspondente é [Astra.Components.GravityField](/pt-br/snapshot-2026-10-06/api/astra-components-gravityfield/). ## Exemplo de uso Crie chão estático e um corpo dinâmico com colisor. Compare queda, massa, atrito e restituição. Para sensor, conecte TriggerEnter a um Behavior como no HUD de corações. ## 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. ### Volume | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Meia extensão X**](#field-half-x)
`half_x` | número · m | 3 | 0.001 … 10000 | | [**Meia extensão Y**](#field-half-y)
`half_y` | número · m | 3 | 0.001 … 10000 | | [**Meia extensão Z**](#field-half-z)
`half_z` | número · m | 3 | 0.001 … 10000 | | [**Raio**](#field-radius)
`radius` | número · m | 3 | 0.001 … 10000 | | [**Centro X**](#field-offset-x)
`offset_x` | número · m | 0 | -10000 … 10000 | | [**Centro Y**](#field-offset-y)
`offset_y` | número · m | 0 | -10000 … 10000 | | [**Centro Z**](#field-offset-z)
`offset_z` | número · m | 0 | -10000 … 10000 | | [**Forma**](#field-shape)
`shape` | enumeração | Caixa | Caixa \| Esfera |

Meia extensão X · half_x

**Onde:** Inspector → **Campo de gravidade** → **Volume** → **Meia extensão X**. **Uso e efeito:** Meia dimensão da forma/volume no eixo indicado. Dimensão total é o dobro; aplica-se à forma selecionada. **Valor:** 3 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 10000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Meia extensão Y · half_y

**Onde:** Inspector → **Campo de gravidade** → **Volume** → **Meia extensão Y**. **Uso e efeito:** Meia dimensão da forma/volume no eixo indicado. Dimensão total é o dobro; aplica-se à forma selecionada. **Valor:** 3 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 10000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Meia extensão Z · half_z

**Onde:** Inspector → **Campo de gravidade** → **Volume** → **Meia extensão Z**. **Uso e efeito:** Meia dimensão da forma/volume no eixo indicado. Dimensão total é o dobro; aplica-se à forma selecionada. **Valor:** 3 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 10000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Raio · radius

**Onde:** Inspector → **Campo de gravidade** → **Volume** → **Raio**. **Uso e efeito:** Raio da forma/volume selecionado; confira o tipo e os campos condicionais. **Valor:** 3 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.001 … 10000. Campo condicional: o modo/forma/recurso selecionado controla a disponibilidade.

Centro X · offset_x

**Onde:** Inspector → **Campo de gravidade** → **Volume** → **Centro X**. **Uso e efeito:** Deslocamento do resultado/volume em relação à origem configurada, eixo X. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000.

Centro Y · offset_y

**Onde:** Inspector → **Campo de gravidade** → **Volume** → **Centro Y**. **Uso e efeito:** Deslocamento do resultado/volume em relação à origem configurada, eixo Y. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000.

Centro Z · offset_z

**Onde:** Inspector → **Campo de gravidade** → **Volume** → **Centro Z**. **Uso e efeito:** Deslocamento do resultado/volume em relação à origem configurada, eixo Z. **Valor:** 0 · **Tipo:** número · **Unidade:** m · **Domínio:** -10000 … 10000.

Forma · shape

**Onde:** Inspector → **Campo de gravidade** → **Volume** → **Forma**. **Uso e efeito:** Escala e orientação são as do objeto e de seus pais **Valor:** Caixa · **Tipo:** enumeração · **Domínio:** Caixa \| Esfera. ### Efeito | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Vetor X**](#field-vector-x)
`vector_x` | número · m/s² | 0 | -10000 … 10000 | | [**Vetor Y**](#field-vector-y)
`vector_y` | número · m/s² | -9.81 | -10000 … 10000 | | [**Vetor Z**](#field-vector-z)
`vector_z` | número · m/s² | 0 | -10000 … 10000 | | [**Ativo**](#field-enabled)
`enabled` | booleano | verdadeiro | verdadeiro \| falso | | [**Substituir gravidade do mundo**](#field-replace-world-gravity)
`replace_world_gravity` | booleano | verdadeiro | verdadeiro \| falso |

Vetor X · vector_x

**Onde:** Inspector → **Campo de gravidade** → **Efeito** → **Vetor X**. **Uso e efeito:** Componente do vetor de contribuição do campo, eixo X. **Valor:** 0 · **Tipo:** número · **Unidade:** m/s² · **Domínio:** -10000 … 10000.

Vetor Y · vector_y

**Onde:** Inspector → **Campo de gravidade** → **Efeito** → **Vetor Y**. **Uso e efeito:** Componente do vetor de contribuição do campo, eixo Y. **Valor:** -9.81 · **Tipo:** número · **Unidade:** m/s² · **Domínio:** -10000 … 10000.

Vetor Z · vector_z

**Onde:** Inspector → **Campo de gravidade** → **Efeito** → **Vetor Z**. **Uso e efeito:** Componente do vetor de contribuição do campo, eixo Z. **Valor:** 0 · **Tipo:** número · **Unidade:** m/s² · **Domínio:** -10000 … 10000.

Ativo · enabled

**Onde:** Inspector → **Campo de gravidade** → **Efeito** → **Ativo**. **Uso e efeito:** Ativa/desativa a participação do componente no sistema consumidor; não remove seus dados. **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Substituir gravidade do mundo · replace_world_gravity

**Onde:** Inspector → **Campo de gravidade** → **Efeito** → **Substituir gravidade do mundo**. **Uso e efeito:** Sobrepostos somam vetores e cancelam a gravidade padrão uma única vez **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso. ### Alcance | Propriedade | Tipo / unidade | Padrão | Domínio | |---|---|---|---| | [**Acordar corpos**](#field-wake-bodies)
`wake_bodies` | booleano | verdadeiro | verdadeiro \| falso | | [**Queda de influência**](#field-falloff)
`falloff` | enumeração | Uniforme | Uniforme \| Linear \| Suave | | [**Camada afetada**](#field-affected-layer)
`affected_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 |

Acordar corpos · wake_bodies

**Onde:** Inspector → **Campo de gravidade** → **Alcance** → **Acordar corpos**. **Uso e efeito:** Desligado: corpos em repouso permanecem dormindo **Valor:** verdadeiro · **Tipo:** booleano · **Domínio:** verdadeiro \| falso.

Queda de influência · falloff

**Onde:** Inspector → **Campo de gravidade** → **Alcance** → **Queda de influência**. **Uso e efeito:** Centro vale 1; Linear e Suave chegam a zero na borda **Valor:** Uniforme · **Tipo:** enumeração · **Domínio:** Uniforme \| Linear \| Suave.

Camada afetada · affected_layer

**Onde:** Inspector → **Campo de gravidade** → **Alcance** → **Camada afetada**. **Uso e efeito:** Todas ou uma camada física do projeto; não altera a matriz de colisão **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/). Ampliar autoria/rebuild, geometria e apoio dos motores, juntas e diagnóstico por cenário. Fechamento deve incluir salvar/reabrir, remoção e gameplay no aparelho. Importação universal de todas as formas e controles não está declarada pronta. 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 **Campo de gravidade** 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_area3d.html). Essa referência não representa paridade funcional.