[TUTORIAL][2D] Como Criar Exports Para o Tiled Map Editor

Introdução

O Tiled Map Editor é um editor de níveis gratuito e open-source.

Esta ferramenta é especialmente útil para quando se está desenvolvendo jogos sem game engines. Independente de quais bibliotecas/frameworks você use, é muito difícil fazer um jogo sem ter pelo menos uma ferramenta visual para ajudar, principalmente quando você quer que um jogo tenha várias fases.

O Tiled é excelente em situações como essa, pois te ajuda a evitar ter que criar um editor inteiro do zero, e muitas bibliotecas/frameworks e até game engines suportam importar/exportar mapas feitos nele.

Infelizmente, "muitas" não é igual a "todas": A Phaser, por exemplo, permite a importação de arquivos TMX diretamente, enquanto o GameMaker Studio 2 utiliza seu próprio formato de fases, e não possui opção de importação.

Em situações como essa, o Tiled oferece opções para exportar suas fases para vários outros formatos. No caso do exemplo acima, o Tiled permite exportar nossos mapas diretamente para o formato do GMS2.


Mas e quando temos uma biblioteca/framework que não suporta o formato do Tiled? Ou quando estamos usando uma game engine com muitas funcionalidades boas, mas com um editor de fases péssimo/obsoleto?

E é daqui que surge este tutorial: estarei ensinando como escrever nossos próprios exports para o Tiled.

Assim como fiz no meu antigo tutorial do Blender, não pretendo estender muito nesse também. No mais, é outro tutorial destinado a mim mesmo. Se de repente eu esquecer ou precisar de informação extra, pretendo ir deixando aqui o que eu for aprendendo, de forma simples e objetiva.

Iniciando

Afim de estender suas funcionalidades, o Tiled oferece suporte a extensões, que podem ser escritas em JavaScript. Isso inclui, é claro, nossos próprios exports.

Começando pelo começo... vamos baixar o Tiled:
Link de download do Tiled Map Editor

Depois de instalado, abra o Tiled e vá em "Editar > Preferências...".


Na aba "Plugins", você encontrará o diretório de extensões lá embaixo. Clique em "Abrir..." e você terá a pasta aberta em seu explorador de arquivos.


As extensões do Tiled são escritas em JavaScript. Para instalar uma extensão, tudo que precisamos fazer é copiar um arquivo .js para esta pasta. Isso, é claro, inclui também a nossa própria extensão de export.

Quando um arquivo .js é copiado para esta pasta, o Tiled carrega a extensão automaticamente. Não é necessário fechar nem reabrir nada.

Documentação

Para não se perder no tutorial, recomendo guardar estes links. Esta é a documentação oficial do Tiled:

• Scripting — Tiled Documentatino
  
• Tiled Scripting API
  

Para este tutorial, utilizaremos a função tiled.registerMapFormat(shortName, mapFormat), que convenientemente já possui um exemplo para nós escrito na documentação.

Arquivos do tutorial

Caso ache necessário, os arquivos usados para fazer o tutorial estão disponíveis abaixo:
Link de download do conteúdo do tutorial

O jogo

Para ajudar a criar nosso export de exemplo, vamos imaginar um jogo...


Vamos chamar este jogo de Dungeon Quest!
Este dungeon crawler é composto de 3 camadas.

O chão, em uma camada de tiles onde os personagens podem atravessar livremente:


As paredes, em uma camada de tiles que bloqueia o movimento:


E os sprites, em uma camada de objetos que representarão nossos personagens:


O jogo contém 5 sprites:

• Herói: personagem principal controlado pelo jogador.
  
• Ogro: inimigo do jogador.
  
• Dinheiro: coletáveis que aumentam a pontuação do jogador.
  
• Comida: coletáveis que aumentam a saúde do jogador.
  
• Porta: Quando o herói avança até ela, o jogador vai para a próxima fase.
  

Este é o tileset que usaremos (créditos: Loveable Rogue, por Surt):


Simples, não é? Veja como esta fase aparece no editor:


Para converter nosso mapa corretamente, ele deverá possuir 3 camadas:

• Sprites (camada de objetos)
  
• Walls (camada de tiles)
  
• Floor (camada de tiles)
  

O formato

Nosso formato de fases será um arquivo JSON contendo esta estrutura:

Código:

