Map File

From Hero of Allacrost Wiki
Jump to: navigation, search
This page is under development.


This page explains the format and conventions for map files in Hero of Allacrost. You should familiarize yourself with the information on this page if you are involved in the map making process and will be creating or editing any map files.

Each map you encounter in the game is created from two different types of map files, both of which are written in Lua. Map data files contain the static data on a map such as the size of the map, where the tiles are located, and so on. Data files are created and updated entirely within the Allacrost Map Editor program and are not edited by hand. Map script files contain dynamic data for a map, such as what sprites appear and where, dialogue that occurs, audio files to play, scripted events that occur on the map, and more. Script files are never created nor edited with the Allacrost Map Editor and need to be written entirely by hand. Each script file indicates which map data file it uses, enabling multiple script files to utilize the same data file for different series of events and sequences to occur on a map.

Map Data Files[edit]

All map data files are stored in at lua/data/maps/. Below you will find an example of a small map data file. This page does not explain features of maps such as tile layers and map contexts. If you wish to read more on that

Within it are comment lines that begin with "-- !" that explain various details about the map. These comment lines would not be found in an actual map data file. Any ellipses (...) indicate that much more data would follow here for an actual data file.

File: lua/data/maps/sample_map_name.lua
-- ! This logic wraps the file in a namespace to prevent variable name collisions with other map data files
local ns = {}
setmetatable(ns, {__index = _G})
sample_map_name = ns;
setfenv(1, ns);

-- ! The three strings below are only used in the map editor and are not seen in the game
map_name = "Sample Forest Map"
map_designers = "Tyler Olsen (Roots), Phil Vorsilak (gorzuate)"
map_description = "A small map of a forest region. Contains an a second map context for the forest after a fire burns it to the ground."

-- Length and height are in units of the number of tiles
map_length = 40
map_height = 28
-- ! Maps must have at least one tileset, tile layer, and map context
number_tilesets = 3
number_tile_layers = 2
-- ! The maximum number of contexts a map can have is 32. In practice, most maps will have less than five contexts
number_map_contexts = 2

-- ! Note that these list data structures begin at index 1, not 0. This is done because it is a Lua convention to start tables with 1.
tileset_filenames = {}
tileset_filenames[1] = "lua/data/tilesets/forest.lua"
tileset_filenames[2] = "lua/data/tilesets/burnt_plants.lua"
tileset_filenames[3] = "lua/data/tilesets/grassy_plains.lua"

-- ! Tile layers should be stored in the order that they would typically be drawn. In this example, you would first drawn the "Ground" layer followed by the "Sky" layer.
tile_layer_names = {}
tile_layer_names[1] = "Ground"
tile_layer_names[2] = "Sky"

tile_layer_collision_enabled = {}
tile_layer_collision_enabled[1] = true
tile_layer_collision_enabled[2] = false

map_context_names = {}
map_context_names[1] = "Base"
map_context_names[2] = "Burned Forest"

map_context_inheritance = {}
map_context_inheritance[1] = 0;
map_context_inheritance[2] = 0;

-- ! The collision grid is twice as long and twice as high as the map. This is because each tile has four independent collision quadrants.
-- ! Also note we are using a starting index of 0 here, not 1 like we were with the property tables above
collision_grid = {};
-- ! Each table entry is one row of collision data. The data is formed as a bitmask of the collision data for each map context. 
-- ! In other words, the collision data for all map contexts is stored in this single table
collision_grid[0] = { 0, 0, 1, 0, 3, 2 ... }
collision_grid[55] = { ... }

-- ! This is where the tile information is stored for all map layers and map contexts. The numbers represent tile locations within a tileset
-- ! image. each tileset stores 256 tiles, so the numbers 0-255 correspond to a location of the first tileset, 256-511 the second tileset,
-- ! and so on. A value of -1 indicates no tile is present for this layer/context.
map_tiles = {}
-- ! In this example, we have two layers and two contexts so each entry in the file contains four pieces of data. 
-- ! The first two numbers correspond to the first and second layers for the first context while the second two
-- ! correspond to the second context. 
map_tiles[0][0] = { 127, 284, -1, 55 }
map_tiles[0][1] = { ... }
map_tiles[27][39] = { ... }

Map Script Files[edit]

All map script files are stored in at lua/scripts/maps/. You may see them worded in an odd way, such as "a01_openin_scene.lua". The "a01" indicates that this map script is only meant to take place during the first chapter of the game. Files which do not contain an "a##" prefix are map scripts that are not specific to any point in the story line.

Unlike map data files which are very rigid in their standard, map script files have only a few requirements. If any of this data is missing, the game will not be able to load and execute the map. Below is a sample map script file that contains only these bare essentials. Within it are comment lines that begin with "-- !" that explain various details about the map. These comment lines would not be found in an actual map script file.

File: lua/scripts/maps/a01_example_map.lua
-- a01_example_map.lua
-- This is a script that loads a map containing no objects, sprites, dialogues, 
-- events, or any other data. 

-- ! This logic wraps the file in a namespace to prevent variable name collisions with other map script files
local ns = {}
setmetatable(ns, {__index = _G})
a01_example_map = ns;
setfenv(1, ns);

-- ! The name of the map data file that the script uses
data_file = "lua/data/maps/sample_map_name.lua";
-- ! A map will sometimes have a location graphic displayed for a few seconds as the player enters the map. If the map uses this graphic, the image filename is specified here
location_filename = "img/portraits/locations/blank.png";
-- ! This is the name of the map as the player would see it upon entering the map, or from the party menu or save game screen
map_name = "Example Map";

-- ! This serves as a pointer to the MapMode object that represents all of the map data. It is used throughout the entire file and should never be reassigned once initialized
Map = {};

-- ! Load does exactly that: loads the map and all necessary data needed. It also initializes the state of the map by setting sprites in their positions and so on.
function Load(m)
    Map = m;

    -- ! These are object names that serve as assistant manager classes to the main MapMode class. These should only be initialized in this function and re-used throughout the file.
    ObjectManager = Map.object_supervisor;
    DialogueManager = Map.dialogue_supervisor;
    EventManager = Map.event_supervisor;
    TreasureManager = Map.treasure_supervisor;
    GlobalEvents = Map.map_event_group;

-- ! Called once every game loop to update the state of objects and other map entities. 
function Update()
    -- ! If a map requires no special update operations that the MapMode code doesn't already perform, this function is left blank

-- ! Called once every game loop to draw the map to the screen
function Draw()
    -- ! Some maps only need to draw the standard layers and GUI objects, in which case they only need to invoke this function on the MapMode object

-- ! This is a container for various map event functions. Functions in this container are short and are only called once to change a property of the map, such as toggling a sprite's visibility.
functions = {};

The rest of the file can be designed in whatever way that the user chooses, as any additional functions or variables added are used in either the Load(), Update(), or Draw() functions. But there is nothing to be gained from having each map script written in a different way. Therefore, it is strongly recommended that you follow the format below so that data and functions in each map script are organized in a similar manner to avoid confusion.


Translation Text[edit]

Map files contain user-readable text that require translations into other languages. The map script file holds only the English text. Translations for map text are kept elsewhere and retrieved by the gettext library. You need not concern yourself with how this is done as it is transparent to the script files you will create.