---
title: "Tween de propriedade"
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-tween-property/
---

# Tween de propriedade

Interpola uma propriedade numérica interpolável de um componente

**Família:** Lógica · **Grupo:** Tempo · **Identificador:** `astra.tween.property` · **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

Interpola uma propriedade numérica de um componente existente. Use para variar uma luz, um parâmetro de material ou outro campo marcado como interpolável.

Escolha Alvo; vazio usa este objeto. No seletor de propriedade, escolha o tipo de componente e o campo numérico. Destino usa a unidade desse campo. Recursos, strings, booleanos e enums não entram nesse seletor.

## Criar e configurar

Hierarquia → selecione o objeto → Inspector → Adicionar componente → **Lógica** / **Tempo** → **Tween de propriedade**.

O schema permite múltiplas instâncias no mesmo objeto; identifique a instância antes de editar ou remover. A fachada C# correspondente é [Astra.Components.PropertyTween](/pt-br/snapshot-2026-10-07/api/astra-components-propertytween/).

Tipo de componente e PropertyId escolhidos são configuração persistente especializada, fora da tabela numérica. O consumidor usa a primeira instância desse tipo no alvo; o seletor não grava um InstanceId para escolher outra. Não confunda o nome exibido com o identificador. Dois tweens no mesmo campo podem disputar a escrita; use um consumidor por campo no primeiro exercício.

