Tilemap

A grid of tiles from one or more tileset images, drawn and (optionally) collided with as a whole. The grid starts at the entity’s position and runs right and down, on an isometric map (see Shape) as diamonds running down to the right and down to the left, and on a hex map as rows of hexagons. Paint it in the Scene view, edit Tiles as text in the inspector, or change it from scripts with SetTile, FillRect and FloodFill, each of which can also lay its tile turned or flipped (see Turns). A tilemap with no Image on an entity inside another tilemap’s is one of its layers (see LayerOf), painted on its own: it uses that map’s tilesets, tile size and tile settings, while its Tiles (and Turns), Tint, Order and collision (Solid, Layer, IgnoreLayers) are its own.

Each row of Tiles is a line of characters, one per cell, top row first: . is empty and 0-9, a-z, A-Z pick tiles 0–61; tiles from 62 on are accented letters, then CJK characters (see CharOf). Rows are saved one per line, so levels diff line by line in git. How each cell’s tile is turned or flipped is a grid of its own, Turns, lined up with it.

Needed by: Blocks, DungeonGenerator, FallingBoard, LineTiles, MatchBoard, WallRooms, WorldGenerator

Draws itself (its entity draws at Order 0 unless it has a Sprite, whose order counts).

Properties

Each is listed as its key in the scene file and the MCP tools, then its kind of value, its default and what it does.

