Quadros e tags

app.addFrame(frameId?, durationMs?, before?) — altera, desfazível

Adiciona um novo quadro em branco ("Novo quadro vazio" no menu Quadro), depois de frameId ou antes dele com before. O novo quadro passa a ser o ativo.

• frameId (string, opcional) — O quadro ao lado do qual inserir. Omita (ou passe nil) para adicionar no final.
• durationMs (number, opcional) — O padrão é a duração padrão de quadro do sprite.
• before (boolean, opcional) — True insere o novo quadro antes de frameId em vez de depois dele, o único jeito de adicionar um quadro antes do primeiro. Exige um frameId.

Retorna (string): O id do novo quadro.

app.addTag(fromFrameId, toFrameId, name?, color?, direction?) — altera, desfazível

Cria uma nova tag abrangendo [fromFrameId, toFrameId].

• fromFrameId (string)
• toFrameId (string)
• name (string, opcional) — O padrão é "Tag N".
• color (string, opcional) — Cor em hex.
• direction (TagDirection: "forward" | "reverse" | "pingpong" | "pingpongReverse", opcional) — Direção de reprodução; o padrão é forward.

Retorna (string): O id da nova tag.

app.bakeTween(layerId, frameId) — altera, desfazível, recusada em uma camada bloqueada

Remove o tween que começa em frameId, mas mantém todos os intermediários como cels comuns, que deixam de ser redesenhados. Um passo de desfazer.

• layerId (string) — Uma camada de imagem (não o Plano de fundo).
• frameId (string) — O quadro do keyframe inicial: o cel da própria camada ali (não um vínculo) é o que recebe o tween.

Não retorna nada.

app.duplicateFrame(frameId, linked?) — altera, desfazível

Duplica um quadro (e seus cels) logo depois dele, tornando a cópia ativa ("Novo quadro" no menu Quadro).

• frameId (string)
• linked (boolean, opcional) — True vincula cada cel copiado ao do original (imagens compartilhadas), false copia todos; omitido, as camadas contínuas vinculam e as outras copiam.

Retorna (string): O id do quadro da cópia.

app.getActiveFrameId() — lê

O id do quadro ativo no momento, ou nil se não houver.

Retorna (string): Id do quadro ou nil.

app.getFrame(frameId) — lê

Um quadro como { id, index, durationMs }, ou nil se não existir esse quadro.

• frameId (string)

Retorna (table): Tabela do quadro ou nil.

app.getFrames() — lê

Todos os quadros na ordem da linha do tempo, como { id, index (0 = primeiro), durationMs }.

Retorna (table): Array de tabelas de quadro.

app.getTags() — lê

Todas as tags de animação, como { id, name, fromFrameId, toFrameId, fromIndex, toIndex (índices de quadro inclusivos), color (hex), direction ("forward" | "reverse" | "pingpong" | "pingpongReverse"), repeat (vezes que é reproduzida antes de continuar; ausente = repete para sempre) }.

Retorna (table): Array de tabelas de tag.

app.moveFrame(frameId, toIndex) — altera, desfazível

Move um quadro para uma nova posição na linha do tempo.

• frameId (string)
• toIndex (number) — Posição de destino na ordem final, limitada ao intervalo válido.

Não retorna nada.

app.regenerateTween(layerId, frameId, revertFrameIds?) — altera, desfazível, recusada em uma camada bloqueada

Redesenha os intermediários do tween que começa em frameId a partir do cel inicial. Os quadros que você editou à mão são ignorados, a menos que estejam em revertFrameIds. Um tween cujo quadro final não existe mais não pode ser redesenhado. Um passo de desfazer; se não houver nada a alterar, nenhum é adicionado.

• layerId (string) — Uma camada de imagem (não o Plano de fundo).
• frameId (string) — O quadro do keyframe inicial: o cel da própria camada ali (não um vínculo) é o que recebe o tween.
• revertFrameIds (table, opcional) — Uma lista de ids de quadros intermediários cujos cels editados à mão também são redesenhados.

Não retorna nada.

app.removeFrame(frameId) — altera, desfazível

Remove um quadro e todos os cels, posicionamentos de tiles e posicionamentos de referência nele. Gera um erro se for o último quadro restante.

• frameId (string)

Não retorna nada.

app.removeTag(tagId) — altera, desfazível

Remove uma tag (os quadros que ela abrangia não são tocados).

• tagId (string)

Não retorna nada.

app.removeTween(layerId, frameId) — altera, desfazível, recusada em uma camada bloqueada

Remove o tween que começa em frameId, excluindo os intermediários gerados por ele (os quadros que você editou à mão permanecem como cels comuns). Um passo de desfazer.

