---
title: "Personagem"
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-character/
---

# Personagem

Locomoção com cápsula

**Família:** Física 3D · **Grupo:** Corpos · **Identificador:** `astra.physics.character` · **Payload:** 5

:::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

Locomoção com cápsula

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** / **Corpos** → **Personagem**.

O schema permite uma única instância desse tipo por objeto. A fachada C# correspondente é [Astra.Components.Character](/pt-br/snapshot-2026-10-07/api/astra-components-character/).

A seção Posse de controle escolhe UI, teclado, gamepad, Script ou IA. Prioridades ficam visíveis em Automático. Selecionar uma origem não cria vínculos de entrada. [Arbitragem, cancelamento, campos e receita](/pt-br/snapshot-2026-10-07/sistemas/posse-de-controle/).

**Guia relacionado:** [Posse e movimento medido](/pt-br/snapshot-2026-10-07/sistemas/posse-de-controle/)

## 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

- [Corpo físico](/pt-br/snapshot-2026-10-07/componentes/astra-physics-body/): Incompatível com corpo físico
- [Colisor 3D](/pt-br/snapshot-2026-10-07/componentes/astra-physics-collider/): O personagem traz a própria cápsula; remova o Colisor 3D
- [Motor dinâmico](/pt-br/snapshot-2026-10-07/componentes/astra-physics-dynamic-motor/): Escolha Character ou motor de corpo dinâmico

## Edição e ciclo de vida

| Operação | Contrato |
|---|---|
| Adicionar/remover em Play | não permitido |
| Alterar propriedades em Play | ponto seguro |
| Múltiplas instâncias | Não |
| Versão do payload | 5 |

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.

### Cápsula