• image: text = null. The first tileset’s image, relative to Assets: tiles 0 on. Without one, its tiles draw as solid squares of Tint (or of PlaceholderColors, a color for each tile), or inside another tilemap’s entity, it’s a layer of that map (see LayerOf). MoreTilesets adds others. (A picture in Assets, e.g. “Sprites/back.png”.) (Field: an image.)
• columns: a whole number = 1. Tiles across the first tileset’s image. (Field: a number.)
• rows: a whole number = 1. Tiles down the first tileset’s image. (Field: a number.)
• placeholderColors: lines of text: an array of strings, or one string with line breaks = []. For a map with no Image: a color for each tile number, in order, to block a level out before there’s any art. Tile 0 draws as a solid shape of the first color, tile 1 of the second and so on (times Tint), so a floor can be checkered and wall tops told from wall faces; a number past the end goes round the list again. The palette in the Scene view offers a tile for each color to paint with. Empty (the default), every tile is a solid shape of the tint. A layer uses its map’s (see LayerOf), so every layer’s tile 2 is the same color. (Colors in order, one per line, as hex (“#F2607E”). The Inspector lists them a row each with the color shown and the palette to pick from.) (Field: its own editor: List Rows.)
• placeholderGrid: true or false = false. For a map with no Image: draws a thin line round each tile, a little darker than it (lighter on a dark one), so the cells show on a floor of one color. Off by default. A layer uses its map’s (see LayerOf). (Field: on or off.)
• moreTilesets: lines of text: an array of strings, or one string with line breaks = []. Tilesets after the first (Image), one per line: an image and its tiles across and down, like “Tiles/props.png 4x4”. Each one’s tiles are numbered on from the next hundred after the tiles before it: with a first tileset of 16 tiles, the second’s are 100 on and a third’s 200 on, so a tileset that grows (up to the next hundred) doesn’t renumber the ones after it. Tile number fields (Background Tiles, Auto Tiles and the rest) and GetTile use these numbers. Art > Add Tileset to Tilemap adds one. (Tilesets, one per line: an image in Assets and its tiles across and down, e.g. “Tiles/props.png 4x4”. The Inspector lists them a row each, with the image picked from the project’s.) (Field: its own editor: Tilesets.)
• shape: one of Square, Isometric, Hex = “Square”. How the cells are laid out: TileShape.Square in rows and columns, or TileShape.Isometric as diamonds twice as wide as they’re tall, the grid’s columns running down to the right from the entity’s position (the top corner of cell 0, 0) and its rows down to the left. Tiles, painting, CellAt and CellCenter all follow it, and so do collisions: on an isometric map a body meets a solid tile’s diamond with the diamond under its collider (see Body), sliding along the walls, and grid movers step from diamond to diamond. TileShape.Hex makes the cells hexagons pointing up and down, a tile wide and a tile tall, in rows three quarters of a tile apart with every odd row (the second, fourth…) shifted half a tile to the right, the entity’s position at the top left of cell 0, 0’s picture; grid movers step from hexagon to hexagon on them (and Tactics units walk and fight over them), and a body’s collider meets a solid hexagon’s six sides and slides along them. A layer’s is its map’s (see LayerOf). (Field: one of its values.)
• tileSize: a number = 1. Width and height of one cell in world units, before the transform’s scale; on an isometric map, a diamond’s width (it’s half as tall), and on a hex map a hexagon’s width and height (its rows are three quarters of it apart). A layer’s is its map’s (see LayerOf). (Field: a number.)
• tileHeight: a number = 0.5. On an isometric map, how tall each tile’s picture is drawn, in tile widths: 0.5 (the default) is a flat diamond, and 1 a square picture standing on its diamond, a block or wall as tall again (a tileset of 32 by 32 pixel tiles with a 32 by 16 diamond at the bottom). A picture stands on its cell’s bottom corner. A layer’s is its map’s. (Field: a number.)
• sortByY: true or false = false. Draws each row of tiles (each diagonal row, on an isometric map) in depth among the sprites, as the camera’s Camera.SortByY does for things that move: whatever stands lower down draws in front, so a character walks behind a wall and in front of it. Needs the camera’s Sort By Y on too. Off, the map draws as one, behind what’s lower in the Hierarchy at its Order: right for floors, so put walls and props on a layer of their own (see LayerOf) and turn this on there. The tiles always draw back to front among themselves. (Field: on or off.)
• tint: a color, “#RRGGBB” or “#RRGGBBAA” = “#FFFFFFFF”. Multiplies the tiles’ colors: white leaves them as they are, and a lower alpha fades them. (Field: a color.)
• order: a whole number = 0. Higher draws on top, like Sprite.Order. (Field: a number.)
• solid: true or false = true. When set, tiles are walls and floors that bodies collide with (except BackgroundTiles). (Field: on or off.)
• backgroundTiles: text = null. Tiles that never collide, for decoration like grass, windows or signs: tile numbers and ranges, e.g. “10-15, 20”. (Tiles of the tilemap’s tilesets by number (the first tileset’s from 0, the next’s from 100, then 200…): a string of numbers and ranges like “10-15, 20”, or for a whole number one tile. The Inspector shows the tiles to click.) (Field: its own editor: Tile Numbers.)
• oneWayTiles: text = null. Tiles that only block bodies landing on top, like BoxCollider.OneWay: tile numbers and ranges, e.g. “4, 5”. (Tiles of the tilemap’s tilesets by number (the first tileset’s from 0, the next’s from 100, then 200…): a string of numbers and ranges like “10-15, 20”, or for a whole number one tile. The Inspector shows the tiles to click.) (Field: its own editor: Tile Numbers.)
• animatedTiles: text = null. Tiles that animate while the game runs, as runs of frames side by side in the tileset with an optional speed in frames a second: “16-19 @6” turns tiles 16, 17, 18 and 19 into water that ripples through all four. Separate runs with commas: “16-19 @6, 30-31 @2”. A cell painted with a later frame starts the run from there, so neighbors needn’t move in step. (Runs of tiles that animate: “first-last @speed” in frames a second, separated by commas, e.g. “16-19 @6, 30-31 @2” (4 a second without @). The Inspector lists them a row each with their frames shown.) (Field: its own editor: Tile Animations.)
• ladderTiles: text = null. Tiles that are ladders: they never collide, and a PlatformerMovement climbs them with up and down. Tile numbers and ranges, e.g. “12, 13”. (Tiles of the tilemap’s tilesets by number (the first tileset’s from 0, the next’s from 100, then 200…): a string of numbers and ranges like “10-15, 20”, or for a whole number one tile. The Inspector shows the tiles to click.) (Field: its own editor: Tile Numbers.)
• slopeUpTiles: text = null. Tiles that are slopes rising to the right, like “/”: solid below the line from their bottom-left corner to their top-right one, so bodies walk up and down them. Tile numbers and ranges, e.g. “20”. (Tiles of the tilemap’s tilesets by number (the first tileset’s from 0, the next’s from 100, then 200…): a string of numbers and ranges like “10-15, 20”, or for a whole number one tile. The Inspector shows the tiles to click.) (Field: its own editor: Tile Numbers.)
• slopeDownTiles: text = null. Tiles that are slopes falling to the right, like “\”: solid below the line from their top-left corner to their bottom-right one. (Tiles of the tilemap’s tilesets by number (the first tileset’s from 0, the next’s from 100, then 200…): a string of numbers and ranges like “10-15, 20”, or for a whole number one tile. The Inspector shows the tiles to click.) (Field: its own editor: Tile Numbers.)
• autoTiles: text = null. Runs of 16 tiles in the tileset that fit themselves to their neighbors: paint with any tile of a run and each cell shows the piece that joins up with the cells around it painted from the same run. “16-31” (or just “16”), several separated by commas. A run’s tiles go in order of which sides join, counting up 1, right 2, down 4 and left 8: the first is a lone block, the second joins only above, the last joins on every side. (Runs of 16 tiles that join up with their neighbors, each by its first tile or as first-last, separated by commas, e.g. “16-31” or “16, 48”. The Inspector lists each run with its pieces shown.) (Field: its own editor: Auto Tiles.)
• layer: text = null. The collision layer of the map’s tiles, like Collider.Layer. Empty is “Default”. (Names a collision layer: this entity’s own, which other fields can name.) (Field: a name.)
• ignoreLayers: text = null. Layers that pass through the map’s tiles, like Collider.IgnoreLayers, e.g. “Ghost”. (Names collision layers: their names, separated by commas.) (Field: a name.)
• tiles: lines of text: an array of strings, or one string with line breaks = []. The grid, top row first; see the remarks on Tilemap for the format. (Plain text: the grid, a line a row: painted in the Scene view with the tile palette.) (Field: lines of text.)
• turns: lines of text: an array of strings, or one string with line breaks = []. How each cell’s tile is turned or flipped, a line a row lined up with Tiles: a character per cell, . as drawn, 1, 2 and 3 turned a quarter, a half and three quarters clockwise, and 4 to 7 the same mirrored left to right first (4 just mirrored, 6 upside down; see TileTurn). Animated tiles turn with their cells, and slope tiles collide turned. Set it with SetTile or by turning the brush while painting (Z, X); empty, as it is for a map that turns nothing, draws every tile as it is. Quarter turns suit square maps; flips and half turns suit every shape. (Plain text: a line a row, a character a cell: painted in the Scene view by turning the brush with Z and X.) (Field: lines of text.)

Grid

• linesUpWith: text = null. Another tilemap, by its entity’s name, whose cells this one’s line up with, e.g. “Level”: it takes that map’s TileSize and Shape, and its top left stays on a corner of that map’s cells (moved to the nearest as it’s set, as it’s dragged in the Scene view, and while the game runs), so a match-3 or falling-blocks board in a platformer level sits on the level’s squares. Its own tiles stay its own: with Solid ticked, a board’s settled pieces are walls and floors the level’s bodies stand on. Empty lines up with nothing. (Names an entity.) (Field: an entity’s name.)

While the game runs

Not saved with the scene; scripts read them, and entity_get shows them as live while the game plays.

• layerOf: an entity with a Tilemap: its name, id or path. The tilemap this one is a layer of, or null when it isn’t one. A tilemap with no Image of its own on an entity inside another tilemap’s entity is a layer of that map: it’s drawn with that map’s tilesets, TileSize and tile settings (Background, One Way, Ladder, Slope, Animated and Auto Tiles), while its Tiles, Tint, Order and collision (Solid, Layer, IgnoreLayers) are its own. Giving it an Image makes it a map of its own again. Art > Add Layer to Tilemap adds one.
• baseMap: an entity with a Tilemap: its name, id or path. The map whose tilesets and tile settings this one uses: itself, or for a layer the map it’s a layer of (the bottom one, for a layer of a layer).
• animationTime: a number. Seconds its AnimatedTiles have been playing. Advanced by the game.
• beltTravel: a number or null. How far a Conveyor whose Belt Tiles this map is has moved its belts, in cells (a cell’s worth kept): while it’s set, its AnimatedTiles step with it rather than with time, a run’s frames making up one cell of travel. Set by the conveyor; null plays them by time.
• width: a whole number. Number of columns: the length of the longest row.
• height: a whole number. Number of rows.
• depths: a whole number. How many rows DepthOf gives, back to front.
• gridMap: an entity with a Tilemap: its name, id or path. The map LinesUpWith names, if it’s in the scene (and isn’t this one).

Scripts use it as Tilemap: its methods, events and values that aren’t saved with the scene.