kts.Tile

Name

kts.Tile – create a new Tile

Synopsis

tile =
    kts.Tile { 
        type = <"", "home", "door", "chest" or "barrel">,

        -- For all tile types:
        access = <access table (see below)>,
        connectivity_check = <integer>,
        control = <control or function>,
        depth = <integer>,
        graphic = <graphic>,
        hit_points = <function or integer>,
        items = <see description below>,
        on_activate = <function>,
        on_approach = <function>,
        on_destroy = <function>,
        on_hit = <function>,
        on_walk_over = <function>,
        on_withdraw = <function>,
        stairs_down = <"special", "north", "south", "east", "west">,
        tutorial = <integer>,
        map_as = <"wall", "floor">,

        -- For type = "home":
        facing = <"north", "south", "east", "west">,
        special_exit = <boolean>,
        unsecured_colour = <integer>,

        -- For type = "door" or "chest":
        open = <boolean>,
        open_graphic = <graphic>,
        lock_chance = <number between 0.0 and 1.0>,
        lock_pick_only_chance = <number between 0.0 and 1.0>,
        keymax = <integer>,
        special_lock = <boolean>,
        on_open_or_close = <function>,
        on_unlock_fail = <function>,

        -- Additionally for type = "chest":
        facing = <"north", "south", "east", "west">,
        trap_chance = <number between 0.0 and 1.0>,
        traps = <function>
    }

where:

<access table> = {
    "flying" = <access type>,
    "missiles" = <access type>,
    "walking" = <access type>
}

<access type> = nil, "approach", "partial", "blocked", "clear"

All fields listed above also accept nil as a valid value.

Description

A "Tile" is an object representing the "terrain" within a particular square of the dungeon. A Tile might therefore represent a wall, a piece of floor, a treasure chest, etc. A given dungeon square can contain more than one Tile, for example a treasure chest tile might be overlaid on top of a floor tile.

The kts.Tile function creates a new Tile. The function takes one parameter, a table, which contains various properties that the new Tile should have. These are as follows:

Return Value

The new Tile (a Lua userdata object) will be returned.

Errors

There are several different errors that can be generated if any of the input parameters are incorrect.

Notes

Connectivity check

(This section gives a detailed description of how the connectivity_check setting works.)

(TODO: this should probably be moved to the kts.ConnectivityCheck page, when that is written.)

When a new game of Knights is started, a dungeon is randomly generated by stitching map segments together, and inserting random doors between segments. Items are then dropped into random locations. This might, in some cases, result in an "impossible" layout, for example, if there is a locked iron door, and the only key (or lock pick) that can open it, is on the inside of the locked room.

In order to avoid this situation, the dungeon generator runs a "connectivity check", which is essentially a flood fill, starting from each knight's entry point. The fill will pass through tiles that are considered "passable" by knights (such as floor tiles). Locked doors are considered passable only if the flood fill has reached an appropriate key (or lock picks). If this flood fill does not reach all keys (or lockpicks), then the dungeon is considered "impossible", and extra lockpicks are spawned at an appropriate location, to avoid the problem.

What has this got to do with Tile settings? Well, the dungeon generator decides whether a tile is passable by a knight, by considering the following:

These heuristics are usually correct, but sometimes need to be overridden. For example, the default Knights data files set "pit" tiles to have access = clear, but then kill the knight (in the on_walk_over function) if any knight walks into the pit. The above heuristic would mark a pit as being "passable" (on the grounds that access is clear) but this would not be accurate. Therefore, pits set connectivity_check = -1 to make sure that the dungeon generator treats open pits the same as walls, for the purpose of the connectivity check.

The other case where an override is needed is in the "closed gate" tiles. Under the final bullet point above, these would be treated as passable, on the assumption that there is a switch somewhere that opens them, however, this is not always the case – some gates are not openable at all. Therefore, gates also have connectivity_check = -1 in the data files.

Examples

A simple floor tile:

floor = kts.Tile {
    access = {
        walking = "clear",
        flying = "clear",
        missiles = "clear"
    },
    items = "floor",
    graphic = my_floor_graphic
}

A treasure chest:

chest = kts.Tile {
    type = "chest",

    graphic = my_graphic,   -- previously created by calling kts.Graphic
    open_graphic = my_open_graphic,
    facing = "north",
    depth = -4,

    items = "chest",
    access = {
        walking = "approach",
        flying = "clear",
        missiles = "clear"
    },
    trap_chance = 0.5,
    traps = function(pos, dir)
        if kts.RandomChance(0.5) then
            kts.SetPoisonTrap(pos, poison_trap_item)
        else
            kts.SetBladeTrap(pos, blade_trap_item, bolt_item, dir)
        end
    end,
    lock_chance = 0.5,
    lock_pick_only_chance = 0.16667,
    keymax = 3,
    hit_points = function() return kts.RandomRange(1, 20) end,
    control = my_control,  -- previously created by calling kts.Control

    -- Not shown here:
    -- functions on_open_or_close, on_unlock_fail, on_hit,
    -- which would typically play sound effects and/or show messages.
}

See Also

kts.Activate

kts.AddItem

kts.AddStuff

kts.CloseDoor

kts.Control

kts.Graphic

kts.IsDoorOpen

kts.ItemType

kts.LoadSegments

kts.LockDoor

kts.OpenDoor

kts.OpenOrCloseDoor

kts.SetBladeTrap

kts.SetPoisonTrap