diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60f5c6ce9..34323dcbc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Contributions are **welcome** and will be fully **credited**. - **Read the coding style** - Make sure you read the [coding style](https://github.com/Unarelith/OpenMiner/wiki/Coding-Style) before opening a pull request. -- **Document any change in behaviour** - Make sure any relevant documentation is kept up-to-date. +- **Document any change in behaviour** - Make sure any relevant [documentation](https://openminer.readthedocs.io/en/latest/) is kept up-to-date. - **Create feature branches** - Don't ask us to pull from your master branch. diff --git a/README.md b/README.md index 91eab9296..775a92c72 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,17 @@ 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) -- [Coding style](https://github.com/Unarelith/OpenMiner/wiki/Coding-Style) + - [Contributing](https://github.com/Unarelith/OpenMiner/blob/master/CONTRIBUTING.md) + - [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/) + - [Block](https://openminer.readthedocs.io/en/latest/lua-api-block/) + - [Item](https://openminer.readthedocs.io/en/latest/lua-api-item/) + - [Recipe](https://openminer.readthedocs.io/en/latest/lua-api-recipe/) + - [Sky](https://openminer.readthedocs.io/en/latest/lua-api-sky/) + - [Tree](https://openminer.readthedocs.io/en/latest/lua-api-tree/) + - [Biome](https://openminer.readthedocs.io/en/latest/lua-api-biome/) + - [Dimension](https://openminer.readthedocs.io/en/latest/lua-api-dimension/) +- [Network Protocol](https://github.com/Unarelith/OpenMiner/wiki/Network-Protocol) ## Keys diff --git a/docs/index.md b/docs/index.md index c20c5cbbe..49c772473 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,13 @@ - [Contributing](https://github.com/Unarelith/OpenMiner/blob/master/CONTRIBUTING.md) - [Coding Style](https://github.com/Unarelith/OpenMiner/wiki/Coding-Style) - [Lua API](lua-api-overview.md) - - [Blocks](lua-api-blocks.md) + - [Block](lua-api-block.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) - [Network Protocol](https://github.com/Unarelith/OpenMiner/wiki/Network-Protocol) ## Other diff --git a/docs/lua-api-biome.md b/docs/lua-api-biome.md new file mode 100644 index 000000000..88aab2fd1 --- /dev/null +++ b/docs/lua-api-biome.md @@ -0,0 +1,214 @@ +# Lua API: Biome + +## Example + +```lua +mod:biome { + id = "desert", + name = "Desert", + + params = { + temperature = -0.3, + precipitation = -0.7 + }, + + trees = { + { + type = "default:tree_cactus", + probability = 0.001, + } + }, + + flora = { + { + block = "default:deadbush", + spawns_on = "default:sand", + probability = 0.005, + } + }, + + top_block = "default:sand", + ground_block = "default:sand", + deep_block = "default:stone", + beach_block = "default:sand", + liquid_block = "default:water", + portal_block = "default:portal", + portal_frame_block = "default:obsidian", +} +``` + +## Attributes + +### `id` + +ID of the biome. **Mandatory field.** + +Example: +```lua +id = "biome_desert" +``` + +IDs are usually of the form `mod:biome` but the `mod:` prefix is prepended automatically so it's not needed. + +### `name` + +Label of the biome. **Mandatory field.** + +Example: +```lua +name = "Desert" +``` + +This label is the name that will appear everywhere in the game. + +### `params` + +Parameters used to generate the biome. + +Example: +```lua +params = { + temperature = -0.3, + precipitation = -0.7 +} +``` + +Current valid parameters are: + +- `temperature` +- `precipitation` + +### `top_block` + +String ID of the block used on the top of the terrain. + +Example: +```lua +top_block = "default:grass" +``` + +### `ground_block` + +String ID of the block used for the upper part of the terrain, under `top_block`. + +Example: +```lua +ground_block = "default:dirt" +``` + +### `deep_block` + +String ID of the block used for the lower part of the terrain, below `ground_block`. + +Example: +```lua +deep_block = "default:stone" +``` + +### `beach_block` + +String ID of the block used around and under `liquid_block`. + +Example: +```lua +beach_block = "default:sand" +``` + +### `liquid_block` + +String ID of the block used to make lakes under `SEALEVEL` (see EngineConfig.hpp). + +Example: +```lua +liquid_block = "default:water" +``` + +### `portal_block` + +String ID of the block used to generate portal center. + +Example: +```lua +portal_block = "default:portal" +``` + +**Note:** This attribute is temporary and will get removed soon. + +### `portal_frame_block` + +String ID of the block used to generate portal frame. + +Example: +```lua +portal_frame_block = "default:obsidian" +``` + +**Note:** This attribute is temporary and will get removed soon. + +### `trees` + +Table that defines tree placement. + +Example: +```lua +trees = { + { + type = "default:oak", + probability = 0.01 + }, + { + type = "default:cactus", + probability = 0.001 + } +} +``` + +Possible attributes: +- `type`: String ID of the tree definition +- `probability`: Probability to spawn this tree + +### `flora` + +Table that defines flora placement. + +Example: +```lua +flora = { + { + block = "default:tallgrass", + spawns_on = "default:grass", + probability = 0.25 + }, + { + block = "default:dandelion", + spawns_on = "default:grass", + probability = 0.025 + } +} +``` + +Possible attributes: +- `block`: Block used as flora +- `spawn_on`: What the block below must be +- `probability`: Probability to spawn `block` + +### `ores` + +Table that defines ore placement. + +Example: +```lua +ores = { + { + block = "default:iron_ore", + probability = 0.0003, + size = 8 + } +} +``` + +Possible attributes: +- `block`: Ore block to be used +- `probability`: Probability to spawn an ore vein with that block +- `size`: Ore vein size + diff --git a/docs/lua-api-blocks.md b/docs/lua-api-block.md similarity index 92% rename from docs/lua-api-blocks.md rename to docs/lua-api-block.md index b4db4a5f2..77502f259 100644 --- a/docs/lua-api-blocks.md +++ b/docs/lua-api-block.md @@ -1,4 +1,4 @@ -# Lua API: Blocks +# Lua API: Block ## Example @@ -45,11 +45,20 @@ tiles = "myblock.png" tiles = {"myblock_top.png", "myblock_bottom.png", "myblock_side.png"} ``` -More documentation will come on the table form. +Table format: +```cpp +// namely: West, East, South, North, Bottom, Top +{0, 0, 0, 0, 0, 0}, // for size = 1 +{1, 1, 1, 1, 0, 0}, // for size = 2 +{2, 2, 2, 2, 1, 0}, // for size = 3 +{2, 3, 3, 3, 1, 0}, // for size = 4 +{2, 3, 4, 4, 1, 0}, // for size = 5 +{2, 3, 4, 5, 1, 0}, // for size = 6 +``` The textures will be loaded from `mods//textures/blocks` -**Note:** Currently, you can only use textures of the exact same size (16x16, 32x32) than the other block textures in the game. +**Note:** Currently, you can only use textures of the exact same size (16x16, 32x32) than the other block/item textures in the game. ### `harvest_requirements` diff --git a/docs/lua-api-dimension.md b/docs/lua-api-dimension.md new file mode 100644 index 000000000..3d1af615b --- /dev/null +++ b/docs/lua-api-dimension.md @@ -0,0 +1,57 @@ +# Lua API: Dimension + +## Example + +```lua +mod:dimension { + id = "overworld", + name = "Overworld", + + biomes = {"default:grassland", "default:desert"}, + + sky = "default:sky_overworld", +} +``` + +## Attributes + +### `id` + +ID of the dimension. **Mandatory field.** + +Example: +```lua +id = "dimension_nether" +``` + +IDs are usually of the form `mod:dimension` but the `mod:` prefix is prepended automatically so it's not needed. + +### `name` + +Label of the dimension. **Mandatory field.** + +Example: +```lua +name = "Nether" +``` + +This label is the name that will appear everywhere in the game. + +### `biomes` + +Table containing all the string IDs of the possible biomes for this dimension. + +Example: +```lua +biomes = {"default:grassland", "default:desert"} +``` + +### `sky` + +String ID of the sky definition used for this dimension. + +Example: +```lua +sky = "default:sky_nether" +``` + diff --git a/docs/lua-api-item.md b/docs/lua-api-item.md new file mode 100644 index 000000000..f47f35828 --- /dev/null +++ b/docs/lua-api-item.md @@ -0,0 +1,82 @@ +# Lua API: Item + +## Example + +```lua +mod:item { + id = "myitem", + name = "My Item", + tiles = "myitem.png", +} +``` + +## Attributes + +### `id` + +ID of the item. **Mandatory field.** + +Example: +```lua +id = "stick" +``` + +IDs are usually of the form `mod:item` but the `mod:` prefix is prepended automatically so it's not needed. + +### `name` + +Label of the item. **Mandatory field.** + +Example: +```lua +name = "Stick" +``` + +This label is the name that will appear everywhere in the game. + +### `tiles` + +Texture of the item. + +Example: +``` lua +tiles = "myblock.png" +``` + +The textures will be loaded from `mods//textures/items` + +**Note:** Currently, you can only use textures of the exact same size (16x16, 32x32) than the other block/item textures in the game. + +### `harvest_capability` + +For a tool, set which blocks are easier to mine. + +**Note:** This attribute would need more doc but it'll probably get removed soon. + +### `mining_speed` + +For a tool, speed at which it mines the block. + +Example: +```lua +mining_speed = 1 -- this is the default value +``` + +### `is_fuel` + +Defines if the item is valid furnace fuel or not. + +Example: +```lua +is_fuel = false -- this is the default value +``` + +### `burn_time` + +Burn time of a fuel item. + +Example: +```lua +burn_time = 200 -- example value for a coal item, default is 0 +``` + diff --git a/docs/lua-api-overview.md b/docs/lua-api-overview.md index bc936e688..caa2fb82b 100644 --- a/docs/lua-api-overview.md +++ b/docs/lua-api-overview.md @@ -72,10 +72,6 @@ mod:smelting_recipe { } ``` -Documented API so far: - -- [Blocks](lua-api-blocks.md) - ### Custom GUI You can create a new GUI with: @@ -157,11 +153,11 @@ gui:image { - `Sky get_sky_from_string(string id)` - `Tree get_tree_from_string(string id)` - `Biome get_biome_from_string(string id)` -- `List blocks()` -- `List items()` -- `List trees()` -- `List biomes()` -- `List dimensions()` +- `Block[] blocks()` +- `Item[] items()` +- `Tree[] trees()` +- `Biome[] biomes()` +- `Dimension[] dimensions()` ### World diff --git a/docs/lua-api-recipe.md b/docs/lua-api-recipe.md new file mode 100644 index 000000000..5f5c4bf52 --- /dev/null +++ b/docs/lua-api-recipe.md @@ -0,0 +1,121 @@ +# Lua API: Recipe + +## Example + +### Crafting recipe + +```lua +mod:crafting_recipe { + result = { + id = "default:wooden_axe", + amount = 1 + }, + + pattern = { + "##", + "#|", + " |" + }, + + keys = { + ['#'] = "default:oak_planks", + ['|'] = "default:stick", + } +} +``` + +### Smelting recipe + +```lua +mod:smelting_recipe { + input = { + id = "default:iron_ore", + amount = 1 + }, + + output = { + id = "default:iron_ingot", + amount = 1 + } +} +``` + +## Attributes + +### Crafting recipe + +#### `result` + +Item stack created with the craft. + +Example +```lua +result = { + id = "default:wooden_axe", + amount = 1 +} +``` + +Possible attributes: +- `id`: String ID of the item created. +- `amount`: Amount of items in the created stack + +#### `pattern` + +Pattern of the craft. + +Example: +```lua +pattern = { + "##", + "#|", + " |", +} +``` + +#### `keys` + +Mapping of the characters used in `pattern` to actual item string IDs. + +Example: +```lua +keys = { + ['#'] = "default:oak_planks", + ['|'] = "default:stick", +} +``` + +### Smelting recipe + +#### `input` + +Item stack used as input for the recipe. + +Example: +```lua +input = { + id = "default:cobblestone", + amount = 1 +} +``` + +Possible attributes: +- `id`: String ID of the item created. +- `amount`: Amount of items in the created stack + +#### `output` + +Item stack created with the recipe. + +Example: +```lua +output = { + id = "default:stone", + amount = 1 +} +``` + +Possible attributes: +- `id`: String ID of the item created. +- `amount`: Amount of items in the created stack + diff --git a/docs/lua-api-sky.md b/docs/lua-api-sky.md new file mode 100644 index 000000000..8ffea6730 --- /dev/null +++ b/docs/lua-api-sky.md @@ -0,0 +1,59 @@ +# Lua API: Sky + +## Example + +```lua +mod:sky { + id = "sky_overworld", + + color = { + day = {50, 153, 204}, + }, + + fog_color = { + day = {50, 153, 204}, + }, +} +``` + +## Attributes + +### `id` + +ID of the sky. **Mandatory field.** + +Example: +```lua +id = "sky_nether" +``` + +IDs are usually of the form `mod:sky` but the `mod:` prefix is prepended automatically so it's not needed. + +### `color` + +Sky color. + +Example: +```lua +color = { + day = {154, 50, 33} +} +``` + +Possible values: +- `day`: Sky color at midday + +### `fog_color` + +Fog color. + +Example: +```lua +fog_color = { + day = {154, 50, 33} +} +``` + +Possible values: +- `day`: Fog color at midday + diff --git a/docs/lua-api-tree.md b/docs/lua-api-tree.md new file mode 100644 index 000000000..f0faf9872 --- /dev/null +++ b/docs/lua-api-tree.md @@ -0,0 +1,70 @@ +# Lua API: Tree + +## Example + +```lua +mod:tree { + id = "oak", + + log_block = "default:oak_wood", + leaves_block = "default:oak_leaves", + + trunk_height = { + min = 3, + max = 6 + }, +} +``` + +## Attributes + +### `id` + +ID of the tree. **Mandatory field.** + +Example: +```lua +id = "tree_oak" +``` + +IDs are usually of the form `mod:tree` but the `mod:` prefix is prepended automatically so it's not needed. + +### `log_block` + +String ID of the block used as a log. + +Example: +```lua +log_block = "default:oak_wood" +``` + +### `leaves_block` + +String ID of the block used as leaves if `has_leaves` is set to `true`. + +Example: +```lua +leaves_block = "default:oak_leaves" +``` + +### `has_leaves` + +Defines if the tree has leaves or not. + +Example: +```lua +has_leaves = true -- this is the default value +``` + +### `trunk_height` + +Minimum and maximum trunk height. + +Example: +```lua +trunk_height = { + min = 3, + max = 6 +} +``` + diff --git a/mkdocs.yml b/mkdocs.yml index c0c8a00e4..32da086cb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,12 +4,17 @@ nav: - 'Home': 'index.md' - 'Lua API': - 'Overview': 'lua-api-overview.md' - - 'Blocks': 'lua-api-blocks.md' + - 'Block': 'lua-api-block.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' theme: name: readthedocs highlightjs: true hljs_languages: - - yaml - - rust + - lua