doc.txt

Registration
------------

creatura.register_mob(name, mob definition)

Mob Definition uses almost all entity definition params

{
	max_health = 10 -- Maximum Health
	damage = 0 -- Damage dealt by mob
	speed = 4 -- Maximum Speed
	tracking_range = 16 -- Maximum range for finding entities/blocks
	despawn_after = 1500 -- Despawn after being active for this amount of time

	max_fall = 8 -- How far a mob can fall before taking damage (set to 0 to disable fall damage)
	turn_rate = 7 -- Turn Rate in rad/s
	bouyancy_multiplier = 1 -- Multiplier for bouyancy effects (set to 0 to disable bouyancy)
	hydrodynamics_multiplier = 1 -- Multiplier for hydroynamic effects (set to 0 to disable hydrodynamics)

	hitbox = { -- Hitbox params (Uses custom registration to force get_pos() to always return bottom of box)
		width = 0.5, (total width = width * 2. A width of 0.5 results in a box with a total width of 1)
		height = 1 (total height of box)
	}

	animations = {
		anim = {range = {x = 1, y = 10}, speed = 30, frame_blend = 0.3, loop = true}
	}

	drops = {
		{name = (itemstring), min = 1, max = 3, chance = 1},
	}
	follow = {
		"farming:seed_wheat",
		"farming:seed_cotton"
	}

	utility_stack = {
		-- Every second, all utilities in the stack are evaluated
		-- Whichever utilitiy's get_score function returns the highest number will be executed
		-- If multiple utilities have the same score, the one with the highest index is executed
		[1] = {
			`utility` -- name of utility to evaluate
			`get_score` -- function (only accepts `self` as an arg) that returns a number
		}
	}

	activate_func = function(self, staticdata, dtime_s) -- called upon activation
	step_func = function(self, dtime, moveresult) -- called every server step
	death_func = function(self) -- called when mobs health drops to/below 0
}

Lua Entity Methods
------------------

`move(pos, method, speed, animation)`
- `pos`: position to move to
- `method`: method used to move to `pos`
- `speed`: multiplier for `speed`
- `animation`: animation to play while moving

`halt()`
- stops movement

`turn_to(yaw[, turn_rate])`
- `yaw`: yaw (in radians) to turn to
- `turn_rate`: turn rate in rad/s (default: 10) -- likely to be deprecated

`set_gravity(gravity)`
- `gravity`: vertical acceleration rate

`set_forward_velocity(speed)`
- `speed`: rate in m/s to travel forward at

`set_vertical_velocity(speed)`
- `speed`: rate in m/s to travel vertically at

`apply_knockback(dir, power)`
- `dir`: direction vector
- `power`: multiplier for dir

`punch_target(target)`
- applies 'damage' to 'target'

`hurt(damage)`
- `damage`: number to subtract from health (ignores armor)

`heal(health)`
- `health`: number to add to health

`get_center_pos()`
- returns position at center of hitbox

`pos_in_box(pos[, size])`
- returns true if 'pos' is within hitbox
- `size`: width of box to check in (optional)

`animate(anim)`
- sets animation to `anim`

`set_texture(id, tbl)`
- `id`: table index
- `tbl`: table of textures

`set_scale(x)`
- `x`: multiplier for base scale (0.5 sets scale to half, 2 sets scale to double)

`fix_attached_scale(parent)`
- sets scale to appropriate value when attached to 'parent'
- `parent`: object

`memorize(id, val)`
-- stores `val` to staticdata
- `id`: key for table
- `val`: value to store

`forget(id)`
-- removes `id` from staticdata

`recall(id)`
-- returns value of `id` from staticdata

`timer(n)`
-- returns true avery `n` seconds

`get_hitbox()`
-- returns current hitbox

`get_height()`
-- returns current height

`get_visual_size()`
-- returns current visual size

`follow_wielded_item(player)`
-- 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`, 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.default_water_physics(self)`
	* Bouyancy and Drag physics used by default on all Mobs

* `creatura.default_vitals(self)`
	* Vitals used by default on all Mobs
	* Handles suffocation, drowning, fire damage, and fall damage

* `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

Pathfinding
-----------

Creatura's pathfinder uses the A* algorithm for speed, as well as Theta* for decent performance and more natural looking paths.

Both pathfinders will carry out pathfinding over multiple server steps to reduce lag spikes which does result in the path not
being returned immediately, so your code will have to account for this.

The maximum amount of time the pathfinder can spend per-step (in microseconds) can be adjusted in settings.
	

* `creatura.pathfinder.find_path(self, pos1, pos2, get_neighbors)`
	* Finds a path from `pos1` to `pos2`
	* `get_neighbors` is a function used to find valid neighbors
		* `creatura.pathfinder.get_neighbors_fly` and `creatura.pathfinder.get_neighbors_swim` are bundled by default


* `creatura.pathfinder.find_path_theta(self, pos1, pos2, get_neighbors)`
	* Finds a path from `pos1` to `pos2`
	* Returns a path with arbitrary angles for natural looking paths at the expense of performance
	* `get_neighbors` is a function used to find valid neighbors
		* `creatura.pathfinder.get_neighbors_fly` and `creatura.pathfinder.get_neighbors_swim` are bundled by default

Spawning
--------

NOTE: Globalstep spawning from early versions of the API likely won't recieve much/any support going forward. Use ABM Spawning instead.

* `creatura.register_abm_spawn(name, def)`
	* `name` of the mob to spawn
	* `def` is a table of spawn parameters
			* `chance` is the chance of a mob spawning every `interval`
				* (a `chance` of 30 and `interval` of 60 would mean a 1 in 30 chance of a mob spawning every 60 seconds)
			* `chance_on_load` same as `chance` but for LBM spawning (when a chunk is loaded for the first time)
			* `interval` is how often (in seconds) a spawn attempt will happen
			* `min_height` is the minimum height that a spawn attempt can happen at
				* a `min_height` of 0 would mean the mob cannot spawn below a y coordinate of 0
			* `max_height` is the maximum height that a spawn attempt can happen at
				* a `max_height` of 128 would mean the mob cannot spawn above a y coordinate of 128
			* `min_time` is the minimum time a mob can spawn at
			* `max_time` is the maximum time a mob can spawn at
				* set `min_time` to 19500 and `max_time` to 4500 to only spawn at night and swap the numbers to only spawn at day
			* `min_light` is the minimum light level a mob can spawn at
			* `max_light` is the maximum light level a mob can spawn at
			* `min_group` is the lowest number of mobs to spawn in a group at a time
				* value of 3 means the mob will always spawn with at least 3 mobs together
			* `max_group` is the highest number of mobs to spawn in a group at a time
			* `block_protected` will block spawning mobs in protected areas if set to true
			* `biomes` is a table of biomes the mob can spawn in
			* `nodes` is a table of nodes the mob can spawn in/on
			* `neighbors` is a table of nodes that must be adjacent to the spawn position
				* ex: set to `{"groups:tree"}` to force the mob to spawn next to a tree
			* `spawn_on_load` will spawn mobs when a chunk generates if set to true
			* `spawn_in_nodes` will spawn mobs inside the node rather than above if set to true
				* set this to true for mobs that spawn in water
			* `spawn_cap` is the maximum amount of the mob that can spawn within active block range