kts.DropHeld – drop the actor's held item
kts.DropHeld()
result = kts.Can_DropHeld()
If the current actor (given by cxt.actor) is a knight, who is carrying an item in hand, then the item will be dropped.
If the knight is approaching a square (such as a table or open chest), then the item will be dropped into that square if possible. If it is not possible, e.g. because there is already an item there, or because the tile is something like a closed chest or door that blocks items, then nothing happens – in particular, the item is not dropped into an adjacent square in this case. (This rule prevents knights from accidentally dropping their weapon when they instead intended to open a chest or something similar.)
If the knight is not approaching a square, then the item will be dropped either onto the current square, or one of the four adjacent squares, as appropriate. (If none of those five squares are able to receive the item, then nothing happens and the drop fails.)
The function kts.Can_DropHeld() returns true if the actor (given by cxt.actor) is a knight able to drop their currently held item, or false otherwise.
kts.DropHeld() returns nothing, and kts.Can_DropHeld() returns a boolean as described above.
The default item (as set by kts.DEFAULT_ITEM), which is usually the sword, can never be dropped; attempting to drop it using this function will fail (and kts.Can_DropHeld will return false in that case).
To drop items that are not held in hand (such as gems or bolts), use kts.Drop.
kts.DropHeld and kts.Can_DropHeld are usually used as the action and possible functions (respectively) of a Control.
The standard "Drop" control (which is available on the action menu, or is the default "tap button" action in many cases) uses kts.DropHeld; see controls.lua.