# API de scripts Lua do pxstud.io — Tilemaps > 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. ### Tilemaps As camadas de tilemap colocam em uma grade tiles do seu próprio tileset. Os tiles são numerados a partir de 1 (0 é o tile vazio). #### `app.addTilemapLayer(name?, tileWidth, tileHeight, parentId?, tilesetLayerId?)` — altera, desfazível Cria uma nova camada de tilemap com um tileset vazio de tiles de tileWidth x tileHeight acima de todas as outras camadas (ou das camadas do grupo parentId) e a torna ativa. Use app.addTilemapTile para adicionar tiles a ela. Com tilesetLayerId, a camada compartilha o tileset daquela camada: editar, adicionar ou remover tiles afeta ambas. - `name` (string, opcional) — Nome da camada; o padrão é 'Tilemap N'. - `tileWidth` (number) - `tileHeight` (number) - `parentId` (string, opcional) — Um grupo ao qual adicioná-la (acima das camadas dele); omitido = o nível superior. - `tilesetLayerId` (string, opcional) — Compartilha o tileset desta camada de tilemap existente em vez de criar um novo (tileWidth e tileHeight são então ignorados). Retorna (string): O id da nova camada de tilemap. #### `app.addTilemapTile(layerId, pixels?)` — altera, desfazível Acrescenta um tile ao tileset de uma camada de tilemap e retorna o índice dele (começando em 1; 0 é o tile vazio implícito). Gera erro se layerId não for uma camada de tilemap. - `layerId` (string) - `pixels` (table, opcional) — Buffer plano de pixels (RGBA = 4 números por pixel, indexado = 1) do tamanho do tile; omita para um tile transparente. Retorna (number): O índice do novo tile, começando em 1. #### `app.clearTilemapTile(layerId, tileIndex)` — altera, desfazível, recusada em uma camada bloqueada Torna um tile totalmente transparente. Todas as posições dele ficam em branco. - `layerId` (string) - `tileIndex` (number) — Índice do tile, começando em 1. Não retorna nada. #### `app.convertToNormalLayer(layerId)` — altera, desfazível, recusada em uma camada bloqueada Converte uma camada de tilemap em uma camada de imagem, rasterizando as posições dos tiles em um cel em cada quadro (Camada > Converter em camada normal). A camada mantém seu id. Uma única etapa de desfazer. - `layerId` (string) — Uma camada de tilemap. Não retorna nada. #### `app.convertToTilemap(layerId, tileWidth, tileHeight, opts?)` — altera, desfazível, recusada em uma camada bloqueada Converte uma camada de imagem em uma camada de tilemap com um novo tileset de tiles de tileWidth x tileHeight recortados dos cels dela em cada quadro (Camada > Converter em tilemap). A camada mantém seu id; seus cels viram posições de tiles. Uma única etapa de desfazer. - `layerId` (string) — Uma camada de imagem (não o plano de fundo). - `tileWidth` (number) - `tileHeight` (number) - `opts` (table, opcional) - `dedupe` (boolean; padrão true) — Compartilha tiles idênticos. - `matchFlips` (boolean; padrão false) — Também compartilha tiles que coincidem invertidos ou girados 90 graus (e ativa as opções de correspondência do tileset). Não retorna nada. #### `app.duplicateTilemapTile(layerId, tileIndex)` — altera, desfazível Acrescenta uma cópia de um tile ao fim do tileset de uma camada de tilemap (o índice dela é a contagem antiga de tiles + 1). - `layerId` (string) - `tileIndex` (number) — Índice, começando em 1, do tile a copiar. Retorna (number): O índice da cópia, começando em 1. #### `app.fillTiles(layerId, frameId, col, row, opts?)` — altera, desfazível, recusada em uma camada bloqueada Balde de tiles: preenche com um tile as células que contêm o mesmo tile que a célula (col, row) (uma célula vazia é o tile 0) — exatamente o balde da interface no modo Colocar tiles. O preenchimento fica dentro da grade de tiles da tela. - `layerId` (string) — Uma camada de tilemap. - `frameId` (string) - `col` (number) — A coluna da grade de tiles clicada (não um pixel do sprite). - `row` (number) — A linha da grade de tiles clicada. - `opts` (table, opcional) Também aceita **Opções de posicionamento** (veja "Grupos de opções"), e ainda: - `contiguous` (boolean; padrão context.bucketFillMode (true para o modo contíguo do contexto, false para o global)) — Apenas as células conectadas (true), ou toda célula que contém o tile da célula clicada (false). - `tileIndex` (integer ≥ 1; padrão context.tileIndex) — O tile, começando em 1, com que preencher. - `flipH` (boolean; padrão context.tileFlipH) — Inverte horizontalmente os tiles colocados. - `flipV` (boolean; padrão context.tileFlipV) — Inverte verticalmente os tiles colocados. - `rotate90` (boolean; padrão context.tileRotate90) — Gira os tiles colocados em 90° no sentido horário (apenas tiles quadrados). Não retorna nada. #### `app.getTilemap(layerId, frameId)` — lê As posições dos tiles de uma camada de tilemap em um quadro como { x, y (célula da grade de tiles), tileIndex, flipH, flipV, rotate90 } — o formato que app.setTilemapInstances recebe. Quadros vinculados informam as posições que compartilham. - `layerId` (string) — Uma camada de tilemap. - `frameId` (string) Retorna (table): Array de tabelas de posição. #### `app.getTilePixels(layerId, tileIndex)` — lê A imagem de um tile como uma lista RGBA plana (tileWidth*tileHeight*4, por linhas; cores da paleta resolvidas em sprites indexados). - `layerId` (string) — Uma camada de tilemap. - `tileIndex` (number) — Tile, começando em 1. Retorna (table): Lista RGBA plana. #### `app.getTileset(layerId)` — lê O tileset de uma camada de tilemap como { tileWidth, tileHeight, tileCount, matchFlipH, matchFlipV, matchRotate, baseIndex, name?, id? } (as flags de correspondência são as opções de Pintura automática, veja app.setTilesetMatch; baseIndex é o número com que o primeiro tile é exibido, veja app.setTilesetProperties; id existe quando camadas compartilham o tileset, e ids iguais significam o mesmo tileset). Os tiles são numerados de 1..tileCount (0 = o tile vazio). - `layerId` (string) — Uma camada de tilemap. Retorna (table): Tabela do tileset. #### `app.importTilesFromImage(layerId, width, height, pixels, opts?)` — altera, desfazível, recusada em uma camada bloqueada Fatia uma imagem no tileset da camada em células de tileWidth x tileHeight (as células das bordas são completadas com transparência), acrescentando os tiles que ainda não existem. Com frameId, também coloca o resultado nesse quadro. Uma única etapa de desfazer. - `layerId` (string) — Uma camada de tilemap. - `width` (number) — Largura da imagem em pixels. - `height` (number) — Altura da imagem em pixels. - `pixels` (table) — Números RGBA planos (4 por pixel, width*height pixels). - `opts` (table, opcional) - `dedupe` (boolean; padrão true) — Reutiliza tiles idênticos em vez de adicionar duplicatas. - `matchFlips` (boolean; padrão false) — Com dedupe: também reutiliza um tile que coincide invertido horizontal/verticalmente ou girado 90 graus (tiles quadrados), colocando-o com as flags correspondentes. - `skipEmpty` (boolean; padrão true) — Células sem nenhum pixel visível não geram tile. - `frameId` (string) — Também coloca as células fatiadas neste quadro da camada, substituindo as células que a imagem cobre. - `col` (integer; padrão 0) — Coluna de tiles da borda esquerda da imagem ao colocar. - `row` (integer; padrão 0) — Linha de tiles da borda superior da imagem ao colocar. Retorna (number): Quantos tiles foram adicionados. #### `app.moveTilemapTile(layerId, from, to)` — altera, desfazível Move um tile para uma nova posição no tileset, remapeando todas as posições para que nada mude visualmente. - `layerId` (string) - `from` (number) — Índice atual do tile, começando em 1. - `to` (number) — Índice do tile depois da movimentação, começando em 1. Não retorna nada. #### `app.paintTilemapPixels(layerId, frameId, x, y, width, height, pixels, mode)` — altera, desfazível, recusada em uma camada bloqueada Pinta pixels em coordenadas da tela em uma camada de tilemap, escrevendo através da inversão/rotação de cada posição de tile. Uma única etapa de desfazer. - `layerId` (string) - `frameId` (string) - `x` (number) — Borda esquerda da região escrita, em coordenadas da tela. - `y` (number) — Borda superior da região escrita, em coordenadas da tela. - `width` (number) - `height` (number) - `pixels` (table) — Números RGBA planos (4 por pixel, width*height pixels); alfa 0 apaga. - `mode` (TilePaintMode: "edit" | "auto") — "edit" altera os tiles que as células já usam (todas as posições são atualizadas); "auto" funciona por célula pintada como o Auto do Aseprite: reutiliza um tile idêntico (ou um invertido/girado, conforme app.setTilesetMatch), senão um tile copy-on-write / novo, e depois remove os tiles que a edição deixou sem uso. Não retorna nada. #### `app.removeTilemapTile(layerId, tileIndex)` — altera, desfazível, recusada em uma camada bloqueada Exclui um tile do tileset de uma camada de tilemap. As posições dele são limpas; as posições de tiles com número maior descem uma casa para continuarem mostrando a mesma imagem (exatamente o Excluir do painel de tileset). - `layerId` (string) — Uma camada de tilemap. - `tileIndex` (number) — Tile a excluir, começando em 1. Não retorna nada. #### `app.setTilemapInstances(layerId, frameId, instances)` — altera, desfazível, recusada em uma camada bloqueada Substitui as posições dos tiles de uma camada de tilemap em um quadro. x/y são coordenadas da grade de tiles. Gera erro se layerId não for uma camada de tilemap. - `layerId` (string) - `frameId` (string) - `instances` (table) — Array de tabelas {x, y, tileIndex, flipH, flipV, rotate90} que substituem as posições deste quadro; vazio as limpa. Não retorna nada. #### `app.setTilemapTilePixels(layerId, tileIndex, pixels)` — altera, desfazível, recusada em uma camada bloqueada Substitui os pixels de um tile de uma camada de tilemap. Todas as posições desse tile (todos os quadros, qualquer inversão/rotação) são atualizadas na hora. Gera erro para layerId/índice/tamanho de pixels inválidos. - `layerId` (string) - `tileIndex` (number) - `pixels` (table) — Buffer plano de pixels (RGBA = 4 números por pixel, indexado = 1) do tamanho do tile. Não retorna nada. #### `app.setTilesetMatch(layerId, flipH, flipV, rotate)` — altera, desfazível Define as opções de "correspondência de inversões" do tileset: na pintura de tilemap "auto", pixels novos iguais a um tile existente invertido/girado reutilizam esse tile com as flags da posição definidas, em vez de criar um tile. - `layerId` (string) — Uma camada de tilemap. - `flipH` (boolean) — Corresponde a tiles invertidos horizontalmente. - `flipV` (boolean) — Corresponde a tiles invertidos verticalmente. - `rotate` (boolean) — Corresponde a tiles girados 90 graus (apenas tiles quadrados). Não retorna nada. #### `app.setTilesetProperties(layerId, name?, baseIndex?)` — altera, desfazível Define o nome e o Índice base de um tileset. O índice base só muda como os tiles são numerados no painel Tileset e no Aseprite; os índices de tiles nos scripts continuam começando em 1. Vale para todas as camadas que compartilham o tileset. - `layerId` (string) — Uma camada de tilemap. - `name` (string, opcional) — O nome do tileset; "" o limpa; nil o mantém. - `baseIndex` (number, opcional) — O Base Index do Aseprite: o número com que o primeiro tile é exibido (padrão 1), de -32768 a 32767; nil o mantém. Não retorna nada. #### `app.stampTiles(layerId, frameId, cells, opts?)` — altera, desfazível, recusada em uma camada bloqueada Carimba um tile nas células da grade de tiles indicadas de uma camada de tilemap (ou, com erase, as limpa) — exatamente o carimbo de tile da interface. As células não tocadas mantêm suas posições. Com symmetry, as células espelhadas recebem o tile espelhado (as inversões se espelham junto); com respectSelection, as células fora da seleção são ignoradas. - `layerId` (string) — Uma camada de tilemap. - `frameId` (string) - `cells` (table) — Lista de células da GRADE DE TILES { x = col, y = row } (ou { col, row }) — não pixels do sprite. - `opts` (table, opcional) Também aceita **Opções de posicionamento** (veja "Grupos de opções"), e ainda: - `tileIndex` (integer ≥ 0; padrão context.tileIndex) — O tile a colocar, começando em 1. - `flipH` (boolean; padrão context.tileFlipH) — Inverte horizontalmente os tiles colocados. - `flipV` (boolean; padrão context.tileFlipV) — Inverte verticalmente os tiles colocados. - `rotate90` (boolean; padrão context.tileRotate90) — Gira os tiles colocados em 90° no sentido horário (apenas tiles quadrados). - `erase` (boolean; padrão false) — Remove as posições das células em vez de colocar um tile. Não retorna nada.