Document api.lua

api.lua

@@ -45,11 +45,9 @@ local function is_value_in_table(tbl, val)
 	return false
 end
 
------------------------
+----------------------------
--- Utility Functions --
+-- Registration Functions --
------------------------
+----------------------------
-
--- Movement Methods --
 
 creatura.registered_movement_methods = {}
 
@@ -57,15 +55,47 @@ function creatura.register_movement_method(name, func)
 	creatura.registered_movement_methods[name] = func
 end
 
--- Utility Behaviors --
-
 creatura.registered_utilities = {}
 
 function creatura.register_utility(name, func)
 	creatura.registered_utilities[name] = func
 end
 
--- Sensors --
+---------------
+-- Utilities --
+---------------
+
+function creatura.is_valid(mob)
+	if not mob then return false end
+	if type(mob) == "table" then mob = mob.object end
+	if type(mob) == "userdata" then
+		if mob:is_player() then
+			if mob:get_look_horizontal() then return mob end
+		else
+			if mob:get_yaw() then return mob end
+		end
+	end
+	return false
+end
+
+function creatura.is_alive(mob)
+	if not creatura.is_valid(mob) then
+		return false
+	end
+	if type(mob) == "table" then
+		return mob.hp > 0
+	end
+	if mob:is_player() then
+		return mob:get_hp() > 0
+	else
+		local ent = mob:get_luaentity()
+		return ent and ent.hp and ent.hp > 0
+	end
+end
+
+------------------------
+-- Environment access --
+------------------------
 
 local default_node_def = {walkable = true} -- both ignore and unknown nodes are walkable
 
@@ -323,36 +353,6 @@ function creatura.sensor_ceil(self, range, water)
 	return dist, node
 end
 
--- Misc
-
-function creatura.is_valid(mob)
-	if not mob then return false end
-	if type(mob) == "table" then mob = mob.object end
-	if type(mob) == "userdata" then
-		if mob:is_player() then
-			if mob:get_look_horizontal() then return mob end
-		else
-			if mob:get_yaw() then return mob end
-		end
-	end
-	return false
-end
-
-function creatura.is_alive(mob)
-	if not creatura.is_valid(mob) then
-		return false
-	end
-	if type(mob) == "table" then
-		return mob.hp > 0
-	end
-	if mob:is_player() then
-		return mob:get_hp() > 0
-	else
-		local ent = mob:get_luaentity()
-		return ent and ent.hp and ent.hp > 0
-	end
-end
-
 function creatura.get_nearby_player(self)
 	local objects = minetest.get_objects_inside_radius(self:get_center_pos(), self.tracking_range)
 	for _, object in ipairs(objects) do
@@ -375,7 +375,7 @@ function creatura.get_nearby_players(self)
 	return nearby
 end
 
-function creatura.get_nearby_entity(self, name)
+function creatura.get_nearby_object(self, name)
 	local objects = minetest.get_objects_inside_radius(self:get_center_pos(), self.tracking_range)
 	for _, object in ipairs(objects) do
 		if creatura.is_alive(object)
@@ -388,7 +388,7 @@ function creatura.get_nearby_entity(self, name)
 	return
 end
 
-function creatura.get_nearby_entities(self, name)
+function creatura.get_nearby_objects(self, name)
 	local objects = minetest.get_objects_inside_radius(self:get_center_pos(), self.tracking_range)
 	local nearby = {}
 	for _, object in ipairs(objects) do
@@ -402,12 +402,13 @@ function creatura.get_nearby_entities(self, name)
 	return nearby
 end
 
+creatura.get_nearby_entity = creatura.get_nearby_object
+creatura.get_nearby_entities = creatura.get_nearby_objects
+
 --------------------
 -- Global Mob API --
 --------------------
 
--- Drops --
-
 function creatura.drop_items(self)
 	if not self.drops then return end
 	for i = 1, #self.drops do
@@ -432,8 +433,6 @@ function creatura.drop_items(self)
 	end
 end
 
--- On Punch --
-
 function creatura.basic_punch_func(self, puncher, time_from_last_punch, tool_capabilities, direction, damage)
 	if not puncher then return end
 	local tool = ""

doc.txt

@@ -136,5 +136,81 @@ Lua Entity Methods
 -- returns itemstack, item name of `player`s wielded item if item is in 'follow'
 
 `get_target(target)`
--- returns if `target` is alive, if mob has a line of sight with `target`, `target`s position
+-- returns if `target` is alive, if mob has a line of sight with `target`, position of `target`
 
+Utilities
+---------
+
+* `creatura.is_valid(mob)`
+	* Returns false if object doesn't exist, otherwise returns ObjectRef/PlayerRef
+	* `mob`: Luaentity, ObjectRef, or PlayerRef
+
+* `creatura.is_alive(mob)`
+	* Returns false if object doesn't exist or is dead, otherwise returns ObjectRef/PlayerRef
+	* `mob`: Luaentity, ObjectRef, or PlayerRef
+
+Environment access
+------------------
+
+* `creatura.get_node_height_from_def(name)`
+	-- Returns total height of nodebox
+	-- `name`: Itemstring/Name of node
+
+
+* `creatura.get_node_def(node)`
+	-- Returns definition of node
+	-- `node`: Itemstring/Name of node or position
+
+* `creatura.get_ground_level(pos, max_diff)`
+	* Returns first position above walkable node within `max_diff`
+
+* `creatura.is_pos_moveable(pos, width, height)`
+	* Returns true if a box with specified `width` and `height` can fit at `pos`
+	* `width` should be the largest side of the collision box
+	* Check from bottom of box
+
+* `creatura.fast_ray_sight(pos1, pos2, water)`
+	* Checks for line of sight between `pos1 and `pos2`
+	* Returns bool
+	* Returns distance to obstruction
+
+* `creatura.sensor_floor(self, range, water)`
+	* Finds distance to ground from bottom of entities hitbox
+	* Returns distance to ground or `range` if no ground is found
+	* `range`: Maximum range
+	* `water`: If false, water will not be counted as ground 
+
+* `creatura.sensor_ceil(self, range, water)`
+	* Finds distance to ceiling from top of entities hitbox
+	* Returns distance to ceiling or `range` if no ceiling is found
+	* `range`: Maximum range
+	* `water`: If false, water will not be counted as ceiling
+
+* `creatura.get_nearby_player(self)`
+	* Finds player within `self.tracking_range`
+	* Returns PlayerRef or nil
+
+* `creatura.get_nearby_players(self)`
+	* Finds players within `self.tracking_range`
+	* Returns table of PlayerRefs or empty table
+
+* `creatura.get_nearby_object(self, name)`
+	* Finds object within `self.tracking_range`
+	* Returns ObjectRef or nil
+	* `name`: Name of object to search for
+
+* `creatura.get_nearby_objects(self, name)`
+	* Finds objects within `self.tracking_range`
+	* Returns table of ObjectRefs or empty table
+	* `name`: Name of object to search for
+
+Global Mob API
+--------------
+
+* `creatura.drop_items(self)`
+	* Drops items from `self.drops`
+
+* `creatura.basic_punch_func(self, puncher, time_from_last_punch, tool_capabilities, direction, damage)`
+	* Deals damage
+	* Applies knockback
+	* Visualy and audibly indicates damage