Entity Lua API

docs/index.md

@@ -3,13 +3,14 @@
 - [C++ classes in Lua](lua-api-cpp.md)
 - [Core API](lua-api-core.md)
 - [Mod API](lua-api-mod.md)
+    - [Biome](lua-api-biome.md)
     - [Block](lua-api-block.md)
+    - [Dimension](lua-api-dimension.md)
+    - [Entity](lua-api-entity.md)
     - [Item](lua-api-item.md)
     - [Recipe](lua-api-recipe.md)
     - [Sky](lua-api-sky.md)
     - [Tree](lua-api-tree.md)
-    - [Biome](lua-api-biome.md)
-    - [Dimension](lua-api-dimension.md)
 - [GUI API](lua-api-gui.md)
     - [Crafting widget](lua-api-gui-crafting.md)
     - [Image](lua-api-gui-image.md)

docs/lua-api-core.md

@@ -18,11 +18,11 @@ Adds a listener to a specific type of event.
 
 Example:
 ```lua
-openminer:add_listener(EventType.OnBlockPlaced, function(pos, player, world, client, server)
+openminer:add_listener(EventType.OnBlockPlaced, function(pos, block, player, world, client, server)
 	server:send_chat_message(0, "Block placed at " .. pos.x .. ";" .. pos.y .. ";" .. pos.z .. " by Client" .. player:client_id(), client);
 end)
 
-openminer:add_listener(EventType.OnBlockDigged, function(pos, player, world, client, server)
+openminer:add_listener(EventType.OnBlockDigged, function(pos, block, player, world, client, server)
 	server:send_chat_message(0, "Block digged at " .. pos.x .. ";" .. pos.y .. ";" .. pos.z .. " by Client" .. player:client_id(), client);
 end)
 
@@ -35,7 +35,7 @@ end)
 
 Possible events:
 
-- `OnBlockPlaced`: `funcion(pos, player, world, client, server)`
-- `OnBlockDigged`: `funcion(pos, player, world, client, server)`
+- `OnBlockPlaced`: `funcion(pos, block, player, world, client, server)`
+- `OnBlockDigged`: `funcion(pos, block, player, world, client, server)`
 - `OnBlockActivated`: `function(pos, block, player, world, client, server)`
 

docs/lua-api-cpp.md

@@ -10,6 +10,7 @@
 - `string label()`
 - `string mod_name()`
 - `bool is_opaque()`
+- `ItemStack get_item_drop()`
 
 ## BlockData
 
@@ -39,6 +40,17 @@
 
 - `u16 id()`
 
+## Dimension
+
+- `u16 id()`
+
+## EntityWrapper
+
+- `entt::entity id()`
+- `PositionComponent *position()`
+- `NetworkComponent *network()`
+- `ItemStack *item_stack()`
+
 ## Inventory
 
 - `void add_stack(string name, u16 amount)`
@@ -49,8 +61,8 @@
 
 - `u16 id()`
 - `string name()`
-- `u16 burn_time()`
-- `bool is_fuel()`
+- `bool has_group(string groupName)`
+- `u16 get_group_value(string groupName)`
 
 ## ItemStack
 
@@ -107,6 +119,14 @@
 
 - `LuaMod *register_mod(string mod_id)` (see [Lua Mod API](/lua-api-mod#example))
 
+## ServerPlayer
+
+- `const ClientInfo &client()`
+
+## ServerWorld
+
+- `u16 dimension()`
+
 ## World
 
 - `u16 get_block(int x, int y, int z)`

docs/lua-api-entity.md

@@ -0,0 +1,162 @@
+# Lua API: Entity
+
+## Example
+
+```lua
+mod:entity {
+	id = "item_drop",
+
+	properties = {
+		visual = {
+			type = "inventorycube",
+			size = 0.25,
+			origin = {0.125, 0.125, 0.125},
+		},
+
+		is_rotatable = true,
+
+		animation = {
+			{
+				type = "rotation",
+				axis = {0, 0, 1},
+				angle = 0.5
+			},
+			{
+				type = "translation",
+				delta = {0, 0, -0.0005},
+				min = -0.2,
+				max = 0,
+				loop = true
+			}
+		},
+
+		hitbox = {0, 0, 0, 0.25, 0.25, 0.25},
+	},
+
+	on_collision = function(entity, player, server)
+		mods["default"]:give_item_stack(player, entity:item_stack());
+		mods["default"]:despawn_entity(entity)
+	end,
+}
+```
+
+## Attributes
+
+### `id`
+
+ID of the entity. **Mandatory field.**
+
+Example:
+```lua
+id = "item_drop"
+```
+
+### `properties`
+
+Properties table.
+
+#### `animation`
+
+Animation table used to define client-side animation.
+
+Example:
+```lua
+animation = {
+	{
+		type = "rotation",
+		axis = {0, 0, 1},
+		angle = 0.5
+	},
+	{
+		type = "translation",
+		delta = {0, 0, -0.0005},
+		min = -0.2,
+		max = 0,
+		loop = true
+	}
+}
+```
+
+**NB:** You need to set `is_rotatable` to `true` if using `rotation` animation.
+
+#### `hitbox`
+
+Hitbox of the entity.
+
+Defined using an array with respectively `{x, y, z, width, depth, height}`.
+
+Example:
+```lua
+hitbox = {0, 0, 0, 0.25, 0.25, 0.25}
+```
+
+#### `is_rotatable`
+
+Defines if the entity can be rotated or not. Default: `false`.
+
+Example:
+```lua
+is_rotatable = true
+```
+
+#### `visual`
+
+Visual definition.
+
+Example:
+```lua
+visual = {
+    type = "inventorycube",
+    size = 0.25,
+    origin = {0.125, 0.125, 0.125},
+    block_id = "default:cobblestone"
+}
+```
+
+**NB:** Currently, `inventorycube` is the only visual type available.
+
+## Callbacks
+
+### `on_collision`
+
+Called when a player is colliding with the entity.
+
+Example:
+```lua
+on_collision = function(entity, player, server)
+    mods["default"]:give_item_stack(player, entity:item_stack());
+    mods["default"]:despawn_entity(entity)
+end
+```
+
+**NB:** `mods` is a global array here. If you use `mod` global instead, it won't work if another mod overwrites it, that's why using an array is better.
+
+## Entity spawn parameters
+
+### `dimension`
+
+Dimension ID of the entity. **Mandatory field.**
+
+Example:
+```lua
+dimension = 1
+```
+
+### `item_stack`
+
+Item stack component for the entity.
+
+Example:
+```lua
+item_stack = {"default:cobblestone", 64} -- {string_id, amount}
+```
+
+### `position`
+
+Position of the entity. **Mandatory field.**
+
+Example:
+```lua
+position = {5, 2, 3}
+```
+

docs/lua-api-mod.md

@@ -68,6 +68,44 @@ You'll need to create a local variable at the beginning of the file:
 local modpath = mod:path()
 ```
 
