# API de scripts Lua do pxstud.io — Images > 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. ### Images O jeito rápido de trabalhar pixel a pixel. app.getImage lê um cel (ou parte dele) em uma Image, um buffer de pixels que vive dentro do script: img:getPixel e img:setPixel nunca saem do script, então um laço sobre todos os pixels de um cel de 512 x 512 leva cerca de um décimo de segundo. app.putImage a grava de volta como uma única alteração, não importa quantos pixels você defina. Um pixel é um inteiro empacotado (app.pixelColor.rgba(r, g, b, a), como no Aseprite); setPixel também aceita "#rrggbb[aa]" e { r, g, b, a } (alfa padrão 255). Em sprites indexados, img:getIndex e img:setIndex trabalham com índices da paleta, então cores duplicadas continuam distintas. O padrão de uso: local img = app.getImage(layer, frame); for y = 0, img.height - 1 do for x = 0, img.width - 1 do img:setPixel(x, y, ...) end end; app.putImage(layer, frame, img). #### `app.getCompositeImage(frameId, rect?)` — lê Como um quadro se parece, como uma Image RGBA: todas as camadas visíveis (de imagem e de tilemap) mescladas com sua opacidade e modo de mesclagem, exatamente como na exportação, sobre rect (padrão: a tela inteira). Camadas de referência são excluídas (não são arte); fora da tela é lido como transparente. Use para conferir seu resultado, ou como fonte para img:drawImage. - `frameId` (string) - `rect` (table, opcional) — A área a ler, { x, y, width, height } na tela (inteiros; width e height de 1 a 4096). Omitido = a tela inteira. - `x` (integer) — Borda esquerda. - `y` (integer) — Borda superior. - `width` (integer 1–4096) — Largura em pixels. - `height` (integer 1–4096) — Altura em pixels. Retorna (image): Uma Image (veja img:getPixel e os outros métodos img:). #### `app.getImage(layerId, frameId, rect?)` — lê Lê o cel de uma camada/quadro em uma Image: um buffer de pixels dentro do script que você lê e altera com img:getPixel / img:setPixel (e img:getIndex / img:setIndex em sprites indexados) sem custo por chamada, e depois grava de volta com app.putImage como uma única alteração. A Image cobre rect (padrão: a tela inteira), e suas coordenadas começam em 0, 0 no canto superior esquerdo do rect; img.x e img.y guardam onde isso fica na tela, que é onde app.putImage a grava por padrão. Pixels sem cel são lidos como transparentes. Um cel vinculado lê sua imagem compartilhada. Somente camadas de imagem (imagens de tiles: app.getTilePixels). - `layerId` (string) - `frameId` (string) - `rect` (table, opcional) — A área a ler, { x, y, width, height } na tela (inteiros; width e height de 1 a 4096). Omitido = a tela inteira. - `x` (integer) — Borda esquerda. - `y` (integer) — Borda superior. - `width` (integer 1–4096) — Largura em pixels. - `height` (integer 1–4096) — Altura em pixels. Retorna (image): Uma Image (veja img:getPixel e os outros métodos img:). #### `app.newImage(width, height, colorMode?)` — lê Uma Image em branco (transparente), em x = 0, y = 0: um buffer de rascunho para montar pixels antes de app.putImage, ou para carimbar em outras imagens com img:drawImage. Uma indexada usa a paleta do sprite. - `width` (number) — 1-4096. - `height` (number) — 1-4096. - `colorMode` (ColorMode: "rgba" | "grayscale" | "indexed", opcional) — Padrão: o do próprio sprite. "rgba" em um sprite indexado dá uma imagem de rascunho em cores plenas (app.putImage então mapeia suas cores para a paleta). Retorna (image): Uma Image (veja img:getPixel e os outros métodos img:). #### `app.pixelColor.rgba(r, g, b, a?)` — pura Empacota uma cor em um inteiro de pixel, a forma que img:getPixel retorna e que img:setPixel recebe mais rápido (como no Aseprite). - `r` (number) — 0-255. - `g` (number) — 0-255. - `b` (number) — 0-255. - `a` (number, opcional) — 0-255, padrão 255. Retorna (number): r | g << 8 | b << 16 | a << 24. #### `app.pixelColor.rgbaA(pixel)` — pura O alfa de um pixel empacotado. - `pixel` (number) — Um pixel empacotado. Retorna (number): 0-255. #### `app.pixelColor.rgbaB(pixel)` — pura O azul de um pixel empacotado. - `pixel` (number) — Um pixel empacotado. Retorna (number): 0-255. #### `app.pixelColor.rgbaG(pixel)` — pura O verde de um pixel empacotado. - `pixel` (number) — Um pixel empacotado. Retorna (number): 0-255. #### `app.pixelColor.rgbaR(pixel)` — pura O vermelho de um pixel empacotado. - `pixel` (number) — Um pixel empacotado. Retorna (number): 0-255. #### `app.putImage(layerId, frameId, image, x?, y?)` — altera, desfazível, recusada em uma camada bloqueada Grava uma Image no cel de uma camada/quadro: todo pixel do retângulo que ela cobre é substituído (sem mesclagem), como uma única alteração, não importa quantos pixels você defina. O cel cresce para comportá-la e é aparado aos seus pixels visíveis; o que cai fora da tela é descartado. Escrita direta: nunca recortada pela seleção nem espelhada. Em um sprite indexado, cada pixel mantém seu índice da paleta (img:setIndex), a menos que a paleta tenha mudado desde então e aquela entrada já não mostre a cor do pixel; em um sprite em tons de cinza, as cores viram cinza. Gravar em um cel vinculado altera todos os quadros aos quais ele está vinculado. - `layerId` (string) - `frameId` (string) - `image` (image) — A Image a gravar. - `x` (number, opcional) — Onde cai o seu pixel superior esquerdo; padrão image.x (onde app.getImage a leu, 0 para app.newImage). - `y` (number, opcional) — Padrão image.y. Não retorna nada. #### `img:clear(x?, y?, width?, height?)` — pura Torna transparente um retângulo da imagem (padrão: toda ela) (o índice transparente em imagens indexadas). - `x` (number, opcional) — Padrão 0. - `y` (number, opcional) — Padrão 0. - `width` (number, opcional) — Padrão: até a borda direita. - `height` (number, opcional) — Padrão: até a borda inferior. Não retorna nada. #### `img:clone()` — pura Uma cópia da imagem (mesmo tamanho, posição e modo de cor). Retorna (image): Uma nova Image. #### `img:drawImage(image, x?, y?, opacity?, blendMode?)` — pura Desenha outra Image sobre esta, mesclada como uma camada (seus pixels transparentes deixam esta como estava). Indexada sobre indexada com opacidade total copia os índices. - `image` (image) — A Image a desenhar. - `x` (number, opcional) — Onde cai o seu canto superior esquerdo; padrão 0. - `y` (number, opcional) — Padrão 0. - `opacity` (number, opcional) — 0-255, padrão 255. - `blendMode` (string, opcional) — Um BlendMode, padrão "normal". Não retorna nada. #### `img:fill(color, x?, y?, width?, height?)` — pura Preenche um retângulo da imagem (padrão: toda ela) com uma cor. - `color` (color) — Um pixel empacotado (app.pixelColor.rgba(r, g, b, a), o que img:getPixel retorna), "#rrggbb[aa]" ou { r, g, b, a } (a tem padrão 255). - `x` (number, opcional) — Padrão 0. - `y` (number, opcional) — Padrão 0. - `width` (number, opcional) — Padrão: até a borda direita. - `height` (number, opcional) — Padrão: até a borda inferior. Não retorna nada. #### `img:getIndex(x, y)` — pura Somente imagens indexadas: o índice da paleta do pixel (a partir de 0, como na ordem de app.getPalette e em app.setPaletteEntry), para que cores duplicadas da paleta possam ser distinguidas. Fora da imagem: o índice transparente. - `x` (number) — Coluna, 0 na borda esquerda da imagem. - `y` (number) — Linha, 0 no topo. Retorna (number): 0-255. #### `img:getPixel(x, y)` — pura A cor de um pixel, empacotada em um inteiro (a forma rápida: nenhuma tabela é criada). Em uma imagem indexada, é a cor da paleta para o índice do pixel (transparente para o índice transparente). Fora da imagem: 0 (transparente). x e y devem ser inteiros. - `x` (number) — Coluna, 0 na borda esquerda da imagem. - `y` (number) — Linha, 0 no topo. Retorna (number): O pixel empacotado r | g << 8 | b << 16 | a << 24: desmonte-o com app.pixelColor (ou & 255, >> 8 ...). #### `img:setIndex(x, y, index)` — pura Somente imagens indexadas: define exatamente o índice da paleta do pixel, mesmo entre duas entradas com a mesma cor (ciclo de paleta, trocas de índice). - `x` (number) — Coluna, 0 na borda esquerda da imagem. - `y` (number) — Linha, 0 no topo. - `index` (number) — Um índice da paleta, a partir de 0. Não retorna nada. #### `img:setPixel(x, y, color)` — pura Define a cor de um pixel. Aceita as mesmas cores dos comandos de desenho, mais pixels empacotados, e recusa qualquer outra coisa ({ red = ... }, uma lista, uma string hex inválida) com um erro. Em uma imagem indexada, a cor vira a entrada da paleta mais próxima, mantendo o índice do pixel quando essa entrada já mostra a cor (img:setIndex escolhe um índice exato); em uma em tons de cinza, vira cinza. Fora da imagem, nada acontece. - `x` (number) — Coluna, 0 na borda esquerda da imagem. - `y` (number) — Linha, 0 no topo. - `color` (color) — Um pixel empacotado (app.pixelColor.rgba(r, g, b, a), o que img:getPixel retorna), "#rrggbb[aa]" ou { r, g, b, a } (a tem padrão 255). Não retorna nada.