kts.Control

Name

kts.Control – create a new Control

Synopsis

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).

Description

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:

0 (the default) indicates no special properties. The control appears on the Action Menu, in its preferred position (menu_direction) if possible, or in another empty slot otherwise.
1 indicates that the control is "weak". This comes into play when two controls are contending for the same menu position, one of the controls is "weak", and the other is not. In that case, the "weak" control is not shown (it is overridden by the "stronger" control).
- An example of where this is useful is with the "open door" and "use lockpicks" controls. Both want to use the north/top menu position. But if both are possible, we only want to show "use lockpicks" (we don't want to show "open door" because it is useless and will just show a "Locked" message). To achieve this, we set the "open door" control to be weak (menu_special = 1).
4 indicates that the control should not appear on the Action Menu at all. (It can still appear on the Action Bar, as that is controlled by a different setting.)

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

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.

Notes

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

Examples

TODO