{
   "width": 160,
   "height": 160,
   "floor": [
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1]
   ],
   "walls": [
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
      [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1]
   ],
   "player": { "x": 0, "y": 0 },
   "exit": { "x": 0, "y": 0 },
   "coins": [
      { "x": 0, "y": 0 }
   ],
   "food": [
      { "x": 0, "y": 0 }
   ]
   "enemies": [
      { "x": 0, "y": 0 }
   ]
}

O formato não é tão complicado. O fato de ser um JSON torna as coisas ainda mais fáceis para nós, já que o JSON é suportado naturalmente pelo JavaScript.

Já temos um jogo, um tileset, um mapa e uma estrutura de arquivo. Vamos começar!

A extensão

Script

Abra o Tiled e mantenha ele aberto. Feito isso, vamos até o diretório de extensões para criar um arquivo chamado dungeon_quest.js. O código inicial do nosso arquivo será este:

Código:

/// <reference types="@mapeditor/tiled-api" />

/**
 * Exporter de exemplo para o nosso jogo, o Dungeon Quest.
 */
let dungeonQuestExporter = {
   /** Nome do exporter. */
   name: "Dungeon Quest level",

   /** Extensão de arquivo que será salvo. */
   extension: "json",
   
   /**
     * Exporta o arquivo.
     *
     * @param {TileMap} map Mapa.
     * @param {string} fileName Nome do arquivo.
     */
   write(map, fileName) {
      // Dados do mapa exportado.
      let mapData = {
         width: 0,
         height: 0,
         floor: [],
         walls: [],
         player: { x: 0, y: 0 },
         exit: { x: 0, y: 0 },
         coins: [],
         food: [],
         enemies: []
      };
      
      // Criar e escrever arquivo...
      let file = new TextFile(fileName, TextFile.WriteOnly);
         file.write(JSON.stringify(mapData));
         file.commit();
   }
};

// Registrar exporter no Tiled...
tiled.registerMapFormat("dungeon", dungeonQuestExporter);

Assim que você criar e salvar este arquivo, o Tiled carregará nossa extensão automaticamente. Note como a nossa opção de exportar já aparece imediatamente:


Fique de olho também no console embaixo do editor. Erros de script aparecerão lá:


Para escrever o nosso export, usaremos as funções da API do Tiled para ler as propriedades do mapa e adaptaremos ela de acordo com a estrutura que decidimos anteriormente. O formato já está expresso na variável mapData, então tudo que precisamos fazer é ir preenchendo seus valores aos poucos.

Vamos começar pelo mais fácil: o tamanho.

Tamanho do mapa

O tamanho do mapa pode ser obtido utilizando os seguintes valores:

• map.width: Largura do mapa, em tiles.
  
• map.height: Altura do mapa, em tiles.
  
• map.tileWidth: Largura dos tiles.
  
• map.tileHeight: Altura dos tiles.
  

No nosso formato, queremos o tamanho da fase inteira. Para isso, é só multiplicar os valores.

Código:

// Dados do mapa exportado.
let mapData = {
   width: map.tileWidth * map.width,
   height: map.tileHeight * map.height,
   floor: [],
   walls: [],
   player: { x: 0, y: 0 },
   exit: { x: 0, y: 0 },
   coins: [],
   food: [],
   enemies: []
};

Camadas

Para converter nossa fase, teremos que explorar todas as camadas do mapa. Para isso, utilizaremos este loop:

Código:

// Percorrer camadas...
for(let i = 0; i < map.layerCount; i++) {
   let layer = map.layerAt(i);
   
   // Ações para camadas de tiles:
   if(layer.isTileLayer) {
      // ...
   }
   
   // Ações para camadas de objetos:
   else if(layer.isObjectLayer) {
      // ...
   }
}

As funções para obter as camadas são auto-explicativas:

• map.layerCount: Retorna a quantidade de camadas do mapa.
  
• map.layerAt(index): Retorna um objeto de camada no índice específicado.
  

Depois de obter a camada, podemos fazer uso dos seguintes valores:

• layer.width: Largura da camada, em tiles.
  
• layer.height: Altura da camada, em tiles.
  
• layer.isTileLayer: Indica se a camada é de tiles.
  layer.isObjectLayer: Indica se a camada é de objetos.
  

Vamos começar pelos tiles.

Tiles

As camadas de tiles possuem uma função que nos ajudará bastante:

• layer.cellAt(x, y): Retorna uma célula nas coordenadas de tile especificadas.
  

