# Beyz: Referencia Publica De Expressoes

Guia para usuarios do editor de propriedades. Atualizado em 13/10/2026.
A disponibilidade dos recursos depende da versao instalada do Beyz.

## Expressoes E Scripts

Uma expressao calcula uma propriedade ao longo do tempo e fica vinculada
a ela durante playback, scrub e exportacao. Scripts importados automatizam
tarefas ou criam ferramentas. Nao e preciso instalar um pacote de script
para usar o campo de expressao.

Este guia documenta a linguagem publica das expressoes. Nao e uma API de
rede ou instalador de extensoes. A API de scripts, incluindo instalacao
de expressoes por scripts, esta em Beyz-Scripts-API.md.
Nao ha compatibilidade geral com scripts/expressoes de outros aplicativos.

## No Editor

Na gaveta de Movimento, escolha posicao, escala, rotacao ou anchor.
O botao de terminal acima dos tres pontos abre o editor. Escreva e aplique.
Desativar conserva o codigo; remover devolve a propriedade ao canal base.
Keyframes existentes nao sao apagados; alteracoes podem ser desfeitas.

O editor tem cores, numeros de linha, indentacao e sugestoes locais
apagadas. Toque na sugestao ou pressione Tab para aceitar.

## Valores E Unidades

- time: segundos da composicao.
- value: valor original da propriedade, incluindo seus keyframes e tempo
  remapeado. Nao e o resultado da propria expressao.
- sin/cos recebem radianos; a rotacao do editor usa graus.
- Escala 1 significa 100%.
- Rotacao e controles de um eixo retornam um numero.
- Posicao, escala e anchor completos retornam [x, y, z], mesmo em 2D.
  Preserve value[2] quando nao quiser modificar Z.

## Exemplos

Cada bloco e uma expressao independente. Use na propriedade indicada.

Rotacao: 90 graus por segundo.

```js
time * 90
```

Rotacao: somar movimento aos keyframes.

```js
value + time * 90
```

Rotacao: girar no sentido contrario.

```js
-time * 90
```

Rotacao: balanco de 15 graus, uma vez por segundo.

```js
value + sin(time * Math.PI * 2) * 15
```

Posicao: mover X em 100 unidades por segundo.

```js
[value[0] + time * 100, value[1], value[2]]
```

Posicao: oscilar X com amplitude de 40.

```js
[value[0] + sin(time * Math.PI * 2) * 40, value[1], value[2]]
```

Escala: pulsar X/Y em 10%, preservando Z.

```js
const pulse = 1 + sin(time * Math.PI * 2) * 0.1;
[value[0] * pulse, value[1] * pulse, value[2]]
```

Rotacao ou posicao: variacao irregular suave. A amplitude tem a unidade
da propriedade.

```js
wiggle(3, 15)
```

Escala: variacao irregular pequena.

```js
wiggle(2, 0.05)
```

Rotacao: ir de 0 a 90 graus em dois segundos, conservando o valor final.

```js
linear(time, 0, 2, 0, 90)
```

Rotacao: mesma transicao com entrada e parada suaves.

```js
ease(time, 0, 2, 0, 90)
```

Escala: ir de 50% a 100% em dois segundos.

```js
ease(time, 0, 2, [0.5, 0.5, 1], [1, 1, 1])
```

Posicao ou escala: posterizar os keyframes originais em 12 amostras
por segundo. Funciona sem outra linha.

```js
posterizeTime(12);
```

Rotacao: movimento continuo posterizado.

```js
posterizeTime(12);
time * 90
```

Posicao ou rotacao: variacao irregular posterizada.

```js
posterizeTime(12);
wiggle(3, 15)
```

posterizeTime muda a amostragem da expressao, nao o FPS do projeto.
Deve ser a primeira instrucao, aparecer uma unica vez e usar taxa
constante entre 0 e 1000. Zero conserva a amostra do instante zero.

## Funcoes

| Funcao | Uso |
| --- | --- |
| sin, cos | Ondas trigonometricas |
| abs, floor, sqrt, pow | Valor absoluto, piso, raiz e potencia |
| min, max, clamp | Limites numericos |
| length | Comprimento de vetor |
| linear(t, a, b) | Interpolacao limitada, t entre 0 e 1 |
| linear(t, inicio, fim, a, b) | Interpolacao em intervalo explicito |
| ease, easeIn, easeOut | Mesmas assinaturas, com curvas suaves |
| wiggle(freq, amplitude) | Ruido suave somado a value |
| posterizeTime(fps) | Amostragem da expressao inteira |
| read(id, caminho), base(id, caminho) | Valor efetivo ou original |
| valueAtTime(id, caminho, segundos) | Canal base em outro instante |
| velocityAtTime(id, caminho, segundos, intervalo) | Velocidade do canal base |
| bounds(id, [u, v]) | Ponto mundial dos limites da camada |
| toWorld(id, [x, y, z]), toLocal(id, ponto) | Conversao de coordenadas |

Math.PI esta disponivel; funcoes matematicas admitem prefixo Math.
wiggle aceita ainda octaves (1..8, inteiro constante), multiplicador da
amplitude (padrao .5) e tempo explicito. ease usa smoothstep;
easeIn/easeOut usam curvas quadraticas.
IDs e caminhos nas consultas devem ser strings literais validas.
Para descobrir IDs e automatizar vinculos, consulte a API de scripts.

## Limites

O campo compila uma linguagem numerica restrita, nao JavaScript irrestrito.
Aceita contas, variaveis locais, vetores, condicionais e funcoes puras.
Nao oferece acesso ao Android, arquivos, rede ou interface por frame.
Lacos exigem termino conhecido na compilacao, ate 128 iteracoes.
Limites: 16384 caracteres de fonte e 1024 nodes compilados.

loopOut(), loopIn(), thisComp, thisLayer e effect() de outros aplicativos
nao estao disponiveis nesse campo. Exemplos de outras APIs nao sao
automaticamente compativeis.

time * 90 sozinho em posicao inteira retorna um numero, mas a propriedade
exige [x, y, z]. Use o exemplo de movimento horizontal.
Em um eixo individual, um numero e o resultado correto.

Referencia tecnica completa: Beyz-Scripts-API.md, secao de expressoes.