Map File

From Hero of Allacrost

This page explains how each map in Hero of Allacrost is represented in Lua script files. 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.

Overview

We define a standard map script format here so that maps 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 map is represented by a single Lua script file, typically called the map script, map file, or map script file. Translations for map text are kept elsewhere and referred to by the gettext library, but they are of no major concern to the map script file itself.

The table below contains a list of markup tags are used to represent additional information about some lines in the map 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.

Map File Standard

The following is a terse yet complete definition of how every map data 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 map file. The next section will explain what functions are required of the map script.

-----------------------------------------------------------------------------[[
-- Map Name:
-- Map Designer(s):
-- Created: xx/xx/xx
-- Last Modified: xx/xx/xx
--
-- Description
-----------------------------------------------------------------------------]]

map = {}                            -- (A)

file_name = $string$                -- (B)
map_name = $string$
num_tile_cols = $uint32 (32, inf)$
num_tile_rows = $uint32 (24, inf)$
enemy_encounters = $bool$           


sound_filenames = {}
sound_filenames[1] = $string$
sound_filenames[2] = $string$
-- ...continued for each sound

music_filenames = {}
music_filenames[1] = $string$
music_filenames[2] = $string$
-- ...continued for each music piece

tileset_filenames = {}
tileset_filenames[1] = $string$
tileset_filenames[2] = $string$
-- ...continued for each tileset file

map_grid = {}
map_grid[0] = { 0, 1, 0, 1, ... }
map_grid[1] = { 1, 1, 0, 0, ... }
-- ...continued for each map grid row

lower_layer = {}

lower_layer[0] = { -1, 4, 26, 14, ... }
lower_layer[1] = { 0, 8, 15, 106, ... }
-- ...continued for each map tile row

middle_layer = {}
middle_layer[0] = { 5, 19, 55, 127, ... }
middle_layer[1] = { 5, 89, 131, 16, ... }
-- ...continued for each map tile row

upper_layer = {}
upper_layer[0] = { 14, 4, -1, -1, ... }
upper_layer[1] = { 8, -1, 43, -1, ... }
-- ...continued for each map tile row

Script Functions Standard

Each map script is required to have a handful of functions that are called on occasion by the map engine. These functions are contained within the same map file as the data in the standard above, and are defined immediately after that data. Once again, comments are noted in this standard and explained in the table below.

function Load(m)                     -- (A)
    map = m;

    -- ... map objects, sprites, dialogue, and actions are all created in the body of this function
end


function CheckTriggers()              -- (B)

end


function PreDraw()                    -- (C)

end


function PostDraw()                   -- (D)

end