kts.LoadSegments

Name

kts.LoadSegments – load map segments

Synopsis

segments = kts.LoadSegments(tile_table, filename)

Description

This function loads a list of map segments from a text file. For a description of what a map segment is, see kts.LayoutDungeon.

The parameters are as follows:

The first parameter is a table mapping tile numbers (integers) to Tile objects.
The second parameter is a filename corresponding to a text file containing map segments.

The text file format is not fully documented, but we give some examples (along with some commentary) in the "Examples" section below.

Return Value

The result is a list (Lua table) containing userdata objects; each userdata represents one segment from the file.

Errors

Errors may occur if there is an error in the file format or if the function parameters are incorrect.

Notes

There used to be a map editor program, which allowed editing the segment files with a mouse-based interface, but unfortunately it does not work any more. The code is still available on the Knights archives page in case anyone wants to try getting it to work again.

Examples

The code for loading the standard Knights segments is found in segments.lua and the map segments themselves can be found in standard_rooms.txt, gnome_rooms.txt, liche_tombs.txt, guarded_exits.txt and special_pentagrams.txt.

A simple example of a segment (the first one in standard_rooms.txt) is as follows:

segment
name: C01.1
width: 12
height: 12
data:
13  2 27 66 66 66  8 75 74 75 74 75 
82  2 66 66 66 66  2 74 75 74 75 74 
82  2 66 66 40 72  2 44 74 75 74 75 
81 85 67 66 42 66  2 43 43 74 43 43 
 2  2 59 66 66 66  2 75 74 75 74 27 
 2  2  2  2  2  7  2 74 75 74 75 74 
15 66 66 66  2 66  2 75 74 75 74 75 
66 79 79 66  2 69  2 74 75 74 75 74 
66 79 79 44  2 66  2  2  2  2  7  2 
66 79 79 66  2 66  8 66 67 66 66 28 
66 79 79 66  2 66  2  2 84  2  2  2 
66 66 66 66  8 66  2  2 81 83 83 14 
rooms:
7
0 1 3 5 
2 0 6 7 
7 0 7 10 
0 6 6 8 
5 6 3 8 
7 9 7 3 
8 11 5 3 
end

Here, width and height give the size of the segment (in this case 12x12; in fact all standard dungeon segments have this size). The data section then gives the 12x12 array of map tiles; the numbers correspond to the provided tile_table in the kts.LoadSegments call. Finally, the rooms section gives the positions of the top-left corner of each dungeon room as well as each room's width and height.

Note that all segments passed to kts.LayoutDungeon must be the same size, or the dungeon generator will not work. In practice, therefore, unless you are entirely replacing all the standard segments with new ones, then you will have to make sure any new segments you design have the same size as the standard ones (i.e. 12x12).

A more complicated segment, with switch effects, is as follows (this is one of the "gnome book" rooms):

segment
name: Z03.3
width: 12
height: 12
data:
79 79  3 16  2 26 66 66 66 66  8 66 
79 79 17 50  2  2  2  7  2  2  2 66 
79 79 17 66  2 66 17 66 32 27  2 66 
79 79  3 16  2 16  2 66 66 66  8 66 
79 79 17 66  2 66  2 18 72 18  2  7 
79 79  3 16  2 16  2 18 66 18  2 70 
79 79 17 66 17 66  2 18 66 18  2  7 
 2  7  2  2  2  2  2 18 72 18  2 66 
66 66  2 27 24 24  2 18 66 18  2 66 
66 66  8 66 24 24  2 18 59 18  2 66 
66 66  2 66 66 66  2  2  7  2  2  7 
66 66  2 66 66 66  8 66 66 66 66 66 
switches:
12
7 4 1 shoot 3 1 -2 3
9 4 1 shoot 3 -1 -2 3
7 5 1 shoot 3 1 -3 3
9 5 1 open 2 -3 -3
7 6 1 open 2 -2 -3
9 6 1 open 2 -4 -1
7 7 1 open 2 -3 -1
9 7 1 shoot 3 -1 -5 3
7 8 1 shoot 3 1 -6 3
9 8 1 open 2 -6 -3
7 9 1 open 2 -4 -6
9 9 1 shoot 3 -1 -7 3
rooms:
12
0 0 6 9 
5 0 7 3 
11 0 3 6 
7 2 5 10 
0 8 4 6 
3 8 5 6 
7 11 7 3 
11 7 3 5 
11 5 3 3 
5 2 3 3 
5 4 3 3 
5 6 3 3 
end

Here, an additional switches section can be seen. Each switch has an x,y position (which can correspond either to an actual lever that knights have to pull, or just a pressure plate that they can walk onto), a "number of functions" (usually 1 but not always), and then a description of each function that is triggered by the switch. Each function has a name (in this case shoot or open), a number of arguments (in this case 3 for shoot or 2 for open), and then the arguments themselves as numbers. The function names correspond to Lua code but rf_ has to be added (at the front) to get the Lua function name. For example, the line shoot 3 1 -2 3 makes the Lua call rf_shoot(1, -2, 3) when the switch is triggered. The rf_ functions themselves are defined in tile_funcs.lua.

A final example of a segment can be found in tutorial_map.txt. This file defines just one "segment" for the entire Knights Tutorial map. Note that this is an exception to the usual rule that segments must be 12x12 in size; in fact, this one is 39x37. The Tutorial can get away with this because it is only passing one segment (the complete tutorial map) to the kts.LayoutDungeon call, and therefore, there is no need to "match" the size of this segment to the standard dungeon segments (or any other segments). A similar technique could potentially be used if someone wanted to create a fixed (i.e. not randomly generated) Knights map for some special purpose.