# API de scripts Lua do pxstud.io — Camadas > Parte da referência de scripts Lua do pxstud.io, cuja visão geral (https://pxstud.io/pt-br/docs/scripting.md) explica as convenções. Os grupos de opções e os tipos a que ela remete estão em https://pxstud.io/pt-br/docs/scripting/option-groups.md e https://pxstud.io/pt-br/docs/scripting/types.md. Tudo em um único arquivo (em inglês): https://pxstud.io/llms-full.txt. O índice de todo o site (em inglês): https://pxstud.io/llms.txt. ### Camadas Crie, organize e configure camadas. Grupos são pastas de camadas: o parentId de uma camada nomeia o grupo dela (nil no nível superior) e as posições de app.moveLayer contam dentro de um grupo (0 = base). Ocultar ou bloquear um grupo oculta ou bloqueia tudo o que está dentro dele. Um grupo com opacidade total e modo de mesclagem "normal" é pass-through (as camadas dele se mesclam direto no que está abaixo), a menos que a flag isolated esteja definida; um grupo isolado, ou com qualquer outra opacidade ou modo, compõe primeiro as camadas dele entre si. #### `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.