kts.Control – create a new Control


result = kts.Control{
    action = <function>,
    action_bar_slot = <integer>,
    action_bar_priority = <integer>,
    can_do_while_moving = <boolean>,
    can_do_while_stunned = <boolean>,
    continuous = <boolean>,
    menu_direction = <"north", "south", "east" or "west">,
    menu_icon = <graphic>,
    menu_special = <integer>,
    name = <string>,
    possible = <function>,
    suicide_key = <boolean>,
    tap_priority = <integer>

All fields are optional – if they are omitted, suitable defaults will be used (see below for details).


Creates a new Control. A Control represents a possible "command" or "input" that a player can give to the game – for example, "move to the left", "open door", or "attack".

This function takes one parameter which must be a table with the following fields:

action is a function to be called when the user selects this Control. The action function receives no arguments, and the game ignores any value returned from it. During the call, the cxt global variable will be available.

action_bar_slot (if non-nil) specifies the position of the control on the Action Bar (in the new control system). Slots are numbered 0 to 9 (from left to right). Note that controls only appear on the action bar if they are possible (see below). If nil (or omitted), the control does not appear on the action bar at all.

action_bar_priority determines which control is displayed on the Action Bar, in the case where two or more controls are currently possible, and both are occupying the same slot. The higher priority value "wins". If this is not specified then it will be the same as tap_priority.

can_do_while_moving and can_do_while_stunned are boolean values that determine whether the control can be selected while the knight is moving, and while they are stunned, respectively. (If omitted, these default to false.)

If continuous is true then the control can be "held down" to activate it continuously. For example, this applies to attacking with a sword, throwing daggers, or picking locks. (If omitted, this defaults to false.)

menu_direction determines where the control will appear on the Action Menu (i.e. the menu that appears when the button is held down in the original Knights control system). Note that controls only appear in the menu when they are possible (see below). If nil (or omitted), the default is "north". (If you don't want the control to appear on the menu at all, use menu_special; see below.)

menu_icon indicates the Graphic that will be used if the control is to be displayed on either the Action Bar or the menu.

menu_special allows finer control over the Action Menu behaviour. It can be set to one of the following values:

name is a name for the control. This will appear when the control is "moused over" in the new control system.

possible is a function which the game will call to determine whether the control is usable in the current situation. The possible function receives no arguments, and should return true if the control is usable, or false otherwise. (The cxt table will be available during the call.) Controls which are not currently possible will not be shown in the Action Bar or Action Menu. If possible is nil (or omitted) then the control is considered possible always.

If suicide_key is true then this control will be activated when the player's "suicide key" is pressed. The default is false.

If tap_priority is specified then the control can be activated simply by tapping the appropriate key. For example, doors can be opened by tapping, rather than having to use the action bar or menu. If multiple controls are available for "tapping" then the one with the highest tap_priority "wins".

Return Value

The new Control (a Lua userdata object) is returned.


Errors may be raised if any of the input parameters are incorrect.

This function is intended to be called during setup only – if called during a game, an error will result.


When specifying directions, the strings "up", "down", "left" and "right" may be used as alternatives to "north", "south", "east" and "west".



See Also