• layerId (string) — Uma camada de imagem (não o Plano de fundo).
• frameId (string) — O quadro do keyframe inicial: o cel da própria camada ali (não um vínculo) é o que recebe o tween.

Não retorna nada.

app.reverseFrames(fromFrameId?, toFrameId?) — altera, desfazível

Inverte a ordem dos quadros em um intervalo (todos os quadros quando omitido) em um passo de desfazer. Cels, vínculos, posicionamentos de tilemap e transformações de referência se movem com seus quadros; as tags continuam cobrindo as mesmas posições.

• fromFrameId (string, opcional) — Primeiro quadro do intervalo; omita (junto com toFrameId) para inverter todos os quadros.
• toFrameId (string, opcional) — Último quadro do intervalo (inclusivo).

Não retorna nada.

app.setActiveFrame(frameId) — altera

Torna um quadro o ativo (o que clicar nele na linha do tempo faz). Não é uma edição que possa ser desfeita.

• frameId (string)

Não retorna nada.

app.setAllFrameDurations(durationMs) — altera, desfazível

Define todos os quadros do sprite com a mesma duração de reprodução.

• durationMs (number)

Não retorna nada.

app.setFrameDuration(frameId, durationMs) — altera, desfazível

Define a duração de reprodução de um quadro.

• frameId (string)
• durationMs (number) — Milissegundos inteiros, de 1 a 65535.

Não retorna nada.

app.setFrameProps(frameId, props) — altera, desfazível

Define o rótulo de cor e/ou o bloqueio de um quadro.

• frameId (string)
• props (table) — As chaves omitidas permanecem inalteradas.
  • color (string) — O rótulo do quadro na linha do tempo como "#rrggbb"; uma string vazia o limpa.
  • locked (boolean) — Os cels de um quadro bloqueado não podem ser editados por nada, scripts inclusive, e o quadro não pode ser removido, movido nem ter a duração alterada.

Não retorna nada.

app.setTagProps(tagId, props) — altera, desfazível

Atualiza uma ou mais propriedades de uma tag.

• tagId (string)
• props (table) — As chaves omitidas permanecem inalteradas.
  • name (string) — O nome da tag.
  • color (string) — A cor da tag como "#rrggbb".
  • direction (TagDirection: "forward" | "reverse" | "pingpong" | "pingpongReverse") — Direção de reprodução.
  • fromFrameId (string) — O primeiro quadro do trecho.
  • toFrameId (string) — O último quadro do trecho.
  • repeat (integer ≥ 0) — Quantas vezes a reprodução toca a tag antes de continuar (o Repeat da tag no Aseprite); 0 repete para sempre.

Não retorna nada.

app.setTween(layerId, frameId, opts?) — altera, desfazível, recusada em uma camada bloqueada

Aplica um tween ao cel de uma camada em frameId até um quadro posterior: os quadros intermediários recebem cels reais (a imagem do cel inicial movida, escalada, girada, inclinada e esmaecida conforme as opções, com o easing escolhido) que continuam vinculados à receita, então são redesenhados quando o cel inicial muda. Substitui um tween que já comece ali. Um passo de desfazer. Os quadros em que você desenhou permanecem como estão. Retorna o id do tween.

