Map‐editor Tiled - ZHAW-Team-Toxic/PM4-Team-Toxic GitHub Wiki

Tiled Map Editor Wiki

Tiled is a map editor used to create maps through spritesheets. It functions similarly to a screen viewer (like in Unity), allowing you to see in real time how the map will look with the different tiles. This page provides insights and learnings with this editor. Note that it is not meant to substitute for the official Tiled documentation, which remains the primary source of information.

Concepts

Understanding the following core concepts will help you effectively work with Tiled:

  1. Layers
  2. Spritesheets
  3. Tiles
  4. Tilesets
  5. Terainsets
  6. Automap
  7. Properties
  8. Files
  9. Code Examples

Layers

Layers in Tiled can be thought of as stacks of canvases where the tiles are placed. The order in which layers are rendered is important since they are drawn from the bottom (layer 0) upward. Layers Documentation

Tile Layers

Below is an example setup for tile layers:

  1. bottomLayer: Contains background tiles like grass, water, desert, etc.
  2. decorationLayer: Contains decorative sprites.
  3. resourceLayer: Contains resource sprites that act as in-game resources.
  4. buildingLayer: Contains buildings that are generated when the map is loaded (static).

Important:

  • Layers are rendered in order starting with layer 0. This means that each layer is drawn on top of the previous one.
    • When creating a map you can choode from where the tile should be drawn from (top to right, bottom to right, etc.). This way you can decide in which corner your origin (0,0) should be.
  • When rendering, be cautious about drawing on lower layers (like the bottomLayer) because it is generally not recommended. Instead, manage drawing through the render method to ensure proper layering.

Static vs. Dynamic:

  • Static Data: Only include values (like spawn points, buildable areas, or traversable tiles) that remain constant throughout the game.
  • Dynamic Data: Any values that change during gameplay should be managed separately via the game logic (dmg, health, range, etc.).

Creating Layers vs. Rendering Layers:

  • When a map is loaded, all layers are rendered as defined in the TMX file. However, adding sprites to these layers at runtime is either not possible or not recommended.
  • Dynamic sprites that are updated during gameplay should be rendered within the game’s render function. This requires maintaining a separate state to ensure persistence and proper order.
  • Tip: Use properties only for static values; game state data should be handled by the game logic.

Object Layers

Object Layers are used to define interactive elements on the map, such as:

  • Doors that open under certain conditions.
  • NPC paths.
  • Larger regions defining movement areas.

Object Layers are more flexible than setting properties on individual tiles and allow for richer interactions during gameplay. Objects Documentation

Spritesheets

Spritesheets are collections of equally sized images (tiles) arranged in a grid, typically stored in a PNG file. They serve as the base for creating tilesets in Tiled.

  • Usage: When starting a new project or map, you load your spritesheets into Tiled.
  • Conversion: The spritesheet is converted into a tileset by creating a TSX file, which holds metadata such as properties and the path to the PNG.

Tiles

Tiles are the individual images extracted from a spritesheet. In Tiled, you define a tile's properties within the tileset. Each tile can represent terrain, objects, or other in-game elements.

To Do: Expand this section by detailing how to define tile properties, how to manage animations (if applicable), and examples of common tile configurations.

Tilesets

Tilesets are essentially spritesheets that have been imported into Tiled. Tilesets Documentation They allow you to:

  • Rearrange or edit tiles.
  • Act as an intermediary between the raw spritesheet and the map.
  • Serve as a “palette” from which you can brush tiles onto your map.

Tilesets are saved as TSX files.

To Do: Consider including instructions on how to create a tileset from a spritesheet and how to adjust tile spacing, margins, and other settings.

Terrainsets

Terrainsets are collections of tiles that are designed to be placed together to form larger, coherent scenes (e.g., houses, beaches). Instead of manually placing individual tiles, terrainsets let you paint entire terrains with predefined combinations of tiles. Terrains Documentation

To Do: Provide examples of terrainset usage and best practices for creating cohesive terrain combinations.

Automap

The Automap feature allows you to define rules for automatically placing tiles or replacing certain tiles with others based on specific criteria. This can streamline the process of designing large maps by automating repetitive tasks. Automap Documentation

To Do: Expand this section with details on how to set up Automap rules, examples of common use cases, and any limitations or tips for effective use. Also need to dive deeper on how it works.

Properties

Properties in Tiled are used to add extra metadata to tiles, tilesets, and objects. This metadata can then be accessed and interpreted by your game’s logic (such as isSpawn, nontraversable, buildable etc.). Properties Documentation

Tile Properties

  • Definition: Properties assigned to a tile as part of the tileset.
  • Note: Individual tiles cannot have properties unless they are part of a tilesheet; properties are defined for the entire tileset and then inherited by tiles when they are placed on the map.

Tilesheet Properties

  • Definition: Properties that apply to the entire tilesheet (or spritesheet) loaded into Tiled.
  • Usage: Set these in the tilesheet window to provide global metadata for all tiles in that spritesheet.

Object Properties

  • Definition: Properties assigned to objects placed on object layers.
  • Usage: These are more flexible than tile properties and can be used to define interactive behaviors, triggers, or custom metadata for game elements.

Files

Tiled works with several file formats:

PNG

  • Usage: Commonly used for spritesheets.
  • Note: Ensure your PNG files have appropriate resolutions and are optimized for performance.

TMX

  • Usage: The primary file format for Tiled maps. It stores the arrangement of layers, tiles, and properties.
  • Note: TMX files are XML-based, making them easy to edit and integrate with various game engines.

