[docs] Updated.
This commit is contained in:
Quentin Bazin
parent
c5510ee595
commit
d861627599
@ -24,7 +24,9 @@ The long-term goal of this project is to provide a viable alternative to Minecra
|
||||
## Wiki
|
||||
|
||||
- [Getting started](https://github.com/Unarelith/OpenMiner/wiki/Getting-Started)
|
||||
- [Lua API Overview](https://github.com/Unarelith/OpenMiner/wiki/Lua-API-Overview)
|
||||
- [Coding style](https://github.com/Unarelith/OpenMiner/wiki/Coding-Style)
|
||||
- [Lua API](https://openminer.readthedocs.io/en/latest/lua-api-overview/)
|
||||
- [Blocks](https://openminer.readthedocs.io/en/latest/lua-api-blocks/)
|
||||
|
||||
## Keys
|
||||
|
||||
|
||||
@ -1,80 +1,222 @@
|
||||
# Lua API: Blocks
|
||||
|
||||
- [Attributes](#attributes)
|
||||
- [Data types](#data-types)
|
||||
- [Draw types](#draw-types)
|
||||
- [Functions](#functions)
|
||||
- [on_block_placed](#on_block_placed)
|
||||
- [on_block_activatd](#on_block_activated)
|
||||
- [on_tick](#on_tick)
|
||||
## Example
|
||||
|
||||
```lua
|
||||
mod:block {
|
||||
id = "myblock", -- mandatory
|
||||
name = "My Block", -- mandatory
|
||||
tiles = "myblock.png",
|
||||
}
|
||||
```
|
||||
|
||||
## Attributes
|
||||
|
||||
Blocks can have the following attributes:
|
||||
### `id`
|
||||
|
||||
| Attribute | Type | Description |
|
||||
| -------------------- | ------------- | ---------------------------------------------------- |
|
||||
| id* | string | ID of the block without the "mod:" prefix |
|
||||
| label* | string | Label of the block |
|
||||
| on_block_placed | function | Called when the block is placed |
|
||||
| on_block_activated | function | Called when a player right-click the block |
|
||||
| on_tick | function | Called every tick |
|
||||
| harvest_requirements | u8 | Set which tools are more effective |
|
||||
| hardness | float | Hardness of the block, affects mining speed |
|
||||
| is_opaque | bool | Whether or not the block let light pass |
|
||||
| is_light_source | bool | Whether or not the block is a light source |
|
||||
| is_rotatable | bool | Whether or not the block is rotatable |
|
||||
| bounding_box | float[6] | Bounding box of the block {x,y,z,w,d,h} |
|
||||
| draw_type | string | Draw type of the block (see [Draw types](#draw-types)) |
|
||||
| item_drop | ItemStack | Item stack that is dropped when the block is broken |
|
||||
| color_multiplier | u8[4] | Only grayscale colors are affected by this attribute |
|
||||
ID of the block. **Mandatory field.**
|
||||
|
||||
NB: Attributes with a `*` means they're mandatory
|
||||
Example:
|
||||
```lua
|
||||
id = "cobblestone"
|
||||
```
|
||||
|
||||
### Data types
|
||||
IDs are usually of the form `mod:block` but the `mod:` prefix is prepended automatically so it's not needed.
|
||||
|
||||
`ItemStack` is a table composed of:
|
||||
### `name`
|
||||
|
||||
- `id` (`string`): item id with the "mod:" prefix
|
||||
- `amount` (`u16`): amount in the stack
|
||||
Label of the block. **Mandatory field.**
|
||||
|
||||
### Draw types
|
||||
Example:
|
||||
```lua
|
||||
name = "Cobblestone"
|
||||
```
|
||||
|
||||
The currently allowed draw type values are:
|
||||
This label is the name that will appear everywhere in the game.
|
||||
|
||||
- `solid`
|
||||
- `xshape`
|
||||
- `leaves`
|
||||
- `liquid`
|
||||
- `glass`
|
||||
### `tiles`
|
||||
|
||||
This field can be either a single string, or a table of strings.
|
||||
|
||||
Example:
|
||||
``` lua
|
||||
tiles = "myblock.png"
|
||||
-- or
|
||||
tiles = {"myblock_top.png", "myblock_bottom.png", "myblock_side.png"}
|
||||
```
|
||||
|
||||
More documentation will come on the table form.
|
||||
|
||||
The textures will be loaded from `mods/<your-mod>/textures/blocks`
|
||||
|
||||
**Note:** Currently, you can only use textures of the exact same size (16x16, 32x32) than the other block textures in the game.
|
||||
|
||||
### `harvest_requirements`
|
||||
|
||||
Set which tools are more effective.
|
||||
|
||||
**Note:** This attribute would need more doc but it'll probably get removed soon.
|
||||
|
||||
### `hardness`
|
||||
|
||||
Hardness of the block, affects mining speed.
|
||||
|
||||
Example:
|
||||
```lua
|
||||
hardness = 0.5
|
||||
```
|
||||
|
||||
Default value is `1.0`, any value under this will increase mining speed, and any value above will decrease mining speed.
|
||||
|
||||
### `is_opaque`
|
||||
|
||||
Defines if the block let the light pass or not.
|
||||
|
||||
Example:
|
||||
```lua
|
||||
is_opaque = true -- this is the default value
|
||||
```
|
||||
|
||||
### `is_light_source`
|
||||
|
||||
Defines if the block is the light source or not.
|
||||
|
||||
Example:
|
||||
```lua
|
||||
is_light_source = false -- this is the default value
|
||||
```
|
||||
|
||||
### `is_rotatable`
|
||||
|
||||
Defines if the block should face the player when placed, like the furnace for example
|
||||
|
||||
Example:
|
||||
```lua
|
||||
is_rotatable = false -- this is the default value
|
||||
```
|
||||
|
||||
### `bounding_box`
|
||||
|
||||
Bounding box of the box.
|
||||
|
||||
Example:
|
||||
```lua
|
||||
bounding_box = {0, 0, 0, 1, 1, 1} -- this is default value
|
||||
```
|
||||
|
||||
Format is `{x, y, z, width, depth, height}`. Note that OpenMiner uses Z axis as up.
|
||||
|
||||
The bounding box determines collisions with the block, as well as the selection box that will be displayed when looking at the block.
|
||||
|
||||
Note: This is what affects the temporary `boundingbox` draw type.
|
||||
|
||||
### `draw_type`
|
||||
|
||||
Draw type of the block, see [Draw types](#draw-types) for more details.
|
||||
|
||||
Example:
|
||||
```lua
|
||||
draw_type = "solid" -- this is the default value
|
||||
```
|
||||
|
||||
### `item_drop`
|
||||
|
||||
Item stack that is given to the player when breaking the block.
|
||||
|
||||
Example:
|
||||
```lua
|
||||
item_drop = {
|
||||
id = "default:cobblestone",
|
||||
amount = 1
|
||||
} -- this is the default drop of a 'default:cobblestone' block
|
||||
```
|
||||
|
||||
### `color_multiplier`
|
||||
|
||||
Color multiplier of the grayscale parts of the block texture.
|
||||
|
||||
Example:
|
||||
```lua
|
||||
color_multiplier = {1, 1, 1, 1} -- full white, this is the default value
|
||||
```
|
||||
|
||||
Only the pure gray parts (red == green == blue) will be affected by this multiplier.
|
||||
|
||||
## Draw types
|
||||
|
||||
The draw type changes how the block is rendered.
|
||||
|
||||
### `solid`
|
||||
|
||||
This draw type is the default draw type of the blocks.
|
||||
|
||||
It renders a basic textured cube of size 1x1x1.
|
||||
|
||||
### `xshape`
|
||||
|
||||
Draws two textured quads that form an X shape.
|
||||
|
||||
Useful for flora, tallgrass, mushrooms, etc...
|
||||
|
||||
### `leaves`
|
||||
|
||||
Keep all the faces while drawing a block.
|
||||
|
||||
Especially useful for leaves.
|
||||
|
||||
### `liquid`
|
||||
|
||||
This draw type doesn't do much yet.
|
||||
|
||||
Makes a single mesh with all the connected blocks of the same type in a chunk.
|
||||
|
||||
It will be rendered without back-face culling (this is why you can see water surface while being inside).
|
||||
|
||||
### `glass`
|
||||
|
||||
Draw type used for glass-type blocks. Also works for portals.
|
||||
|
||||
Almost the same as the `liquid` draw type, except that back-face culling is enabled.
|
||||
|
||||
### `cactus`
|
||||
|
||||
Using the `bounding_box` attribute, will draw a # shape instead of a cube.
|
||||
|
||||
Useful for `cactus` block.
|
||||
|
||||
### `boundingbox`
|
||||
|
||||
NB: Temporary draw type.
|
||||
|
||||
Allow drawing a block of the size of the `bounding_box`.
|
||||
|
||||
## Functions
|
||||
|
||||
### on_block_placed
|
||||
### `on_block_placed`
|
||||
|
||||
Parameters:
|
||||
|
||||
- `pos` (`vec3`): position of the block
|
||||
- `pos` (`ivec3`): position of the block
|
||||
- `world` (`World`): instance of `ServerWorld`
|
||||
|
||||
### on_block_activated
|
||||
### `on_block_activated`
|
||||
|
||||
Parameters:
|
||||
|
||||
- `pos` (`vec3`): position of the block
|
||||
- `player` (`Player`): current player
|
||||
- `pos` (`ivec3`): position of the block
|
||||
- `player` (`Player`): player that activated the block
|
||||
- `world` (`World`): instance of the `ServerWorld`
|
||||
- `client` (`Client`): client that activated the block
|
||||
- `server` (`Server`): current server
|
||||
- `screen_width` (`u16`): width of the screen
|
||||
- `screen_height` (`u16`): height of the screen
|
||||
- `gui_scale` (`u8`): current scaling setting
|
||||
|
||||
### on_tick
|
||||
### `on_tick`
|
||||
|
||||
Parameters:
|
||||
|
||||
- `pos` (`vec3`): position of the block
|
||||
- `player` (`Player`): current player
|
||||
- `pos` (`ivec3`): position of the block
|
||||
- `chunk` (`Chunk`): current chunk
|
||||
- `world` (`World`): instance of the `ServerWorld`
|
||||
|
||||
|
||||
@ -1,32 +1,36 @@
|
||||
# Lua API: Overview
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Lua API](#lua-api)
|
||||
- [Core API](#core-api)
|
||||
- [Mod API](#mod-api)
|
||||
- [Custom GUI](#custom-gui)
|
||||
- [Button](#button)
|
||||
- [Inventory](#inventory)
|
||||
- [Crafting table](#crafting-table)
|
||||
- [Image](#image)
|
||||
- [C++ classes in Lua](#c-classes-in-lua)
|
||||
- [Registry](#registry)
|
||||
- [World](#world)
|
||||
- [Chunk](#chunk)
|
||||
- [BlockData](#blockdata)
|
||||
- [Player](#player)
|
||||
- [Inventory](#inventory-1)
|
||||
- [Recipe](#recipe)
|
||||
- [ItemStack](#itemstack)
|
||||
- [Item](#item)
|
||||
|
||||
## Lua API
|
||||
|
||||
Note: The Lua API is currently server-side only.
|
||||
|
||||
### Core API
|
||||
|
||||
- `Registry *openminer:registry()`
|
||||
- `openminer:add_listener(event_type, listener)`
|
||||
#### `openminer:registry()`
|
||||
|
||||
This function returns the `Registry` instance of the server.
|
||||
|
||||
#### `openminer:add_listener(event_type, listener)`
|
||||
|
||||
Adds a listener to a specific type of event.
|
||||
|
||||
Example:
|
||||
```lua
|
||||
openminer:add_listener(EventType.OnBlockPlaced, function(pos, 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.OnBlockActivated, function(pos, block, player, world, client, server)
|
||||
if block:string_id() == "default:portal" then
|
||||
server:send_chat_message(0, "Swoosh! Changing dimension...", client);
|
||||
end
|
||||
end)
|
||||
```
|
||||
|
||||
Possible events:
|
||||
|
||||
- `OnBlockPlaced`: `funcion(pos, player, world, client, server)`
|
||||
- `OnBlockActivated`: `function(pos, block, player, world, client, server)`
|
||||
|
||||
### Mod API
|
||||
|
||||
@ -39,14 +43,10 @@ mod:block {
|
||||
id = "myblock",
|
||||
name = "My Block",
|
||||
tiles = "myblock.png",
|
||||
hardness = 3,
|
||||
harvest_requirements = 1,
|
||||
on_tick = function(pos, player, chunk, world) end,
|
||||
on_block_activated = function(pos, player, world, client) end,
|
||||
}
|
||||
|
||||
mod:item {
|
||||
id = "mymod:myitem",
|
||||
id = "myitem",
|
||||
name = "My Item",
|
||||
tiles = "myitem.png",
|
||||
}
|
||||
@ -67,12 +67,14 @@ mod:crafting_recipe {
|
||||
}
|
||||
|
||||
mod:smelting_recipe {
|
||||
input = {id = "mymod:myblock", amount = 1},
|
||||
output = {id = "default:ingot_iron", amount = 1}
|
||||
input = {id = "mymod:myitem", amount = 1},
|
||||
output = {id = "mymod:myblock", amount = 1}
|
||||
}
|
||||
```
|
||||
|
||||
I'll describe all the possible options later.
|
||||
Documented API so far:
|
||||
|
||||
- [Blocks](lua-api-blocks.md)
|
||||
|
||||
### Custom GUI
|
||||
|
||||
@ -144,29 +146,66 @@ gui:image {
|
||||
|
||||
### Registry
|
||||
|
||||
- `Block get_block(u16 id)`
|
||||
- `Item get_item(u16 id)`
|
||||
- `Sky get_sky(u16 id)`
|
||||
- `Tree get_tree(u16 id)`
|
||||
- `Biome get_biome(u16 id)`
|
||||
- `Recipe get_recipe(Inventory crafting_inventory)`
|
||||
- `Block get_block_from_string(string id)`
|
||||
- `Item get_item_from_string(string id)`
|
||||
- `Sky get_sky_from_string(string id)`
|
||||
- `Tree get_tree_from_string(string id)`
|
||||
- `Biome get_biome_from_string(string id)`
|
||||
- `List<Block> blocks()`
|
||||
- `List<Item> items()`
|
||||
- `List<Tree> trees()`
|
||||
- `List<Biome> biomes()`
|
||||
- `List<Dimension> dimensions()`
|
||||
|
||||
### World
|
||||
|
||||
- `u16 get_block(int x, int y, int z)`
|
||||
- `void set_block(int x, int y, int z, u16 block)`
|
||||
- `u16 get_data(int x, int y, int z)`
|
||||
- `void set_data(int x, int y, int z, u16 data)`
|
||||
- `BlockData *add_block_data(int x, int y, int z, int inventoryWidth, int inventoryHeight)`
|
||||
- `BlockData *get_block_data(int x, int y, int z)`
|
||||
|
||||
### Chunk
|
||||
|
||||
- `u16 get_block(int x, int y, int z)`
|
||||
- `void set_block(int x, int y, int z, u16 block)`
|
||||
- `u16 get_data(int x, int y, int z)`
|
||||
- `void set_data(int x, int y, int z, u16 data)`
|
||||
- `BlockData *add_block_data(int x, int y, int z, int inventoryWidth, int inventoryHeight)`
|
||||
- `BlockData *get_block_data(int x, int y, int z)`
|
||||
|
||||
### BlockData
|
||||
|
||||
- `Inventory *inventory()`
|
||||
- `u32 data()`
|
||||
- `Inventory *inventory`
|
||||
- `BlockMetadata *meta`
|
||||
- `bool use_alt_tiles`
|
||||
|
||||
### Block
|
||||
|
||||
- `u16 id()`
|
||||
- `u16 data()`
|
||||
- `string string_id()`
|
||||
- `string label()`
|
||||
- `stirng mod_name()`
|
||||
- `bool is_opaque()`
|
||||
|
||||
### Player
|
||||
|
||||
- `Inventory *inventory()`
|
||||
- `double x()`
|
||||
- `double y()`
|
||||
- `double z()`
|
||||
- `void set_position(double x, double y, double z)`
|
||||
- `u16 dimension()`
|
||||
- `void set_dimension(u16 dimension)`
|
||||
- `u16 client_id()`
|
||||
|
||||
### Inventory
|
||||
|
||||
@ -189,4 +228,27 @@ gui:image {
|
||||
- `u16 id()`
|
||||
- `string name()`
|
||||
- `u16 burn_time()`
|
||||
- `bool is_fuel()`
|
||||
|
||||
### ivec3
|
||||
|
||||
- `int x`
|
||||
- `int y`
|
||||
- `int z`
|
||||
|
||||
### BlockMetadata
|
||||
|
||||
- `string get_string(string attribute)`
|
||||
- `void set_string(string attribute, string value)`
|
||||
- `int get_int(string attribute)`
|
||||
- `void set_int(string attribute, int value)`
|
||||
|
||||
### ClientInfo
|
||||
|
||||
- `u16 id()`
|
||||
|
||||
### ServerCommandHandler
|
||||
|
||||
- `void send_player_change_dimension(u16 clientID, int x, int y, int z, u16 dimension, ClientInfo client)`
|
||||
- `void send_chat_message(u16 senderID, string message, ClientInfo client)`
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user