Tileset Definition File

From Hero of Allacrost Wiki
Revision as of 08:34, 6 December 2012 by Roots (talk | contribs) (Copying page from old wiki.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
This page is under development.

This page explains how each tileset in Hero of Allacrost is represented in Lua script files. These tileset files are used to describe tilesets to the editor. You do not need to read this page if your only desire is to be able to create maps for Allacrost (although reading this page won't hurt you). You might need to read this page if you are working on the map editor, map mode code, or scripting engine. This page may also be of interested to those who wish to understand how the mechanics of map creation and representation work in Allacrost. If you do not know the Lua programming language, you may wish to become familiar with it prior to reading this page, although it is not absolutely necessary to do so.


We define a standard tileset definition script format here so that tilesets can be used in maps appropriately, will behave as the designer expects them to, and to establish a common ground of communication between the Allacrost map editor and the game engine. Each tileset is represented by a Lua script file, typically called the tileset definition, tileset def file, or tileset script file.

What is a tileset definition file used for? It defines properties of a specific tileset so the editor can manipulate the tileset accordingly. Some of these properties include the walkability of tiles, what kind of tile a tile is (used for auto-tiling), whether a tile belongs to a chunk of tiles (used for easier placement on a map), and whether a tile is animated.

The table below contains a list of markup tags that are used to represent additional information about some lines in the tileset def file standard, such as the specific type of data a variable must be set to (Lua is a typeless language, C++ is not). These markup tags are not Lua syntax and are enclosed with matching dollar signs ($) to clearly indicate so. More than one tag may be enclosed by a pair of dollar signs, and these are separated with two spaces. For example, $int32 [-1000,4096]$ means an int32 data type between the inclusive range of -1000 to 4096.

Tag Meaning Example
Markup Tags
$type$ The variable must be of "type", which can be allowable Allacrost C++ datatype uint8, float, string, etc. $int32$: Variable must be a 32-bit integer type
$[min,max]$ A range of acceptable numeric values (inclusive) $[1,128]$: Number must be between 1 and 128
$[==,>,<,>=,<=,!=num]$ Another way to specify acceptable numeric values $[<0,!=10,>=20]$: Number must be greater than zero, not 10, and less than or equal to 20
$nilok$ It is acceptable if this variable is assigned to nil $nilok$: This variable may be assigned to nil

Tileset Definition File Standard[edit]

The following is a terse yet complete definition of how every tileset script file is structured. Some lines are commented (comments in Lua are represented with "--" or "--[[ --]]") with a letter, which are used in the explanation section to explain any peculiarities of the line or code block. The formatted block below contains only the static data that must be present in every tileset def file.

File: dat/tilesets/tileset_name.lua
-- Name Tileset datasheet

file_name = $string$                           -- (A)
image = $string$                               -- (B)
num_tile_cols = $uint32  [1,16]$
num_tile_rows = $uint32  [1,16]$

tile = {}                                      -- (C)

tile[0] =
walkability = { $uint32  [0,2^32-1]$,
                $uint32  [0,2^32-1]$,
                $uint32  [0,2^32-1]$,
                $uint32  [0,2^32-1]$ }         -- (D)
chunk = $uint32  [0,chunk_size-1]$ $nilok$     -- (E)
type = $string$                                -- (F)
-- ...continued for each tile

chunks = {}
chunks[0] = { $uint32  [0, num_tile_cols*num_tile_rows - 1]$,
              $uint32  [0, num_tile_cols*num_tile_rows - 1]$,
              ... }                            -- (G)
-- ...continued for each chunk of tiles

-- The animated tiles table has one row per animated tile,
-- with each entry in a row indicating which tile in the tileset
-- is the next part of the animation, followed by the time in ms
-- that the tile will be displayed for.
animated_tiles = {}
animated_tiles[0] = { 144, 25, 145, 50, ... }  -- (H)
-- ...continued for each animated tile

Comment Letter Explanation
Standard Comments Explanations
(A) The filename for this file includes the dat/tilesets/ prefix as well as the .lua extension.
(B) This is the filename of the tileset's image file. It includes the img/tilesets/ prefix, which is where the image should be located, as well as the .png extension.
(C) This table must contain an entry for each tile location in the tileset, even if there is no valid tile located there. Index into this table using a range from 0 to num_tile_cols * num_tile_rows - 1.
(D) There are 32 contexts used for walkability. Each context is represented by a bit, most significant is the 32nd context, least significant is the 1st. 0 = walkable; 1 = unwalkable. The first entry represents the upper-left corner of the tile, followed by the upper-right, lower-left, and lower-right.
(E) An index into the chunks table representing which chunk this tile belongs to, if any.
(F) Must be a string value existing in the dat/tilesets/autotiling.lua file, defining which group of tiles this one belongs to.
(G) Contains indeces of tiles belonging to a chunk. Should be specified in ascending order.
(H) In this example, the tile with index 144 will be displayed for 25 ms, followed by the tile with index 145 for 50 ms. This constitutes one animation.