Camadas

app.addAdjustmentLayer(name?, effects?, parentId?) — altera, desfazível

Adiciona uma camada de ajuste acima de todas as outras camadas (ou dentro do grupo parentId): ela não contém pixels, e seus efeitos alteram tudo o que está composto abaixo dela no grupo (ou na imagem inteira), em todos os quadros, com a opacidade da camada. Recorte-a para alterar apenas a camada abaixo. Torna-a ativa.

• name (string, opcional) — O padrão é "Adjustment N".
• effects (table, opcional) — Seus efeitos, como em app.setLayerEffects (apenas os tipos de cor e por pixel). Omitido = nenhum ainda.
• parentId (string, opcional) — Um grupo ao qual adicioná-la (acima das camadas dele); omitido = o nível superior.

Retorna (string): O id da nova camada.

app.addGroup(name?, parentId?) — altera, desfazível

Adiciona um novo grupo de camadas vazio acima de todas as outras camadas (ou dentro do grupo parentId) e o torna ativo. Coloque camadas nele com app.moveLayer ou app.groupLayers.

• name (string, opcional) — O padrão é "Group N".
• parentId (string, opcional) — Um grupo no qual aninhá-lo (acima das camadas dele); omitido = o nível superior.

Retorna (string): O id do novo grupo.

app.addLayer(name?, parentId?) — altera, desfazível

Adiciona uma nova camada em branco acima de todas as outras camadas (ou acima das camadas do grupo parentId) e a torna ativa.

• name (string, opcional) — O padrão é "Layer N".
• parentId (string, opcional) — Um grupo ao qual adicioná-la (acima das camadas dele); omitido = o nível superior.

Retorna (string): O id da nova camada.

app.backgroundFromLayer(layerId?, backgroundColor?) — altera, desfazível, recusada em uma camada bloqueada

Camada > "Plano de fundo a partir da camada": converte uma camada de imagem na camada Plano de fundo do sprite: movida para a base, chamada "Background" e totalmente opaca (os pixels transparentes recebem a cor de fundo). Gera um erro se o sprite já tiver uma camada Plano de fundo.

• layerId (string, opcional) — A camada de imagem a converter; omitido = a camada de imagem mais baixa.
• backgroundColor (color, opcional) — O que preenche os pixels transparentes. O padrão é a cor de fundo atual.

Retorna (string): O id da camada convertida.

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

Renderiza os efeitos ativados de uma camada de imagem em todos os cels dela e os remove, em um único passo de desfazer. Os cels crescem para comportar sombras e contornos (cortados na tela); em sprites indexed, o resultado se ajusta à paleta de cada quadro. Gera um erro em uma camada bloqueada ou sem efeitos.

• layerId (string)

Não retorna nada.

app.duplicateLayer(layerId) — altera, desfazível

Clona uma camada (um grupo com tudo o que está dentro dele) e todos os cels pintados nela, inserindo a cópia diretamente acima do original e tornando-a ativa.

• layerId (string)

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

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

Substitui um grupo e tudo o que há nele por uma camada de imagem (mesmo id, nome, opacidade, modo de mesclagem e lugar) com as camadas dele compostas entre si em cada quadro. As camadas ocultas, de rascunho e de referência dentro dele são excluídas, como em Achatar.

• layerId (string) — O grupo a achatar.

Não retorna nada.

app.flattenSprite(visibleOnly?, backgroundColor?) — altera, desfazível

Camada > Achatar: reúne todas as camadas de nível superior (inclusive as ocultas) em uma só camada, por quadro, exatamente como é renderizado com elas exibidas; com visibleOnly, apenas as visíveis, mantendo as ocultas. Uma camada Plano de fundo visível continua sendo o Plano de fundo (totalmente opaco); caso contrário, o resultado é uma nova camada chamada Flattened. Gera um erro se não houver nada a achatar.