| Propriedade | Tipo / unidade | Padrão | Domínio |
|---|---|---|---|
| [**Raio m**](#field-radius)<br/>`radius` | número · m | 0.45 | 0.01 … 10 |
| [**Meia altura do cilindro m**](#field-half-height)<br/>`half_height` | número · m | 0.55 | 0.01 … 10 |
| [**Altura dos olhos m**](#field-eye-height)<br/>`eye_height` | número · m | 1.65 | 0.02 … 20 |

<h4 id="field-radius">Raio m · <code>radius</code></h4>

**Onde:** Inspector → **Personagem** → **Cápsula** → **Raio m**.

**Uso e efeito:** Raio da forma/volume selecionado; confira o tipo e os campos condicionais.

**Valor:** 0.45 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.01 … 10.



<h4 id="field-half-height">Meia altura do cilindro m · <code>half_height</code></h4>

**Onde:** Inspector → **Personagem** → **Cápsula** → **Meia altura do cilindro m**.

**Uso e efeito:** Meia dimensão da forma/volume no eixo indicado. Dimensão total é o dobro; aplica-se à forma selecionada.

**Valor:** 0.55 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.01 … 10.



<h4 id="field-eye-height">Altura dos olhos m · <code>eye_height</code></h4>

**Onde:** Inspector → **Personagem** → **Cápsula** → **Altura dos olhos m**.

**Uso e efeito:** Altura de referência dos olhos do Character.

**Valor:** 1.65 · **Tipo:** número · **Unidade:** m · **Domínio:** 0.02 … 20.



### Locomoção

| Propriedade | Tipo / unidade | Padrão | Domínio |
|---|---|---|---|
| [**Velocidade m/s**](#field-speed)<br/>`speed` | número · m/s | 8 | 0.01 … 100 |
| [**Inclinação máxima graus**](#field-slope-degrees)<br/>`slope_degrees` | número · ° | 45 | 1 … 89 |
| [**Velocidade do salto m/s**](#field-jump-speed)<br/>`jump_speed` | número · m/s | 5 | 0 … 100 |
| [**Gravidade**](#field-gravity)<br/>`gravity` | número · m/s² | 9.81 | 0 … 1000 |

<h4 id="field-speed">Velocidade m/s · <code>speed</code></h4>

**Onde:** Inspector → **Personagem** → **Locomoção** → **Velocidade m/s**.

**Uso e efeito:** Velocidade de reprodução/percurso/motor na unidade do componente.

**Valor:** 8 · **Tipo:** número · **Unidade:** m/s · **Domínio:** 0.01 … 100.



<h4 id="field-slope-degrees">Inclinação máxima graus · <code>slope_degrees</code></h4>

**Onde:** Inspector → **Personagem** → **Locomoção** → **Inclinação máxima graus**.

**Uso e efeito:** Inclinação máxima de apoio do Character.

**Valor:** 45 · **Tipo:** número · **Unidade:** ° · **Domínio:** 1 … 89.



<h4 id="field-jump-speed">Velocidade do salto m/s · <code>jump_speed</code></h4>

**Onde:** Inspector → **Personagem** → **Locomoção** → **Velocidade do salto m/s**.

**Uso e efeito:** Velocidade alvo inicial de salto.

**Valor:** 5 · **Tipo:** número · **Unidade:** m/s · **Domínio:** 0 … 100.



<h4 id="field-gravity">Gravidade · <code>gravity</code></h4>

**Onde:** Inspector → **Personagem** → **Locomoção** → **Gravidade**.

**Uso e efeito:** Aceleração de gravidade do Character.

**Valor:** 9.81 · **Tipo:** número · **Unidade:** m/s² · **Domínio:** 0 … 1000.



### Chão

| Propriedade | Tipo / unidade | Padrão | Domínio |
|---|---|---|---|
| [**Altura do degrau**](#field-step-height)<br/>`step_height` | número · m | 0.4 | 0 … 10 |
| [**Aderência ao chão**](#field-floor-snap-length)<br/>`floor_snap_length` | número · m | 0.5 | 0 … 10 |
| [**Impulso ao sair**](#field-inherit-platform-horizontal)<br/>`inherit_platform_horizontal` | booleano | falso | verdadeiro \| falso |

<h4 id="field-step-height">Altura do degrau · <code>step_height</code></h4>

**Onde:** Inspector → **Personagem** → **Chão** → **Altura do degrau**.

**Uso e efeito:** Altura de degrau que o Character pode transpor.

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



<h4 id="field-floor-snap-length">Aderência ao chão · <code>floor_snap_length</code></h4>

**Onde:** Inspector → **Personagem** → **Chão** → **Aderência ao chão**.

**Uso e efeito:** Distância de snap ao chão; confira degraus e bordas.

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



<h4 id="field-inherit-platform-horizontal">Impulso ao sair · <code>inherit_platform_horizontal</code></h4>

**Onde:** Inspector → **Personagem** → **Chão** → **Impulso ao sair**.

**Uso e efeito:** Conserva X/Z da superfície no ar; desligar remove apenas esse impulso, sem recriar a cápsula.

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



### Posse de controle

| Propriedade | Tipo / unidade | Padrão | Domínio |
|---|---|---|---|
| [**Prioridade UI**](#field-control-priority-ui)<br/>`control_priority_ui` | número | 10 | 0 … 1000 |
| [**Prioridade Teclado / mouse**](#field-control-priority-keyboard)<br/>`control_priority_keyboard` | número | 10 | 0 … 1000 |
| [**Prioridade Gamepad**](#field-control-priority-gamepad)<br/>`control_priority_gamepad` | número | 10 | 0 … 1000 |
| [**Prioridade Script**](#field-control-priority-script)<br/>`control_priority_script` | número | 20 | 0 … 1000 |
| [**Prioridade IA**](#field-control-priority-ai)<br/>`control_priority_ai` | número | 5 | 0 … 1000 |
| [**Fonte de controle**](#field-control-source)<br/>`control_source` | enumeração | Automático | Automático \| UI \| Teclado / mouse \| Gamepad \| Script \| IA |

<h4 id="field-control-priority-ui">Prioridade UI · <code>control_priority_ui</code></h4>

**Onde:** Inspector → **Personagem** → **Posse de controle** → **Prioridade UI**.

**Uso e efeito:** Prioridade de arbitragem desta origem em Automático, de 0 a 1000. Maior vence entre candidatos; na fonte exclusiva fica oculta e é preservada. Não é prioridade de execução do script.

**Valor:** 10 · **Tipo:** número · **Domínio:** 0 … 1000.

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

<h4 id="field-control-priority-keyboard">Prioridade Teclado / mouse · <code>control_priority_keyboard</code></h4>

**Onde:** Inspector → **Personagem** → **Posse de controle** → **Prioridade Teclado / mouse**.

**Uso e efeito:** Prioridade de arbitragem desta origem em Automático, de 0 a 1000. Maior vence entre candidatos; na fonte exclusiva fica oculta e é preservada. Não é prioridade de execução do script.

**Valor:** 10 · **Tipo:** número · **Domínio:** 0 … 1000.

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

<h4 id="field-control-priority-gamepad">Prioridade Gamepad · <code>control_priority_gamepad</code></h4>

**Onde:** Inspector → **Personagem** → **Posse de controle** → **Prioridade Gamepad**.

**Uso e efeito:** Prioridade de arbitragem desta origem em Automático, de 0 a 1000. Maior vence entre candidatos; na fonte exclusiva fica oculta e é preservada. Não é prioridade de execução do script.

**Valor:** 10 · **Tipo:** número · **Domínio:** 0 … 1000.

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

<h4 id="field-control-priority-script">Prioridade Script · <code>control_priority_script</code></h4>

**Onde:** Inspector → **Personagem** → **Posse de controle** → **Prioridade Script**.

**Uso e efeito:** Prioridade de arbitragem desta origem em Automático, de 0 a 1000. Maior vence entre candidatos; na fonte exclusiva fica oculta e é preservada. Não é prioridade de execução do script.

**Valor:** 20 · **Tipo:** número · **Domínio:** 0 … 1000.

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

<h4 id="field-control-priority-ai">Prioridade IA · <code>control_priority_ai</code></h4>

**Onde:** Inspector → **Personagem** → **Posse de controle** → **Prioridade IA**.

**Uso e efeito:** Prioridade de arbitragem desta origem em Automático, de 0 a 1000. Maior vence entre candidatos; na fonte exclusiva fica oculta e é preservada. Não é prioridade de execução do script.

**Valor:** 5 · **Tipo:** número · **Domínio:** 0 … 1000.

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

<h4 id="field-control-source">Fonte de controle · <code>control_source</code></h4>

**Onde:** Inspector → **Personagem** → **Posse de controle** → **Fonte de controle**.

**Uso e efeito:** Automático arbitra os canais; UI/Teclado/Gamepad/Script/IA escolhe uma origem exclusiva. Origem exclusiva neutra mantém a posse; não passa para a IA.

**Valor:** Automático · **Tipo:** enumeração · **Domínio:** Automático \| UI \| Teclado / mouse \| Gamepad \| Script \| IA.



## 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 **Personagem** 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-CharacterController.html). Essa referência não representa paridade funcional.

## 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 |
|---|---|---|
| **Bateu num colisor** · `collider_hit` | O movimento do personagem colidiu com um corpo; carrega o objeto, o ponto e a normal | Objeto tocado: objeto; Ponto: vetor (m); Normal: vetor |