**Guia relacionado:** [Montagem passo a passo](/pt-br/snapshot-2026-10-06/versoes/preview-2026-10-07/#tween-de-propriedade-animar-um-campo)

## Exemplo de uso

Em uma luz, escolha o campo de intensidade pelo seletor. Use Destino 2, Duração 1 s, Espera 0 e Destino relativo desligado. Em Play, a intensidade deve chegar a 2, dentro dos limites do campo. Compare depois Destino relativo ligado: 2 passa a ser um incremento. A receita não representa uma execução validada desta publicação.



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

### Propriedade

| Propriedade | Tipo / unidade | Padrão | Domínio |
|---|---|---|---|
| [**Destino**](#field-destination)<br/>`destination` | número | 0 | -100000 … 100000 |
| [**Destino relativo**](#field-relative)<br/>`relative` | booleano | falso | verdadeiro \| falso |
| [**Alvo**](#field-target)<br/>`target` | referência | Este objeto | qualquer objeto |

<h4 id="field-destination">Destino · <code>destination</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Propriedade** → **Destino**.

**Uso e efeito:** Valor de chegada na unidade do campo selecionado. Relativo desligado = valor final; ligado = incremento a partir do início.

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



<h4 id="field-relative">Destino relativo · <code>relative</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Propriedade** → **Destino relativo**.

**Uso e efeito:** Interpreta os valores da transição como deslocamento relativo, conforme o canal.

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



<h4 id="field-target">Alvo · <code>target</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Propriedade** → **Alvo**.

**Uso e efeito:** Objeto dono do componente animado; vazio usa este objeto

**Valor:** Este objeto · **Tipo:** referência · **Domínio:** qualquer objeto.



### Tempo

| Propriedade | Tipo / unidade | Padrão | Domínio |
|---|---|---|---|
| [**Duração**](#field-duration)<br/>`duration` | número · s | 1 | 0.001 … 36000 |
| [**Espera**](#field-delay)<br/>`delay` | número · s | 0 | 0 … 36000 |
| [**Ativo**](#field-enabled)<br/>`enabled` | booleano | verdadeiro | verdadeiro \| falso |
| [**Iniciar no Play**](#field-autoplay)<br/>`autoplay` | booleano | verdadeiro | verdadeiro \| falso |
| [**Ignorar escala de tempo**](#field-ignore-time-scale)<br/>`ignore_time_scale` | booleano | falso | verdadeiro \| falso |
| [**Curva**](#field-easing)<br/>`easing` | enumeração | Linear | Linear \| Smoothstep \| Quadrático entrada \| Quadrático saída |

<h4 id="field-duration">Duração · <code>duration</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Tempo** → **Duração**.

**Uso e efeito:** Tempo da reprodução/interpolação; configure na unidade indicada. Valor curto acelera a transição.

**Valor:** 1 · **Tipo:** número · **Unidade:** s · **Domínio:** 0.001 … 36000.



<h4 id="field-delay">Espera · <code>delay</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Tempo** → **Espera**.

**Uso e efeito:** Espera inicial antes de reproduzir a transição.

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



<h4 id="field-enabled">Ativo · <code>enabled</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Tempo** → **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.



<h4 id="field-autoplay">Iniciar no Play · <code>autoplay</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Tempo** → **Iniciar no Play**.

**Uso e efeito:** Inicia a reprodução automaticamente ao ativar a execução; não é o mesmo que repetição.

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



<h4 id="field-ignore-time-scale">Ignorar escala de tempo · <code>ignore_time_scale</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Tempo** → **Ignorar escala de tempo**.

**Uso e efeito:** Usa relógio não afetado pela escala do tempo do mundo; confira pausa e segundos reais.

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



<h4 id="field-easing">Curva · <code>easing</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Tempo** → **Curva**.

**Uso e efeito:** Escolhe a curva de interpolação; altera a velocidade ao longo da transição, não o valor final.

**Valor:** Linear · **Tipo:** enumeração · **Domínio:** Linear \| Smoothstep \| Quadrático entrada \| Quadrático saída.



### Repetição

| Propriedade | Tipo / unidade | Padrão | Domínio |
|---|---|---|---|
| [**Ida e volta**](#field-pingpong)<br/>`pingpong` | booleano | falso | verdadeiro \| falso |
| [**Repetição**](#field-loops)<br/>`loops` | enumeração | Uma vez | Infinito \| Uma vez \| Duas vezes \| Três vezes \| Dez vezes |

<h4 id="field-pingpong">Ida e volta · <code>pingpong</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Repetição** → **Ida e volta**.

**Uso e efeito:** Alterna ida e volta na reprodução.

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



<h4 id="field-loops">Repetição · <code>loops</code></h4>

**Onde:** Inspector → **Tween de propriedade** → **Repetição** → **Repetição**.

**Uso e efeito:** Número/política de repetições no domínio indicado; confira a opção de repetição contínua na enumeração/contrato.

**Valor:** Uma vez · **Tipo:** enumeração · **Domínio:** Infinito \| Uma vez \| Duas vezes \| Três vezes \| Dez vezes.



## Roadmap deste componente

[Tempo, eventos e tweens](/pt-br/snapshot-2026-10-06/roadmap/tempo-eventos-e-tweens/). Presente no APK 0.2.3; seletor numérico, lifecycle e comandos Restart/Cancel/Pause/Resume constam do contrato. Animação arbitrária de qualquer recurso/campo não é suportada. Sem data para expansões.

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 **Tween de propriedade** 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_tween.html#class-tween-method-tween-property). 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 |
|---|---|---|---|
| **Reiniciar** · `restart` | Recomeça do valor atual da propriedade, conservando a pausa | Nenhum | nada |
| **Cancelar** · `cancel` | Interrompe sem voltar ao valor inicial | Nenhum | nada |
| **Pausar** · `pause` | Congela o progresso | Nenhum | nada |
| **Retomar** · `resume` | Continua o progresso pausado | Nenhum | nada |
| **Decorrido** · `elapsed` | Segundos desde o início, incluindo a espera | Nenhum | número |

[Assinaturas da fachada PropertyTween](/pt-br/snapshot-2026-10-07/api/astra-components-propertytween/#membros)

## 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 |
|---|---|---|
| **Concluiu** · `completed` | Emitido uma vez quando as repetições finitas terminam, depois do valor final | Nenhum |