• visibleOnly (boolean, opcional) — Achatar visíveis: achata apenas as camadas visíveis de nível superior e mantém as ocultas. O padrão é false: tudo, inclusive as camadas ocultas.
• backgroundColor (color, opcional) — Somente quando o resultado é a camada Plano de fundo (um Plano de fundo visível é achatado): o que preenche os pixels que nada cobre. O padrão é a cor de fundo atual.

Não retorna nada.

app.getActiveLayerId() — lê

O id da camada ativa no momento, ou nil se não houver.

Retorna (string): Id da camada ou nil.

app.getLayer(layerId) — lê

Uma camada, no mesmo formato de uma entrada de app.getLayers, ou nil se não existir essa camada.

• layerId (string)

Retorna (table): Tabela da camada ou nil.

app.getLayers() — lê

Todas as camadas, da base ao topo (um grupo fica logo acima de suas camadas), como { id, name, type ("image" | "tilemap" | "reference" | "group"), parentId (o grupo em que está; nil no nível superior), depth (0 = nível superior), index (0 = base da pilha inteira), position (posição entre as camadas do pai, 0 = base; o que app.moveLayer recebe), opacity (0-1), visible, locked, movementLocked, background (true na camada Plano de fundo), clipped (uma máscara de recorte: aparece apenas onde a camada não recortada mais próxima abaixo dela tem pixels), continuous (app.duplicateFrame vincula os cels dela em vez de copiá-los), blendMode, collapsed (grupos), tileset = { tileWidth, tileHeight, tileCount, matchFlipH, matchFlipV, matchRotate } (camadas de tilemap), reference = { width, height } (camadas de referência) }. visible/locked/movementLocked são as flags da própria camada; um grupo oculto, bloqueado ou com movimento bloqueado também oculta, bloqueia ou fixa tudo o que está dentro dele.

Retorna (table): Array de tabelas de camada.

app.getReferenceTransform(layerId, frameId) — lê

Onde a imagem de uma camada de referência fica em um quadro, como { x, y, width, height } em pixels do sprite, ou nil se estiver em branco ali.

• layerId (string) — Uma camada de referência.
• frameId (string)

Retorna (table): Tabela de transformação ou nil.

app.groupLayers(layerIds, name?) — altera, desfazível

Coloca camadas (grupos com tudo o que está dentro deles) em um novo grupo na posição da mais alta, mantendo a ordem delas, e torna o grupo ativo.

• layerIds (table) — Array de ids de camada, todas no mesmo grupo (ou todas no nível superior).
• name (string, opcional) — O padrão é "Group N".

Retorna (string): O id do novo grupo.

app.layerFromBackground() — altera, desfazível

Camada > "Camada a partir do plano de fundo": transforma a camada Plano de fundo em uma camada comum (transparência e movimento voltam a ser permitidos). Gera um erro se o sprite não tiver camada Plano de fundo.

Retorna (string): O id da camada convertida.

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

Compõe uma camada (ou um grupo inteiro, como é renderizado) sobre a camada diretamente abaixo dela no mesmo grupo e depois a exclui; uma base de recorte leva consigo as camadas recortadas dela. O resultado tem a mesma aparência, e a camada de baixo fica com opacidade de 100% e o modo de mesclagem normal. Gera um erro se não houver nada abaixo dela no grupo, se o que está abaixo não for uma camada de imagem ou se uma camada não recortada fosse mesclada sobre uma recortada.

• layerId (string)

Não retorna nada.

app.mergeLayers(layerIds) — altera, desfazível, recusada em uma camada bloqueada

Mescla camadas (grupos com tudo o que está dentro deles) em uma só camada de imagem exatamente como são renderizadas juntas, na posição da mais alta e com o nome dela, e a torna ativa. Com o Plano de fundo entre elas, o resultado é o Plano de fundo.

• layerIds (table) — Array de dois ou mais ids de camada, todas no mesmo grupo (ou todas no nível superior). As ocultas também são mescladas.

Retorna (string): O id da camada mesclada.

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

