kts.Secure – "secure" a Home tile, preventing other knights from using it
success, reason = kts.Secure(wall_tile)
This function "secures" a home, making it unusable as an entry point by any knight, other than the knight who secured it.
If two different players (from different teams) secure the same home, then the home is removed, and turned into a copy of wall_tile (the parameter to this function), instead. The parameter must therefore be a valid Tile object.
This function does not take any parameters indicating which knight is doing the securing or which home is being secured. Instead, the game looks at the cxt table, and specifically the actor field, to determine which knight is acting, and then looks at the position one square "ahead" of that knight to look for a home to secure. This function is therefore best called from one of the item or tile callback functions, such as melee_action in ItemType, as the cxt table will already be correctly set up in such cases.
On success, there is exactly one return value which is true.
On failure, two values are returned. The first value is false and the second value is one of the following strings:
"not_a_home": There is no home tile in front of the knight currently. "already_secure": The home tile is already secured by this knight. "special_exit": The home tile is a special exit point (e.g. an exit point associated with a "Guarded" exit). These homes cannot be secured, nor can they be used as normal entry points by knights. "invalid": The call was invalid, e.g. the cxt.actor field was not set, or it was not pointing to a valid knight. If the input parameter is not a tile, then a Lua error is raised.
Historical note: Earlier versions of Knights would allow players to respawn at the "special_exit" point, if their previous entry point was secured, but this led to comical situations where a player would respawn at the Guarded Exit without having the key to get out – so therefore would be stuck there forever (or at least until another player came and "released" them). This was changed at some point to the current behaviour, where "special_exits" can neither be secured, nor used as spawn points by knights.
This function is called from the melee_action of the Wand of Securing ItemType, in order to implement the special effect of that wand. See items.lua.