kts.Attractor – teleport a random other knight to my room
kts.Attractor()
This function teleports a random other knight to the current actor's room.
In other words: If the current actor (as defined by cxt.actor) is a knight, then a random other knight is chosen, and that knight is teleported to a randomly chosen unoccupied square in the current knight's room. If the current actor is some other type of creature, then a random knight is chosen (from among all the knights in the dungeon) and teleported to this creature's room.
If no (other) knights exist (e.g. if the actor is the only knight in a single-player game) then the current actor is teleported to a random dungeon square instead. (This is the only case in which the current actor, as opposed to some other knight, will be teleported by this function.)
None.
No errors can be raised by this function.
The teleportation can fail (e.g. because the current room is already full with knights or other creatures, so there is no space for the new knight to arrive), but in this case no Lua error is raised – instead, nothing happens and the actor stays where they currently are.
This function can also fail if cxt.actor is not a valid creature, but again in that case, no error is raised, and instead the function just does nothing.
This function is mainly intended to be used from item or tile effects (e.g. the on_pick_up function of an ItemType).
No sound effects or visual effects are performed by this function – if those are required, they must be done separately.
Scrolls use this function (as one of their possible effects); try searching for my_attractor in the standard Knights Lua files to see how this works.