• layerId (string) — Uma camada de imagem (não o Plano de fundo).
• frameId (string) — O quadro do keyframe inicial: o cel da própria camada ali (não um vínculo) é o que recebe o tween.
• opts (table, opcional)
  • to (string) — Obrigatório. O id do quadro do keyframe final: um quadro posterior na mesma camada. Os intermediários são os quadros estritamente entre eles; o quadro final mantém o seu próprio desenho.
  • from ({ dx, dy, scaleX, scaleY, rotation, skewX, skewY, opacity }, each optional (missing = no change: 0, 1, 0, 0, 1); padrão no change) — A pose no keyframe inicial (normalmente deixada como está).
  • end ({ dx, dy, scaleX, scaleY, rotation, skewX, skewY, opacity }, each optional (missing = no change: 0, 1, 0, 0, 1); padrão no change) — A pose alcançada no keyframe final: translação em pixels do sprite, escala (1 = igual), rotação e inclinação em graus, multiplicador de opacidade de 0..1.
  • ease (TweenEaseFamily: "linear" | "hold" | "sine" | "quad" | "cubic" | "quart" | "quint" | "expo" | "circ" | "back" | "elastic" | "bounce"; padrão "quad") — A curva de easing de todas as trilhas. Ignorada quando steps é informado.
  • mode (TweenEaseMode: "in" | "out" | "inOut"; padrão "inOut") — Qual extremo do tween ease modela (ignorado por linear e hold).
  • overshoot (number 0–10) — Easing back: quanto ele recua ou ultrapassa (padrão 1.70158). Somente com ease = "back".
  • amplitude (number 1–10) — Easing elastic: tamanho do pico (padrão 1). Somente com ease = "elastic".
  • period (number 0.01–1) — Easing elastic: duração da oscilação como fração do trecho (padrão 0.3). Somente com ease = "elastic".
  • bounces (integer 1–8) — Easing bounce: número de quicadas (padrão 4). Somente com ease = "bounce".
  • steps (integer 1–64) — Quantiza o progresso nesta quantidade de saltos iguais (um visual em degraus, com quadros mantidos) em vez de uma curva suave.
  • curve (a list of 2-32 anchors { x, y, inX?, inY?, outX?, outY?, corner? }; the first is x = 0, y = 0 and the last x = 1, y = 1, and x rises along the list) — Uma curva de easing desenhada passando por essas âncoras (béziers cúbicas; inX/inY e outX/outY são as alças como deslocamentos a partir da âncora, 0 por padrão). Substitui ease e steps.
  • trackEasing ({ position?, scale?, rotation?, skew?, opacity?, color? }, each an easing table with the same keys as the easing options (ease, mode, overshoot, amplitude, period, bounces, steps, curve)) — Easing para trilhas individuais, substituindo o padrão somente nessas trilhas.
  • color ({ hue?, saturation?, lightness?, tint? }: hue in degrees (-360..360), saturation and lightness -100..100, tint 0..1) — Ajustes de cor alcançados na pose final, aplicados à imagem inicial (Matiz/Saturação HSL e depois a tinta). Os campos omitidos permanecem neutros (0). O easing da trilha color os modela.
  • colorFrom (the same fields as color; padrão all neutral) — Os ajustes de cor no keyframe inicial (normalmente deixados como estão).
  • tintColor (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); padrão "#ffffff") — A cor para a qual o tingimento mistura (o alfa dela é ignorado).
  • ramp ({ first, last, shift, wrap? }: palette indices first..last (0-255), shift in whole places (-255..255), wrap true by default) — Somente sprites indexed: os pixels cujo índice de paleta está em first..last (o índice transparente excluído) se movem ao longo desse trecho da paleta em shift posições durante o intervalo, voltando ao início ao passar das pontas com wrap e parando nelas caso contrário. Ignorado nos outros modos de cor. O easing da trilha color o modela.
  • path (TweenPath: "straight" | "arc" | "wave" | "zigzag" | "shake" | "custom"; padrão "straight") — O trajeto que a posição segue entre as poses, como um deslocamento em relação à linha reta.
  • points (a list of 2-64 anchors { x, y, inX?, inY?, outX?, outY?, corner? } in sprite pixels relative to the start cel's position; inX/inY and outX/outY are the handles as offsets from the anchor (0 by default)) — trajetória custom: o trajeto desenhado, uma Bézier cúbica pelas âncoras, percorrida em velocidade constante. Obrigatória com path = "custom". A primeira âncora é a posição from e a última a posição end: quando from ou end omitem dx/dy, eles vêm daí, e os informados precisam coincidir.
  • orient (boolean; padrão false) — Gira o desenho para seguir a direção do movimento ao longo da trajetória (somado à rotação; sem giro no início). Usa resample (RotSprite é uma boa escolha).
  • height (number) — Trajeto arc: a altura da curva em pixels. Padrão 8.
  • pathAmplitude (number) — Trajetos wave, zigzag e shake: o deslocamento em pixels. Padrão 4.
  • cycles (number 0–64) — Trajetos wave e zigzag: quantas ondas completas de comprimento. Padrão 1.
  • phase (number -1–1) — Trajeto wave: onde na onda ele começa, em voltas. Padrão 0.
  • seed (integer ≥ 0) — Trajeto shake: o seed aleatório; um mesmo seed sempre treme do mesmo jeito. Padrão 1.
  • fade (TweenFade: "alpha" | "dither"; padrão "alpha") — Como a trilha de opacidade aparece: opacidade parcial ou uma dissolução com dithering de pixels inteiros.
  • ditherPattern (TweenDither: "bayer2" | "bayer4" | "bayer8" | "cluster"; padrão "bayer4") — O padrão pelo qual um fade com dithering se dissolve, fixo na tela para não se arrastar quando o desenho se move. Informá-lo implica fade = "dither".
  • crossfade (boolean; padrão false) — Faz a transição do desenho inicial para o próprio desenho do keyframe final (pelo easing da trilha de opacidade), com dithering ou mesclado conforme fade. O desenho do keyframe final passa a ser uma entrada: editá-lo redesenha o tween.
  • delay (integer 0–4096; padrão 0) — Quadros em que a pose inicial é mantida antes de se mover; depois o movimento preenche o resto do trecho.
  • trackDelay ({ position?, scale?, rotation?, skew?, opacity?, color? }, each a whole number of frames (0-4096)) — Atrasos para trilhas específicas, substituindo delay só nessas trilhas.
  • preset (a preset recipe, as app.tweenPreset returns: { from, end, easing, path, squash, pivotX, pivotY, exposure, shortestRotation, pingPong, trackEasing?, color?, orient?, fade?, delay?, trackDelay? } with distances relative to the start cel's size) — Monta o tween a partir de uma predefinição, ajustada ao cel inicial (distâncias são frações do tamanho dele, atrasos frações do trecho). Junto dela só podem ir to, resample, subpixel, timing, autoRegenerate, fade, ditherPattern, crossfade, delay e orient, que substituem os da predefinição.
  • squash (number 0–1; padrão 0) — Achatamento e alongamento (squash and stretch) baseados na velocidade, preservando o volume.
  • pivotX (number; padrão 0.5) — Ponto fixo de escala, rotação e inclinação, como fração da largura do cel inicial (0.5 = centro).
  • pivotY (number; padrão 0.5) — O mesmo, como fração da altura do cel inicial.
  • pivotSpace (TweenPivotSpace: "cel" | "sprite"; padrão "cel") — Em que estão pivotX e pivotY. "sprite" os torna um ponto em pixels do sprite, o mesmo para cada camada animada com ele.
  • resample (TransformInterpolation: "nearest" | "rotsprite" | "bilinear"; padrão "nearest") — Como os pixels são reamostrados quando escala, rotação ou inclinação mudam. Uma translação pura sempre copia os pixels exatamente.
  • subpixel (TweenSubpixel: "round" | "floor" | "monotonic"; padrão "round") — Como as posições fracionárias caem em pixels inteiros.
  • timing (TweenTiming: "frames" | "time"; padrão "frames") — O que conta como progresso.
  • exposure (integer 1–8; padrão 1) — Desenha uma pose a cada N e a mantém ("on twos" = 2).
  • shortestRotation (boolean; padrão true) — Gira pelo caminho mais curto (a variação ajustada para -180..180) em vez do número exato de graus.
  • pingPong (boolean; padrão false) — Ida e volta: o movimento chega à pose final na metade do trecho e retorna à pose inicial no keyframe final, então um loop que termina onde começou não precisa de um segundo desenho. O easing modela cada metade.
  • autoRegenerate (boolean; padrão true) — Redesenha os intermediários sozinho quando o keyframe inicial ou os quadros mudam.

Retorna (string): O id do tween.

app.setTweenChain(layerId, frameIds, opts?) — altera, desfazível, recusada em uma camada bloqueada

Aplica tweens por vários keyframes de uma camada em um só passo: um tween de cada keyframe até o seguinte, todos com as mesmas opções (as mesmas de app.setTween sem to). Os tweens que já começam nesses quadros são substituídos; os outros da camada não devem se sobrepor. Um passo de desfazer. Retorna os ids dos tweens, em ordem.

• layerId (string) — Uma camada de imagem (não o Plano de fundo).
• frameIds (table) — Os keyframes da cadeia como uma lista de ids de quadro, do mais antigo ao mais recente (2 ou mais). Um tween vai de cada um ao seguinte, então os vizinhos compartilham um keyframe; todos, menos o último, precisam do próprio cel.
• opts (table, opcional)
  • from ({ dx, dy, scaleX, scaleY, rotation, skewX, skewY, opacity }, each optional (missing = no change: 0, 1, 0, 0, 1); padrão no change) — A pose no keyframe inicial (normalmente deixada como está).
  • end ({ dx, dy, scaleX, scaleY, rotation, skewX, skewY, opacity }, each optional (missing = no change: 0, 1, 0, 0, 1); padrão no change) — A pose alcançada no keyframe final: translação em pixels do sprite, escala (1 = igual), rotação e inclinação em graus, multiplicador de opacidade de 0..1.
  • ease (TweenEaseFamily: "linear" | "hold" | "sine" | "quad" | "cubic" | "quart" | "quint" | "expo" | "circ" | "back" | "elastic" | "bounce"; padrão "quad") — A curva de easing de todas as trilhas. Ignorada quando steps é informado.
  • mode (TweenEaseMode: "in" | "out" | "inOut"; padrão "inOut") — Qual extremo do tween ease modela (ignorado por linear e hold).
  • overshoot (number 0–10) — Easing back: quanto ele recua ou ultrapassa (padrão 1.70158). Somente com ease = "back".
  • amplitude (number 1–10) — Easing elastic: tamanho do pico (padrão 1). Somente com ease = "elastic".
  • period (number 0.01–1) — Easing elastic: duração da oscilação como fração do trecho (padrão 0.3). Somente com ease = "elastic".
  • bounces (integer 1–8) — Easing bounce: número de quicadas (padrão 4). Somente com ease = "bounce".
  • steps (integer 1–64) — Quantiza o progresso nesta quantidade de saltos iguais (um visual em degraus, com quadros mantidos) em vez de uma curva suave.
  • curve (a list of 2-32 anchors { x, y, inX?, inY?, outX?, outY?, corner? }; the first is x = 0, y = 0 and the last x = 1, y = 1, and x rises along the list) — Uma curva de easing desenhada passando por essas âncoras (béziers cúbicas; inX/inY e outX/outY são as alças como deslocamentos a partir da âncora, 0 por padrão). Substitui ease e steps.
  • trackEasing ({ position?, scale?, rotation?, skew?, opacity?, color? }, each an easing table with the same keys as the easing options (ease, mode, overshoot, amplitude, period, bounces, steps, curve)) — Easing para trilhas individuais, substituindo o padrão somente nessas trilhas.
  • ends (a list of end pose tables, one per segment (same fields as end)) — Somente para app.setTweenChain: uma pose final diferente para cada segmento, em ordem; cada uma substitui end no seu segmento.
  • color ({ hue?, saturation?, lightness?, tint? }: hue in degrees (-360..360), saturation and lightness -100..100, tint 0..1) — Ajustes de cor alcançados na pose final, aplicados à imagem inicial (Matiz/Saturação HSL e depois a tinta). Os campos omitidos permanecem neutros (0). O easing da trilha color os modela.
  • colorFrom (the same fields as color; padrão all neutral) — Os ajustes de cor no keyframe inicial (normalmente deixados como estão).
  • tintColor (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); padrão "#ffffff") — A cor para a qual o tingimento mistura (o alfa dela é ignorado).
  • ramp ({ first, last, shift, wrap? }: palette indices first..last (0-255), shift in whole places (-255..255), wrap true by default) — Somente sprites indexed: os pixels cujo índice de paleta está em first..last (o índice transparente excluído) se movem ao longo desse trecho da paleta em shift posições durante o intervalo, voltando ao início ao passar das pontas com wrap e parando nelas caso contrário. Ignorado nos outros modos de cor. O easing da trilha color o modela.
  • path (TweenPath: "straight" | "arc" | "wave" | "zigzag" | "shake" | "custom"; padrão "straight") — O trajeto que a posição segue entre as poses, como um deslocamento em relação à linha reta.
  • points (a list of 2-64 anchors { x, y, inX?, inY?, outX?, outY?, corner? } in sprite pixels relative to the start cel's position; inX/inY and outX/outY are the handles as offsets from the anchor (0 by default)) — trajetória custom: o trajeto desenhado, uma Bézier cúbica pelas âncoras, percorrida em velocidade constante. Obrigatória com path = "custom". A primeira âncora é a posição from e a última a posição end: quando from ou end omitem dx/dy, eles vêm daí, e os informados precisam coincidir.
  • orient (boolean; padrão false) — Gira o desenho para seguir a direção do movimento ao longo da trajetória (somado à rotação; sem giro no início). Usa resample (RotSprite é uma boa escolha).
  • height (number) — Trajeto arc: a altura da curva em pixels. Padrão 8.
  • pathAmplitude (number) — Trajetos wave, zigzag e shake: o deslocamento em pixels. Padrão 4.
  • cycles (number 0–64) — Trajetos wave e zigzag: quantas ondas completas de comprimento. Padrão 1.
  • phase (number -1–1) — Trajeto wave: onde na onda ele começa, em voltas. Padrão 0.
  • seed (integer ≥ 0) — Trajeto shake: o seed aleatório; um mesmo seed sempre treme do mesmo jeito. Padrão 1.
  • fade (TweenFade: "alpha" | "dither"; padrão "alpha") — Como a trilha de opacidade aparece: opacidade parcial ou uma dissolução com dithering de pixels inteiros.
  • ditherPattern (TweenDither: "bayer2" | "bayer4" | "bayer8" | "cluster"; padrão "bayer4") — O padrão pelo qual um fade com dithering se dissolve, fixo na tela para não se arrastar quando o desenho se move. Informá-lo implica fade = "dither".
  • crossfade (boolean; padrão false) — Faz a transição do desenho inicial para o próprio desenho do keyframe final (pelo easing da trilha de opacidade), com dithering ou mesclado conforme fade. O desenho do keyframe final passa a ser uma entrada: editá-lo redesenha o tween.
  • delay (integer 0–4096; padrão 0) — Quadros em que a pose inicial é mantida antes de se mover; depois o movimento preenche o resto do trecho.
  • trackDelay ({ position?, scale?, rotation?, skew?, opacity?, color? }, each a whole number of frames (0-4096)) — Atrasos para trilhas específicas, substituindo delay só nessas trilhas.
  • squash (number 0–1; padrão 0) — Achatamento e alongamento (squash and stretch) baseados na velocidade, preservando o volume.
  • pivotX (number; padrão 0.5) — Ponto fixo de escala, rotação e inclinação, como fração da largura do cel inicial (0.5 = centro).
  • pivotY (number; padrão 0.5) — O mesmo, como fração da altura do cel inicial.
  • pivotSpace (TweenPivotSpace: "cel" | "sprite"; padrão "cel") — Em que estão pivotX e pivotY. "sprite" os torna um ponto em pixels do sprite, o mesmo para cada camada animada com ele.
  • resample (TransformInterpolation: "nearest" | "rotsprite" | "bilinear"; padrão "nearest") — Como os pixels são reamostrados quando escala, rotação ou inclinação mudam. Uma translação pura sempre copia os pixels exatamente.
  • subpixel (TweenSubpixel: "round" | "floor" | "monotonic"; padrão "round") — Como as posições fracionárias caem em pixels inteiros.
  • timing (TweenTiming: "frames" | "time"; padrão "frames") — O que conta como progresso.
  • exposure (integer 1–8; padrão 1) — Desenha uma pose a cada N e a mantém ("on twos" = 2).
  • shortestRotation (boolean; padrão true) — Gira pelo caminho mais curto (a variação ajustada para -180..180) em vez do número exato de graus.
  • pingPong (boolean; padrão false) — Ida e volta: o movimento chega à pose final na metade do trecho e retorna à pose inicial no keyframe final, então um loop que termina onde começou não precisa de um segundo desenho. O easing modela cada metade.
  • autoRegenerate (boolean; padrão true) — Redesenha os intermediários sozinho quando o keyframe inicial ou os quadros mudam.

Retorna (table): Os ids dos tweens, um por segmento, em ordem.

app.setTweenEnd(layerId, frameId, toFrameId) — altera, desfazível, recusada em uma camada bloqueada

Move o fim do tween que começa em frameId para outro quadro e o redesenha. Os intermediários que ficam fora do novo intervalo são excluídos (ou mantidos como cels comuns, se você os editou); o próprio quadro final nunca é tocado. Falha se o novo intervalo se sobrepuser a outro tween da camada. Um passo de desfazer.

• layerId (string) — Uma camada de imagem (não o Plano de fundo).
• frameId (string) — O quadro do keyframe inicial: o cel da própria camada ali (não um vínculo) é o que recebe o tween.
• toFrameId (string) — O novo keyframe final: um quadro posterior na mesma camada.

Não retorna nada.

app.setTweenStagger(layerIds, frameId, opts?) — altera, desfazível, recusada em uma camada bloqueada

Aplica tween a várias camadas com uma mesma receita (as mesmas opções de app.setTween, ou uma predefinição ajustada ao cel inicial de cada camada), cada camada começando step quadros depois da anterior. Com groupPivot as camadas escalam e giram em torno de um ponto compartilhado, então se movem como um grupo rígido. Tweens que já começam ali são substituídos. Uma única etapa de desfazer. Retorna os ids dos tweens, na ordem de layerIds.

• layerIds (table) — As camadas a animar, como lista de ids: camadas de imagem (não o Fundo), cada uma com seu próprio cel em frameId. Com order = "given", a ordem da lista é a ordem do escalonamento.
• frameId (string) — O quadro do keyframe inicial, compartilhado por todas as camadas.
• opts (table, opcional)
  • to (string) — Obrigatório. O id do quadro do keyframe final: um quadro posterior na mesma camada. Os intermediários são os quadros estritamente entre eles; o quadro final mantém o seu próprio desenho.
  • from ({ dx, dy, scaleX, scaleY, rotation, skewX, skewY, opacity }, each optional (missing = no change: 0, 1, 0, 0, 1); padrão no change) — A pose no keyframe inicial (normalmente deixada como está).
  • end ({ dx, dy, scaleX, scaleY, rotation, skewX, skewY, opacity }, each optional (missing = no change: 0, 1, 0, 0, 1); padrão no change) — A pose alcançada no keyframe final: translação em pixels do sprite, escala (1 = igual), rotação e inclinação em graus, multiplicador de opacidade de 0..1.
  • ease (TweenEaseFamily: "linear" | "hold" | "sine" | "quad" | "cubic" | "quart" | "quint" | "expo" | "circ" | "back" | "elastic" | "bounce"; padrão "quad") — A curva de easing de todas as trilhas. Ignorada quando steps é informado.
  • mode (TweenEaseMode: "in" | "out" | "inOut"; padrão "inOut") — Qual extremo do tween ease modela (ignorado por linear e hold).
  • overshoot (number 0–10) — Easing back: quanto ele recua ou ultrapassa (padrão 1.70158). Somente com ease = "back".
  • amplitude (number 1–10) — Easing elastic: tamanho do pico (padrão 1). Somente com ease = "elastic".
  • period (number 0.01–1) — Easing elastic: duração da oscilação como fração do trecho (padrão 0.3). Somente com ease = "elastic".
  • bounces (integer 1–8) — Easing bounce: número de quicadas (padrão 4). Somente com ease = "bounce".
  • steps (integer 1–64) — Quantiza o progresso nesta quantidade de saltos iguais (um visual em degraus, com quadros mantidos) em vez de uma curva suave.
  • curve (a list of 2-32 anchors { x, y, inX?, inY?, outX?, outY?, corner? }; the first is x = 0, y = 0 and the last x = 1, y = 1, and x rises along the list) — Uma curva de easing desenhada passando por essas âncoras (béziers cúbicas; inX/inY e outX/outY são as alças como deslocamentos a partir da âncora, 0 por padrão). Substitui ease e steps.
  • trackEasing ({ position?, scale?, rotation?, skew?, opacity?, color? }, each an easing table with the same keys as the easing options (ease, mode, overshoot, amplitude, period, bounces, steps, curve)) — Easing para trilhas individuais, substituindo o padrão somente nessas trilhas.
  • color ({ hue?, saturation?, lightness?, tint? }: hue in degrees (-360..360), saturation and lightness -100..100, tint 0..1) — Ajustes de cor alcançados na pose final, aplicados à imagem inicial (Matiz/Saturação HSL e depois a tinta). Os campos omitidos permanecem neutros (0). O easing da trilha color os modela.
  • colorFrom (the same fields as color; padrão all neutral) — Os ajustes de cor no keyframe inicial (normalmente deixados como estão).
  • tintColor (color ("#rgb", "#rrggbb[aa]" or { r, g, b, a }); padrão "#ffffff") — A cor para a qual o tingimento mistura (o alfa dela é ignorado).
  • ramp ({ first, last, shift, wrap? }: palette indices first..last (0-255), shift in whole places (-255..255), wrap true by default) — Somente sprites indexed: os pixels cujo índice de paleta está em first..last (o índice transparente excluído) se movem ao longo desse trecho da paleta em shift posições durante o intervalo, voltando ao início ao passar das pontas com wrap e parando nelas caso contrário. Ignorado nos outros modos de cor. O easing da trilha color o modela.
  • path (TweenPath: "straight" | "arc" | "wave" | "zigzag" | "shake" | "custom"; padrão "straight") — O trajeto que a posição segue entre as poses, como um deslocamento em relação à linha reta.
  • points (a list of 2-64 anchors { x, y, inX?, inY?, outX?, outY?, corner? } in sprite pixels relative to the start cel's position; inX/inY and outX/outY are the handles as offsets from the anchor (0 by default)) — trajetória custom: o trajeto desenhado, uma Bézier cúbica pelas âncoras, percorrida em velocidade constante. Obrigatória com path = "custom". A primeira âncora é a posição from e a última a posição end: quando from ou end omitem dx/dy, eles vêm daí, e os informados precisam coincidir.
  • orient (boolean; padrão false) — Gira o desenho para seguir a direção do movimento ao longo da trajetória (somado à rotação; sem giro no início). Usa resample (RotSprite é uma boa escolha).
  • height (number) — Trajeto arc: a altura da curva em pixels. Padrão 8.
  • pathAmplitude (number) — Trajetos wave, zigzag e shake: o deslocamento em pixels. Padrão 4.
  • cycles (number 0–64) — Trajetos wave e zigzag: quantas ondas completas de comprimento. Padrão 1.
  • phase (number -1–1) — Trajeto wave: onde na onda ele começa, em voltas. Padrão 0.
  • seed (integer ≥ 0) — Trajeto shake: o seed aleatório; um mesmo seed sempre treme do mesmo jeito. Padrão 1.
  • fade (TweenFade: "alpha" | "dither"; padrão "alpha") — Como a trilha de opacidade aparece: opacidade parcial ou uma dissolução com dithering de pixels inteiros.
  • ditherPattern (TweenDither: "bayer2" | "bayer4" | "bayer8" | "cluster"; padrão "bayer4") — O padrão pelo qual um fade com dithering se dissolve, fixo na tela para não se arrastar quando o desenho se move. Informá-lo implica fade = "dither".
  • crossfade (boolean; padrão false) — Faz a transição do desenho inicial para o próprio desenho do keyframe final (pelo easing da trilha de opacidade), com dithering ou mesclado conforme fade. O desenho do keyframe final passa a ser uma entrada: editá-lo redesenha o tween.
  • delay (integer 0–4096; padrão 0) — Quadros em que a pose inicial é mantida antes de se mover; depois o movimento preenche o resto do trecho.
  • trackDelay ({ position?, scale?, rotation?, skew?, opacity?, color? }, each a whole number of frames (0-4096)) — Atrasos para trilhas específicas, substituindo delay só nessas trilhas.
  • preset (a preset recipe, as app.tweenPreset returns: { from, end, easing, path, squash, pivotX, pivotY, exposure, shortestRotation, pingPong, trackEasing?, color?, orient?, fade?, delay?, trackDelay? } with distances relative to the start cel's size) — Monta o tween a partir de uma predefinição, ajustada ao cel inicial (distâncias são frações do tamanho dele, atrasos frações do trecho). Junto dela só podem ir to, resample, subpixel, timing, autoRegenerate, fade, ditherPattern, crossfade, delay e orient, que substituem os da predefinição.
  • squash (number 0–1; padrão 0) — Achatamento e alongamento (squash and stretch) baseados na velocidade, preservando o volume.
  • pivotX (number; padrão 0.5) — Ponto fixo de escala, rotação e inclinação, como fração da largura do cel inicial (0.5 = centro).
  • pivotY (number; padrão 0.5) — O mesmo, como fração da altura do cel inicial.
  • pivotSpace (TweenPivotSpace: "cel" | "sprite"; padrão "cel") — Em que estão pivotX e pivotY. "sprite" os torna um ponto em pixels do sprite, o mesmo para cada camada animada com ele.
  • resample (TransformInterpolation: "nearest" | "rotsprite" | "bilinear"; padrão "nearest") — Como os pixels são reamostrados quando escala, rotação ou inclinação mudam. Uma translação pura sempre copia os pixels exatamente.
  • subpixel (TweenSubpixel: "round" | "floor" | "monotonic"; padrão "round") — Como as posições fracionárias caem em pixels inteiros.
  • timing (TweenTiming: "frames" | "time"; padrão "frames") — O que conta como progresso.
  • exposure (integer 1–8; padrão 1) — Desenha uma pose a cada N e a mantém ("on twos" = 2).
  • shortestRotation (boolean; padrão true) — Gira pelo caminho mais curto (a variação ajustada para -180..180) em vez do número exato de graus.
  • pingPong (boolean; padrão false) — Ida e volta: o movimento chega à pose final na metade do trecho e retorna à pose inicial no keyframe final, então um loop que termina onde começou não precisa de um segundo desenho. O easing modela cada metade.
  • autoRegenerate (boolean; padrão true) — Redesenha os intermediários sozinho quando o keyframe inicial ou os quadros mudam.
  • step (integer 0–4096; padrão 0) — Quadros entre o início de uma camada e o da seguinte (0 = todas juntas).
  • order (TweenStaggerOrder: "topDown" | "bottomUp" | "given"; padrão "topDown") — Qual camada começa primeiro.
  • length (TweenStaggerLength: "keep" | "extend"; padrão "keep") — Se as camadas seguintes terminam junto com a primeira (keep) ou mantêm a mesma duração do movimento e terminam depois (extend; os quadros precisam existir).
  • groupPivot (boolean; padrão false) — Escala, gira e inclina todas as camadas em torno de um mesmo ponto: pivotX/pivotY são frações da caixa em volta de todos os cels iniciais, então as camadas se movem rigidamente como um grupo.

Retorna (table): Os ids dos tweens, um por camada, na ordem de layerIds.

app.tweenPreset(id) — pura

Uma predefinição de tween embutida pelo id, ou nil. Passe a recipe dela como opção preset de app.setTween: app.setTween(layerId, frameId, { to = endFrameId, preset = app.tweenPreset("popIn").recipe }).

• id (string) — O id de uma predefinição embutida, p. ex. "popIn" ou "slideInLeft".

Retorna (table): A predefinição, { id, name, description, frames, recipe }: recipe é a receita relativa de tween que a opção preset de app.setTween aceita; nil para um id desconhecido.

app.tweenPresets() — pura

As predefinições de tween embutidas (surgir e sumir, com e sem dithering, brotar, cair, deslizar, entrada em curva, tremer, pulo, squash and stretch, flutuar, balançar, girar, piscar...), na ordem do inspetor de Tween. Suas próprias predefinições ficam no editor do seu dispositivo e não são listadas.

Retorna (table): Uma lista de predefinições, cada uma { id, name, description, frames, recipe }: recipe é a receita relativa de tween que a opção preset de app.setTween aceita.

Em Markdown: frames.md.