Com isso, podemos percorrer todos os tiles da camada e organizá-los em uma Array 2D, do jeito que está a estrutura do nosso formato de mapas.

Para deixar o código de conversão mais limpo, vamos criar uma nova função to2DArray(layer), que converterá esta camada para nós:

Código:

/**
 * Converte uma camada em uma Array 2D.
 *
 * @param {TileLayer} layer Camada.
 * @returns {number[][] | null}
 */
function to2DArray(layer) {
   // Caso a camada não seja de tiles, a função não continuará...
   if(!layer.isTileLayer) {
      return null;
   }

   // Linhas do tileset (Array 2D).
   let rows = [];

   // Percorrer linhas da camada...
   for(let y = 0; y < layer.height; y++) {
      let column = [];

      // Percorrer colunas da camada...
      for(let x = 0; x < layer.width; x++) {
         column.push(layer.cellAt(x, y).tileId);
      }

      // Salvar tiles coletados:
      rows.push(column);
   }

   return rows;
}

E como vamos diferenciar o chão das paredes?
Para isso, utilizaremos os nomes das camadas como referência. Com isso, conseguimos obter os tiles:

Código:

// Percorrer camadas...
for(let i = 0; i < map.layerCount; i++) {
   let layer = map.layerAt(i);
   
   // Encontrar tiles...
   if(layer.isTileLayer) {
      let layerName = layer.name.toLowerCase();
      let expected = ["floor", "walls"];
      
      if(expected.includes(layerName)) {
         mapData[layerName] = to2DArray(layer);
      }
   }
   
   // Ações para camadas de objetos:
   else if(layer.isObjectLayer) {
      // ...
   }
}

Com isso, agora temos Arrays 2D!
Vamos aos objetos.

Objetos

Para ler os objetos, utilizamos este valor:

• layer.objects: Array de objetos da camada.
  

E como vamos diferenciar os objetos, se não declaramos nada neles?
Para isso, utilizaremos o ID do tile que compõe o objeto. Isto pode ser obtido usando o valor mapObject.tile.id.

Você pode descobrir os IDs selecionando um tile no editor e verificando suas propriedades.


Na imagem acima, descobrimos que o herói possui o ID 15.
Vamos identificar todos os IDs e oranizá-los em constantes:

Código:

/** ID do sprite do herói. */
const SPR_PLAYER = 15;

/** ID do sprite do ogro. */
const SPR_ENEMY = 16;

/** ID do sprite do dinheiro. */
const SPR_COINS = 17;

/** ID do sprite da comida. */
const SPR_FOOD = 18;

/** ID do sprite da porta. */
const SPR_EXIT = 19;

Agora é só percorrer os objetos:

Código:

// Percorrer objetos...
for(let mapObject of layer.objects) {
   let tileId = mapObject.tile.id;

   // Herói.
   if(tileId === SPR_PLAYER) {
      mapData.player.x = mapObject.x;
      mapData.player.y = mapObject.y;
   }

   // Ogro.
   else if(tileId === SPR_ENEMY) {
      mapData.enemies.push({ x: mapObject.x, y: mapObject.y });
   }

   // Dinheiro.
   else if(tileId === SPR_COINS) {
      mapData.coins.push({ x: mapObject.x, y: mapObject.y });
   }

   // Comida.
   else if(tileId === SPR_FOOD) {
      mapData.food.push({ x: mapObject.x, y: mapObject.y });
   }

   // Saída.
   else if(tileId === SPR_EXIT) {
      mapData.exit.x = mapObject.x;
      mapData.exit.y = mapObject.y;
   }
}

Resultado

Com tudo já escrito, este é o nosso código final:

Código:

/// <reference types="@mapeditor/tiled-api" />

/** ID do sprite do herói. */
const SPR_PLAYER = 15;

/** ID do sprite do ogro. */
const SPR_ENEMY = 16;

/** ID do sprite do dinheiro. */
const SPR_COINS = 17;

/** ID do sprite da comida. */
const SPR_FOOD = 18;

/** ID do sprite da porta. */
const SPR_EXIT = 19;

/**
 * Converte uma camada em uma Array 2D.
 *
 * @param {TileLayer} layer Camada.
 * @returns {number[][] | null}
 */
