Docs Quick code

Finding things in the world

nearest, objects_near, line of sight, raycasts, ground tiles and walking paths.

Positions in code are in tiles: x and z along the ground, y in height levels. A position can be given as an object or as a vector vec(x, y, z).

#Nearest and nearby

local foe = nearest("enemy")                  -- the closest object tagged enemy (to self)
local thing = nearest("any", player)          -- the closest object to the player
for o in objects_near(self, 5, "coin") do     -- within 5 tiles, nearest first
  o.remove()
end

Function	Gives
`nearest(tag, from = self)`	The closest object with that tag (not `from` itself), or `nil`. `"any"` = any object but the ground; `"player"` = the player.
`objects_near(where, radius, tag = "any")`	The objects within `radius` tiles, nearest first.
`distance(a, b)`	Tiles between two objects or positions.
`angle_to(from, to)`	The direction (degrees) to face from one to the other.

#Seeing and pointing

if line_of_sight(self, player) then
  self.say("I see you!")
end

local hit = raycast(self, vec(0, 0, -1), 12)   -- straight ahead (-Z), up to 12 tiles
if hit ~= nil and hit.object ~= nil then
  hit.object.hurt(10)
end

Function	Gives
`line_of_sight(a, b)`	`true` if nothing solid is between two objects or positions (the two themselves don't count).
`raycast(from, direction, distance = 20)`	What a line hits first, as a table — `hit.object` (the object or block it hit; `nil` for the level's floor), `hit.position` (where), `hit.tile` (the tile just in front of the hit) — or `nil` if it hits nothing. `from` itself is never hit.
`mouse_tile()`	The tile under the mouse, or `nil` (see Input).

#Ground tiles

Whole blocks of the level (grass, dirt, stone… one tile big) can be read and changed:

if tile_at(4, 0, 7) == "Water block" then popup("Splash!") end
set_tile(4, 0, 7, "Stone block")     -- by the model's name (or id)
clear_tile(5, 1, 7)                  -- dig it out

Function	Does
`tile_at(x, level, z)`	The name of the model of the block there (`""` if empty).
`set_tile(x, level, z, model)`	Puts a block there (replacing what was there).
`clear_tile(x, level, z)`	Removes the block there.

#Paths

local route = path_to(self, player)    -- a list of tile vectors, the start and end included
for step in route do
  self.move_to(step.x, step.y, step.z, 0.3)
end

path_to(from, to) walks around solid things on the level's walking grid (as the level was built — blocks you place or dig in code aren't in it). It gives an empty list when there's no way.