Mescla uma camada de imagem na camada diretamente acima dela no mesmo grupo: o resultado tem exatamente a aparência de Mesclar para baixo dessa camada, mas leva o nome e a tag de cor dela. Gera um erro se não houver nada acima dela no grupo ou se ela não for uma camada de imagem.

• layerId (string)

Não retorna nada.

app.moveLayer(layerId, position, parentId?) — altera, desfazível

Move uma camada (um grupo com tudo o que está dentro dele) para uma nova posição, opcionalmente para dentro de outro grupo. Gera um erro ao mover um grupo para dentro de si mesmo.

• layerId (string)
• position (number) — Sua posição depois entre as outras camadas do pai (0 = base), limitada ao intervalo válido.
• parentId (string, opcional) — O grupo para o qual movê-la; "" = o nível superior; omitido = continuar no grupo atual.

Não retorna nada.

app.removeLayer(layerId) — altera, desfazível

Remove uma camada e todos os cels pintados nela; remover um grupo remove tudo o que está dentro dele. Gera um erro se não sobrasse nenhuma camada (que não seja grupo).

• layerId (string)

Não retorna nada.

app.setActiveLayer(layerId) — altera

Torna uma camada a ativa (o que clicar nela no painel de camadas faz). Não é uma edição que possa ser desfeita.

• layerId (string)

Não retorna nada.

app.setLayerEffects(layerId, effects) — altera, desfazível

Define os efeitos não destrutivos de uma camada: as operações rodam sobre os pixels da camada (os filhos compostos de um grupo) toda vez que o sprite é composto, em ordem, e nunca são gravadas nos cels (app.bakeLayerEffects faz isso). Permitido em uma camada bloqueada. Não vale para camadas de referência; a camada Plano de fundo aceita apenas efeitos de cor.

• layerId (string)
• effects (table) — A lista completa de efeitos da camada, o primeiro embaixo ({} a limpa). Cada entrada é { kind = "levels", ...os campos desse efeito, enabled = true }; leia a lista atual em app.getLayers, altere-a e passe-a de volta (as entradas mantêm o id). Tipos: brightnessContrast, hueSaturation, colorCurve, levels, threshold, gradientMap, colorBalance, invert, replaceColor, posterize recebem os campos do ajuste app.* correspondente; outline recebe place, width, shape, color; shadow recebe place, dx, dy, spread, shape, softness (0-8 px de borda suave), edge ("dithered", "hard" ou "smooth": como uma borda suave é desenhada), color; noise (amount, size, mono, seed), dither (pattern, levels, strength), scanlines (period, thickness, offset, strength, mask), vignette (strength, radius, softness, color), paletteSwap (from, to, tolerance), blur (radius, shape, edge, colors), bloom (threshold, radius, intensity, edge, colors), edgeDetect (strength, mode, invert, color), smoother (size), pixelate (size), chromatic (dx, dy), wave (axis, amplitude, wavelength, phase), bend (axis, amount), distortion (axis, band, amount, density, seed), parallax (shift), echo (count, dx, dy, fade), antiAlias (a, anyA, b, steps, into, strength, colors: como em app.antiAlias), autoShade (target, base, angle, highlights, shadows, width, hueShift, chroma, rim, outline, colors, ramp: como em app.autoShade). Blur e bloom podem se ajustar para pixel art: edge é "smooth", "hard" ou "dithered", colors é "any" ou "palette" (a paleta do quadro, o padrão em sprites indexados). Anime um parâmetro numérico ou de cor com tracks = { dx = { { frame = frameId, value = 0 }, { frame = otherFrameId, value = 4, easing = ... } } } (o caminho é o campo, ou value.gamma, shadows.red e assim por diante; um easing ausente é linear) e timing = "frames" ou "time". Toda cor (color, below, above, from, to, o color de uma parada de gradiente, a, b, base, o value de um keyframe de cor) é "#rgb", "#rrggbb", "#rrggbbaa" ou { r, g, b, a } (a vale 255 por padrão); as listas de cores (from e to de paletteSwap, ramp de autoShade) também aceitam essas formas, ignorando o alfa. As leituras (app.getLayers) retornam as cores como tabelas { r, g, b, a } e as listas de cores como strings "#rrggbb".