function to2DArray(layer) {
   // Caso a camada não seja de tiles, a função não continuará...
   if(!layer.isTileLayer) {
      return null;
   }

   // Linhas do tileset (Array 2D).
   let rows = [];

   // Percorrer linhas da camada...
   for(let y = 0; y < layer.height; y++) {
      let column = [];

      // Percorrer colunas da camada...
      for(let x = 0; x < layer.width; x++) {
         column.push(layer.cellAt(x, y).tileId);
      }

      // Salvar tiles coletados:
      rows.push(column);
   }

   return rows;
}

/**
 * Exporter de exemplo para o nosso jogo, o Dungeon Quest.
 */
 let dungeonQuestExporter = {
   /** Nome do exporter. */
   name: "Dungeon Quest level",

   /** Extensão de arquivo que será salvo. */
   extension: "json",
   
   /**
     * Exporta o arquivo.
     *
     * @param {TileMap} map Mapa.
     * @param {string} fileName Nome do arquivo.
     */
   write(map, fileName) {
      // Dados do mapa exportado.
      let mapData = {
         width: map.tileWidth * map.width,
         height: map.tileHeight * map.height,
         floor: [],
         walls: [],
         player: { x: 0, y: 0 },
         exit: { x: 0, y: 0 },
         coins: [],
         food: [],
         enemies: []
      };

      // Percorrer camadas...
      for(let i = 0; i < map.layerCount; i++) {
         let layer = map.layerAt(i);

         // Encontrar tiles...
         if(layer.isTileLayer) {
            let layerName = layer.name.toLowerCase();
            let expected = ["floor", "walls"];

            if(expected.includes(layerName)) {
               mapData[layerName] = to2DArray(layer);
            }
         }

         // Encontrar objetos...
         else if(layer.isObjectLayer) {
            let layerName = layer.name.toLowerCase();
            let expected = ["sprites"];

            if(expected.includes(layerName)) {

               // Percorrer objetos...
               for(let mapObject of layer.objects) {
                  let tileId = mapObject.tile.id;

                  // Herói.
                  if(tileId === SPR_PLAYER) {
                     mapData.player.x = mapObject.x;
                     mapData.player.y = mapObject.y;
                  }

                  // Ogro.
                  else if(tileId === SPR_ENEMY) {
                     mapData.enemies.push({ x: mapObject.x, y: mapObject.y });
                  }

                  // Dinheiro.
                  else if(tileId === SPR_COINS) {
                     mapData.coins.push({ x: mapObject.x, y: mapObject.y });
                  }

                  // Comida.
                  else if(tileId === SPR_FOOD) {
                     mapData.food.push({ x: mapObject.x, y: mapObject.y });
                  }
                  
                  // Saída.
                  else if(tileId === SPR_EXIT) {
                     mapData.exit.x = mapObject.x;
                     mapData.exit.y = mapObject.y;
                  }
               }
            }
         }
      }
      
      // Criar e escrever arquivo...
      let file = new TextFile(fileName, TextFile.WriteOnly);
         file.write(JSON.stringify(mapData));
         file.commit();
   }
};

// Registrar exporter no Tiled...
tiled.registerMapFormat("dungeon", dungeonQuestExporter);

Ao exportar o arquivo de mapa visto no exemplo, o arquivo gerado é este:

Código:

{"width":160,"height":160,"floor":[[-1,-1,-1,-1,-1,-1,-1,-1,-1,-1],[-1,10,10,10,10,-1,-1,-1,-1,-1],[-1,10,10,10,10,-1,-1,-1,11,-1],[-1,10,10,10,10,-1,-1,-1,11,-1],[10,10,10,10,10,-1,-1,-1,11,-1],[-1,10,10,10,10,-1,-1,-1,11,-1],[10,10,10,10,10,-1,-1,-1,11,-1],[-1,10,10,10,10,-1,11,11,11,-1],[-1,10,10,10,10,-1,-1,-1,-1,-1],[-1,-1,-1,-1,-1,-1,-1,-1,-1,-1]],"walls":[[8,5,9,-1,7,8,9,-1,0,-1],[1,-1,-1,-1,-1,1,0,-1,-1,-1],[1,-1,-1,-1,-1,1,-1,-1,-1,0],[13,-1,-1,-1,-1,1,-1,0,-1,-1],[-1,-1,-1,-1,-1,13,0,-1,-1,-1],[6,-1,-1,-1,-1,-1,-1,-1,-1,-1],[-1,-1,-1,-1,-1,-1,-1,-1,-1,0],[3,-1,-1,-1,-1,-1,-1,-1,-1,-1],[1,-1,-1,-1,-1,3,-1,-1,-1,-1],[8,5,5,5,5,14,-1,-1,-1,0]],"player":{"x":128,"y":48},"exit":{"x":48,"y":16},"coins":[{"x":0,"y":80},{"x":0,"y":112},{"x":16,"y":128},{"x":16,"y":144},{"x":32,"y":144}],"food":[{"x":96,"y":160},{"x":144,"y":144}],"enemies":[{"x":16,"y":32},{"x":32,"y":64},{"x":64,"y":48},{"x":64,"y":96}]}

