# API de scripts Lua do pxstud.io — Paleta > 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. ### Paleta A paleta do sprite. #### `app.addColorCycle(fromIndex, toIndex, opts?)` — altera, desfazível Adiciona um intervalo de ciclo de cores (sprites indexados): durante a reprodução, as cores desse intervalo da paleta giram. Os pixels não mudam; use app.bakeColorCycles para transformar o ciclo em paletas por quadro. - `fromIndex` (number) — Primeiro índice da paleta do intervalo em ciclo. - `toIndex` (number) — Último índice da paleta do intervalo (inclusivo). - `opts` (table, opcional) - `direction` (string; padrão "forward") — "forward" move cada cor para o próximo índice maior, "reverse" para o menor. - `framesPerStep` (integer 1–1000; padrão 1) — Quadros de reprodução por rotação de um passo. Retorna (string): O id do novo ciclo. #### `app.bakeColorCycles(frames?)` — altera, desfazível Grava os ciclos de cores em paletas por quadro (adicionando quadros se necessário) para que exportações como GIF reproduzam o ciclo, e depois remove os ciclos. Somente sprites indexados. - `frames` (number, opcional) — Total de quadros da animação gravada (no mínimo a contagem atual); padrão: um laço completo dos ciclos. Os quadros são acrescentados depois do último. Não retorna nada. #### `app.cleanPalette(opts?)` — altera, desfazível Limpa a paleta: mescla cores duplicadas e semelhantes na primeira ocorrência e remove entradas não usadas. Em sprites indexados, os pixels acompanham suas cores. - `opts` (table, opcional) — { removeDuplicates = bool, removeUnused = bool, mergeDistance = 0-100 (delta E; ~2 mal é visível, 10 claramente diferente), frameId = paleta em vigor naquele quadro }. Toda opção vem desativada por padrão. Não retorna nada. #### `app.createPaletteChange(frameId, colors?)` — altera, desfazível Inicia uma nova paleta em um quadro: esse quadro e os seguintes (até a próxima mudança) resolvem os pixels indexados por ela. Os índices dos pixels não mudam. - `frameId` (string) — Quadro em que a nova paleta começa (não o primeiro quadro). - `colors` (table, opcional) — A paleta a partir desse quadro, um array de cores hex; padrão: uma cópia da paleta em vigor ali. Não retorna nada. #### `app.createPaletteRamp(from, to, count?, space?, mode?, frameId?)` — altera, desfazível Gera uma rampa de cores entre duas entradas da paleta (o Gradiente da paleta do Aseprite): por padrão sobrescreve as entradas entre elas, ou, com o modo "insert", insere novas cores antes da entrada posterior. Em sprites indexados, uma inserção desloca os índices dos pixels para que a imagem não mude. Uma única etapa desfazível. - `from` (number) — Índice da paleta de uma extremidade da rampa (a partir de 0). - `to` (number) — Índice da paleta da outra extremidade (a partir de 0). - `count` (number, opcional) — Quantas cores inserir entre elas (1-256). Obrigatório para o modo "insert"; "replace" preenche todas as entradas entre as extremidades e o ignora. - `space` (string, opcional) — Espaço de interpolação: "oklab" (padrão, perceptualmente uniforme), "oklch", "rgb" ou "hsl". - `mode` (string, opcional) — "replace" sobrescreve as entradas entre as duas extremidades com a rampa (o Gradiente da paleta do Aseprite; os pixels não são tocados); "insert" adiciona `count` novas cores antes da extremidade posterior. Padrão: "replace" quando há entradas entre as extremidades, caso contrário "insert". - `frameId` (string, opcional) — Edita a paleta em vigor neste quadro (as paletas podem mudar por quadro); padrão: a paleta do primeiro quadro. Em sprites indexados, "insert" só desloca os pixels dos quadros que compartilham essa paleta. Não retorna nada. #### `app.getColorCycles()` — lê Os intervalos de ciclo de cores de um sprite indexado: { id, fromIndex, toIndex, direction, framesPerStep } cada um. Retorna (table): Array de tabelas de ciclo de cores. #### `app.getPalette(frameId?)` — lê A paleta como um array de strings de cor hex, "#rrggbb" ou, para entradas com alfa abaixo de 255, "#rrggbbaa", p. ex. { "#ff0000", "#00ff0080", ... }. Passe um id de quadro para obter a paleta desse quadro. - `frameId` (string, opcional) — Quadro cuja paleta será lida (as paletas podem mudar por quadro); omita para a paleta do primeiro quadro. Retorna (table): Array de strings de cor hex. #### `app.insertPaletteEntries(index, colors, frameId?)` — altera, desfazível Insere entradas de paleta em um índice. Em sprites indexados, todo pixel (e o índice transparente) acompanha sua entrada, então a imagem não muda. - `index` (number) — Onde vai a primeira nova entrada (a partir de 0; o comprimento da paleta acrescenta ao final). - `colors` (table) — Array de strings de cor hex, "#rrggbb" ou "#rrggbbaa", p. ex. { "#ff0000", "#00ff0080" }. - `frameId` (string, opcional) — Edita a paleta em vigor neste quadro (as paletas podem mudar por quadro); padrão: a paleta do primeiro quadro. Não retorna nada. #### `app.movePaletteEntry(fromIndex, toIndex, frameId?)` — altera, desfazível Move uma entrada da paleta para uma nova posição. Em sprites indexados, todo pixel acompanha sua cor, então a imagem não muda. - `fromIndex` (number) — Índice atual na paleta (a partir de 0). - `toIndex` (number) — Índice em que a entrada deve ficar (a partir de 0). - `frameId` (string, opcional) — Edita a paleta em vigor neste quadro (as paletas podem mudar por quadro); padrão: a paleta do primeiro quadro. Não retorna nada. #### `app.remapColors(mappings, cels)` — altera, desfazível, recusada em uma camada bloqueada Substitui cores exatas por outras cores em um conjunto de cels: o remapeamento da Auditoria de paleta. Sprites RGBA e em tons de cinza. - `mappings` (table) — Array de { from = "#rrggbb", to = "#rrggbb" } (qualquer um pode ter alfa, "#rrggbbaa"); todos os mapeamentos são aplicados de uma vez. - `cels` (table) — Array de { layerId = ..., frameId = ... }: os cels a recolorir (camadas de imagem). Não retorna nada. #### `app.removeColorCycle(cycleId)` — altera, desfazível Remove um ciclo de cores. - `cycleId` (string) Não retorna nada. #### `app.removePaletteChange(frameId)` — altera, desfazível Remove a mudança de paleta em um quadro, que volta a usar a paleta anterior a ele. Os índices dos pixels não mudam. - `frameId` (string) — Quadro cuja mudança de paleta será removida. Não retorna nada. #### `app.removePaletteEntries(indices, frameId?)` — altera, desfazível Remove entradas da paleta por índice. Em sprites indexados, os pixels das entradas removidas ficam transparentes e todos os outros pixels (e o índice transparente) acompanham sua entrada. - `indices` (table) — Array dos índices da paleta a remover (a partir de 0), p. ex. { 3 } ou { 4, 5, 6 }. - `frameId` (string, opcional) — Edita a paleta em vigor neste quadro (as paletas podem mudar por quadro); padrão: a paleta do primeiro quadro. Não retorna nada. #### `app.setColorDepth(depth?)` — altera, desfazível Fixa o sprite em uma profundidade de cor, como um console que só consegue mostrar certos valores: pixels, tiles e paletas se ajustam a ela agora (uma única etapa de desfazer), e tudo o que for desenhado depois fica nela. nil a remove (a precisão perdida não volta). Leia-a com app.getSprite().colorDepth. - `depth` (table, opcional) — A profundidade de cor em níveis por canal, ou nil para removê-la. n bits são 2^n níveis (3 bits = 8). - `red` (integer 2–256) — Níveis de vermelho (com green e blue). - `green` (integer 2–256) — Níveis de verde. - `blue` (integer 2–256) — Níveis de azul. - `gray` (integer 2–256) — Níveis de cinza, em vez de vermelho, verde e azul: cada cor vira um cinza. - `profile` (string) — O id do perfil de hardware que ela representa (por exemplo, "mega-drive"), mostrado no editor. Não retorna nada. #### `app.setPalette(colors, frameId?)` — altera, desfazível Substitui a paleta inteira do sprite, posição por posição. Em sprites indexados, todo pixel mantém seu índice e mostra a nova cor nele (uma paleta mais curta é completada com as cores antigas das posições ainda em uso). Para adicionar ou remover cores com os pixels acompanhando, use app.insertPaletteEntries / app.removePaletteEntries. - `colors` (table) — Array de strings de cor hex, "#rrggbb" ou "#rrggbbaa" (alfa), p. ex. { "#ff0000", "#00ff0080" }. - `frameId` (string, opcional) — Edita a paleta em vigor neste quadro (as paletas podem mudar por quadro); padrão: a paleta do primeiro quadro. Não retorna nada. #### `app.setPaletteEntry(index, color, frameId?)` — altera, desfazível Recolore uma entrada da paleta no lugar. Em sprites indexados, todo pixel que usa essa entrada mostra a nova cor. - `index` (number) — Entrada da paleta a recolorir (a partir de 0). - `color` (string) — Cor hex, "#rrggbb" (opaca) ou "#rrggbbaa" (com alfa), p. ex. "#ff0000" ou "#ff000080". - `frameId` (string, opcional) — Edita a paleta em vigor neste quadro (as paletas podem mudar por quadro); padrão: a paleta do primeiro quadro. Não retorna nada. #### `app.setPaletteGroups(groups)` — altera, desfazível Substitui os grupos da paleta: rótulos nomeados sobre intervalos de índices da paleta. Eles rotulam posições, então mover ou ordenar cores não move um grupo. - `groups` (table) — Array de { name = "Skin", from = 0, to = 3 } (índices da paleta a partir de 0, inclusivos), ordenado por from e sem sobreposição. {} remove todos os grupos. Não retorna nada. #### `app.setPaletteLock(locked)` — altera, desfazível Ativa ou desativa a Trava de paleta. Somente sprites RGBA (sprites indexados sempre pintam com cores da paleta); salva com o arquivo. - `locked` (boolean) — true: todo comando de desenho em um sprite RGBA ajusta os pixels que pinta à cor da paleta mais próxima. Não retorna nada. #### `app.setTransparentIndex(index)` — altera, desfazível Define o índice da cor transparente do sprite indexado (Propriedades do sprite > Cor transparente do Aseprite). Só a propriedade muda, não os bytes dos pixels. - `index` (number) — Índice da paleta (0-255) cujos pixels são transparentes em sprites indexados (padrão 0). Não retorna nada. #### `app.sortPalette(by, descending?, from?, to?, frameId?)` — altera, desfazível Ordena a paleta (ou o intervalo from..to) por uma propriedade de cor, na ordem da classificação de paleta do Aseprite: entradas totalmente transparentes primeiro em qualquer direção; hue põe os cinzas primeiro (por valor) em ordem crescente e por último em ordem decrescente; hue, saturation e brightness comparam graus e porcentagens inteiros (saturation desempata por brightness e vice-versa); luminance pondera os canais ao quadrado. Os demais empates mantêm sua ordem. Em sprites indexados, todo pixel acompanha sua cor, então a imagem não muda. - `by` (string) — Chave de ordenação: "hue", "saturation", "brightness", "luminance", "red", "green", "blue" ou "alpha". - `descending` (boolean, opcional) — Ordena do maior para o menor (padrão false). - `from` (number, opcional) — Primeiro índice da paleta a ordenar (a partir de 0, padrão 0). - `to` (number, opcional) — Último índice da paleta a ordenar (inclusivo, padrão: o último). - `frameId` (string, opcional) — Edita a paleta em vigor neste quadro (as paletas podem mudar por quadro); padrão: a paleta do primeiro quadro. Não retorna nada. #### `app.updateColorCycle(cycleId, props?)` — altera, desfazível Altera o intervalo, a direção ou a velocidade de um ciclo de cores. - `cycleId` (string) - `props` (table, opcional) - `fromIndex` (integer 0–255) — Primeiro índice da paleta do intervalo. - `toIndex` (integer 0–255) — Último índice da paleta do intervalo (inclusivo). - `direction` (string) — "forward" ou "reverse". - `framesPerStep` (integer 1–1000) — Quadros de reprodução por rotação de um passo. Não retorna nada.