Não retorna nada.

app.setLayerProps(layerId, props) — altera, desfazível

Atualiza uma ou mais propriedades de uma camada ou grupo.

• layerId (string)
• props (table) — As chaves omitidas permanecem inalteradas.
  • name (string) — O nome da camada.
  • opacity (number 0–1) — Opacidade da camada. Um grupo abaixo de 1 compõe primeiro as camadas dele entre si (fica isolado).
  • visible (boolean) — Se a camada é exibida (e, para scripts, exportada). Um grupo oculto oculta tudo o que está dentro dele.
  • locked (boolean) — O conteúdo de uma camada bloqueada não pode ser alterado por nada, scripts inclusive. Bloquear um grupo bloqueia tudo o que está dentro dele.
  • movementLocked (boolean) — Os cels de uma camada com movimento bloqueado não podem ser movidos (movePixels, moveCels, um deslocamento de transformPixels, posicionamento de referência); pintar continua funcionando. Bloquear o movimento de um grupo bloqueia tudo o que está dentro dele.
  • clipped (boolean) — Máscara de recorte: a camada só aparece onde a camada não recortada mais próxima abaixo dela no mesmo grupo (a base) tem pixels, e o modo de mesclagem da base se aplica à pilha inteira. Não vale para camadas de referência nem para a camada Plano de fundo.
  • draft (boolean) — Camada de rascunho: aparece enquanto você trabalha, mas nunca é exportada, achatada nem carimbada (um grupo de rascunho leva junto tudo o que está dentro dele). Não vale para camadas de referência nem para a camada Plano de fundo.
  • continuous (boolean) — Camada contínua (a do Aseprite): Novo quadro (app.duplicateFrame sem linked) vincula o cel desta camada ao do original em vez de copiá-lo. Não vale para grupos.
  • isolated (boolean) — Somente grupos: compõe primeiro as camadas do grupo isoladamente e depois mescla o resultado como uma só imagem (o grupo Normal do Photoshop). Desativado, um grupo com mesclagem normal e opacidade 1 é pass-through: as camadas dele se mesclam direto no que está abaixo. Qualquer outro modo de mesclagem ou opacidade isola o grupo de qualquer forma.
  • blendMode (BlendMode: "normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity" | "addition" | "subtract" | "divide") — Como a camada se mescla com as de baixo. Um grupo com um modo diferente de "normal" compõe primeiro as camadas dele entre si (fica isolado).

Não retorna nada.

app.setReferenceTransform(layerId, frameId, x, y, width, height) — altera, desfazível, recusada em uma camada bloqueada

Reposiciona/redimensiona o posicionamento de uma camada de referência em um quadro (no espaço do sprite). Uma largura ou altura <= 0 a limpa (em branco naquele quadro). Gera um erro se layerId não for uma camada de referência.

• layerId (string)
• frameId (string)
• x (number)
• y (number)
• width (number)
• height (number)

Não retorna nada.

app.stampVisible(name?) — altera, desfazível

Adiciona uma nova camada com tudo o que está visível, por quadro, exatamente como Achatar a faria (camadas de referência e de rascunho ficam de fora), mas mantendo todas as camadas, acima do bloco de nível superior da camada ativa, e a torna ativa.

• name (string, opcional) — O padrão é "Visible".

Retorna (string): O id da nova camada.

app.ungroupLayer(layerId) — altera, desfazível

Remove um grupo, movendo as camadas dele para cima, para o lugar dele. As propriedades próprias delas são mantidas; a opacidade, o modo de mesclagem e a visibilidade do grupo são descartados, não incorporados.

• layerId (string) — Um grupo.

Não retorna nada.

Em Markdown: layers.md.