TSX

  • Usage: Used for tilesets created from spritesheets.
  • Note: TSX files store metadata for the tiles, such as properties and the path to the associated PNG.

JSON

  • Usage: it's also possible to export the map to JSON.

Naming Conventions in Tiled

  • TSX Files: Name your tileset files clearly, reflecting the content or theme of the spritesheet (e.g., grassland.tsx, buildings.tsx).

Code-Examples

Loading a Map into Memory

private TiledMap map;
map = mapLoader.load("path/to/file.tmx);`

Calculating a tile-coordinate from a mouse input

Here you calculate where the tile is on the map.

       // Get screen coordinates of the mouse
        int screenX = Gdx.input.getX();
        int screenY = Gdx.input.getY();

        // Convert screen coordinates to world coordinates
        Vector3 worldCoords = new Vector3(screenX, screenY, 0);
        camera.unproject(worldCoords);

        // Calculate tile coordinates
        int tileX = (int)(worldCoords.x / tileWidth);
        int tileY = (int)(worldCoords.y / tileHeight);
        //result (12, 14) - On the map the tile is x = 12 and Y = 14`

Calculating the world coordinate Here you calculate based on pixel.

        int worldX = tileX * tileWidth; //our case 16
        int worldY = tileY * tileHeight; //our case 16

Searching for a layer

map.getLayers().get("yourLayerName"); //or
map.getLayers().get("0/1/2/3 Or 4"); //0 = bottom layer`

Searching for a tile or a tile with property X

for (int x = 0; x < layer.getWidth(); x++) {
    for (int y = 0; y < layer.getHeight(); y++) {
          Cell cell = layer.getCell(x, y);
          if (cell != null && cell.getTile() != null) {
              MapProperties props = cell.getTile().getProperties();
              if (props.containsKey(propertyKey) && props.get(propertyKey, String.class).equals(propertyValue)) {
                        return cell;
            }
        }
    }
}

Rendering a tile-raster

private ShapeRenderer shapeRenderer;
        // Draw the grid overlay (raster)
        // Set the ShapeRenderer's projection matrix to match the camera
        shapeRenderer.setProjectionMatrix(camera.combined);
        shapeRenderer.begin(ShapeRenderer.ShapeType.Line);
        shapeRenderer.setColor(1, 1, 1, 0.5f); // semi-transparent white

        // For example, if you have a 64x64 tile map:
        int mapWidthInTiles = 64;
        int mapHeightInTiles = 64;
  
        float tileWidth = 16;
        float tileHeight = 16;

        // Draw vertical lines
        for (
            int x = 0;
            x <= mapWidthInTiles; x++) {
            float worldX = x * tileWidth;
            shapeRenderer.line(worldX, 0, worldX, mapHeightInTiles * tileHeight);
        }

        // Draw horizontal lines
        for (
            int y = 0;
            y <= mapHeightInTiles; y++) {
            float worldY = y * tileHeight;
            shapeRenderer.line(0, worldY, mapWidthInTiles * tileWidth, worldY);
        }
        shapeRenderer.end();`

Placing a sprite onto the screen with coordinate X/Y

Placing the sprite onto the screen aligned with the raster

Conventions for Tiled

This document describes the conventions used in the Tiled map editor for the for the project Frontier. Since we'll be working with multiple people on the same maps, it's important to have a consistent way of working.

Layers

The amount of layers may change as further knowledge has been gained. But for now I suggest for now 4 layers:

  1. BottomLayer: This layer is for the background of the map. It should contain the ground, water, etc.

    • Concerned Tiles: Grass Tiles and variations of it, water tiles, Forest Grass Tiles, etc.

  2. DecorationLayer: This layer is for the decoration of the map. It should contain trees, rocks, etc. (which are not resources)

    • Concerned Tiles: Signe Trees, small rocks, grass, flowers, etc.

  3. ResourceLayer: This layer is for the resources of the map. It should contain trees, rocks, etc. (which are resources)

    • Concerned Tiles: Trees, rocks, iron ores / mountains, etc.

Files

All files should be named in a consistent way. This makes it easier to find the files you need. Put all files matching with the same ending in the same folder.

Tilesets

The tilesets are the images that contain the tiles. The tilesets should be named as follows:

  • bottomLayerTileset
  • decorationLayerTileset
  • resourceLayerTileset

If more are needed and for the sake of visibility numbers can be added to the end of the name.

  • bottomLayerTileset1, bottomLayerTileset2, etc.

Sprite Sheets (PNG)

Sprite sheets are the images that contain the tiles. They should be named as follows:

  • tilesetName.png

TMX Files

TMX files are the files that contain the map data. It is native to the Tiled map editor and there exists a TMX-Loader for libGDX. The TMX files should be named as follows:

  • mapName.tmx

TSX Files

TSX files are the files that contain the tileset data. It is native to the Tiled map editor and there exists a TMX-Loader for libGDX. The TSX files should be named as follows:

  • tilesetName.tsx

It should have the same name as the sprite sheet.

Objects

Objects are the entities that are placed on the map. They should be named as follows:

  • objectName

If more are needed and for the sake of visibility numbers can be added to the end of the name.

  • objectName1, objectName2, etc.

Properties

Properties are the data that is attached to the objects. They should be named as follows:

  • propertyName

If more are needed and for the sake of visibility numbers can be added to the end of the name.

  • propertyName1, propertyName2, etc.