Vamos formatar este arquivo utilizando o Prettier e ver o resultado:

Código:

{
  "width": 160,
  "height": 160,
  "floor": [
    [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
    [-1, 10, 10, 10, 10, -1, -1, -1, -1, -1],
    [-1, 10, 10, 10, 10, -1, -1, -1, 11, -1],
    [-1, 10, 10, 10, 10, -1, -1, -1, 11, -1],
    [10, 10, 10, 10, 10, -1, -1, -1, 11, -1],
    [-1, 10, 10, 10, 10, -1, -1, -1, 11, -1],
    [10, 10, 10, 10, 10, -1, -1, -1, 11, -1],
    [-1, 10, 10, 10, 10, -1, 11, 11, 11, -1],
    [-1, 10, 10, 10, 10, -1, -1, -1, -1, -1],
    [-1, -1, -1, -1, -1, -1, -1, -1, -1, -1]
  ],
  "walls": [
    [8, 5, 9, -1, 7, 8, 9, -1, 0, -1],
    [1, -1, -1, -1, -1, 1, 0, -1, -1, -1],
    [1, -1, -1, -1, -1, 1, -1, -1, -1, 0],
    [13, -1, -1, -1, -1, 1, -1, 0, -1, -1],
    [-1, -1, -1, -1, -1, 13, 0, -1, -1, -1],
    [6, -1, -1, -1, -1, -1, -1, -1, -1, -1],
    [-1, -1, -1, -1, -1, -1, -1, -1, -1, 0],
    [3, -1, -1, -1, -1, -1, -1, -1, -1, -1],
    [1, -1, -1, -1, -1, 3, -1, -1, -1, -1],
    [8, 5, 5, 5, 5, 14, -1, -1, -1, 0]
  ],
  "player": { "x": 128, "y": 48 },
  "exit": { "x": 48, "y": 16 },
  "coins": [
    { "x": 0, "y": 80 },
    { "x": 0, "y": 112 },
    { "x": 16, "y": 128 },
    { "x": 16, "y": 144 },
    { "x": 32, "y": 144 }
  ],
  "food": [
    { "x": 96, "y": 160 },
    { "x": 144, "y": 144 }
  ],
  "enemies": [
    { "x": 16, "y": 32 },
    { "x": 32, "y": 64 },
    { "x": 64, "y": 48 },
    { "x": 64, "y": 96 }
  ]
}

Nosso export está finalizado! Agora, podemos utilizar o Tiled para criar e exportar fases para nosso jogo diretamente.

Fim

E este é o fim do tutorial. É difícil encontrar informação decente sobre extensões do Tiled, pelo menos em português. Então acho que será algo muito útil de se guardar por aqui.

Antes de conhecer esta API de extensões, o que eu fazia era converter para JSON e depois passava o arquivo em outro script, que cortava as partes que o Tiled exporta que eu não precisava e reorganizava no formato do jogo que eu estava desenvolvendo. Com uma extensão, eu consigo transformar as fases com muito mais facilidade.

Espero que isso ajude em alguma coisa. Até mais!

o/

Ferramenta interessante, e bom tutorial, simples mais útil, e, é bom as vezes tirar um tempo pra escrever coisas, fazer algo diferente e criar conteúdo, talvez alguém que leia nem venha a usar isso, mas só de ser apresentado para essa ferramenta, já pode ter ideias de pesquisar por ela e por outras com ideias similares e então agregar algo a sua pilha de desenvolvimento...

E possivelmente tu vai ajudar algumas pessoas com esse tutorial mas nunca saberá quem, mas faz parte de ensinar coisas na internet, e é bacana

.

@Mr.Rafael

Gostei bastante do tutorial, parabéns pela iniciativa! Sem dúvidas vai ajudar bastante a galera do fórum. Tutorial bem detalhado, show demais!