Tilemaps

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 (tileWidthtileHeight4, 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.

Em Markdown: tilemaps.md.