+## Utility functions
+
+### `despawn_entity`
+
+Despawn an entity.
+
+Example:
+```lua
+mod:despawn_entity(entity)
+```
+
+**NB:** `entity` is an `EntityWrapper` instance here. Currently, only `on_collision` entity callback can use it.
+
+### `give_item_stack`
+
+Give an item stack to a player.
+
+Example:
+```lua
+mod:give_item_stack(player, item_stack)
+```
+
+### `spawn_entity`
+
+Spawn an entity.
+
+Example:
+```lua
+mod:spawn_entity("default:item_drop", {
+	position = {pos.x + 0.5, pos.y + 0.5, pos.z + 0.5},
+	dimension = world:dimension():id(),
+
+	item_stack = {block:get_item_drop():item():string_id(), block:get_item_drop():amount()}
+})
+```
+
+See [entity page](/lua-api-entity#entity-spawn-parameters) for more information about the available fields in the table.
+
 ## Registration functions
 
 ### `block`
@@ -82,6 +120,10 @@ Defines a biome from a table, see [this page](lua-api-biome.md) for more informa
 
 Defines a dimension from a table, see [this page](lua-api-dimension.md) for more information.
 
+### `entity`
+
+Defines an entity from a table, see [this page](lua-api-entity.md) for more information.
+
 ### `item`
 
 Defines an item from a table, see [this page](lua-api-item.md) for more information.

mkdocs.yml

@@ -10,6 +10,7 @@ nav:
         - 'Biome': 'lua-api-biome.md'
         - 'Block': 'lua-api-block.md'
         - 'Dimension': 'lua-api-dimension.md'
+        - 'Entity': 'lua-api-entity.md'
         - 'Item': 'lua-api-item.md'
         - 'Recipe': 'lua-api-recipe.md'
         - 'Sky': 'lua-api-sky.md'