Document public API

This commit is contained in:
octacian 2017-02-24 12:26:22 -08:00
parent cd99564739
commit 5113f957d7
4 changed files with 91 additions and 1 deletions

View File

@ -3,3 +3,6 @@ The APIs provided by MicroExpansion are divided among several different files. U
### `modules.md` ### `modules.md`
Non-API portions of MicroExpansion are loaded as modules to allow them to be easily enabled or disabled. This documents the API for loading, configuring, and interacting with modules. Non-API portions of MicroExpansion are loaded as modules to allow them to be easily enabled or disabled. This documents the API for loading, configuring, and interacting with modules.
### `api.lua`
This section documents the "core" API that is always loaded before any modules (`api.lua`). This API is mostly made up of functions to make registering items, nodes, and recipes quicker and more intuitive.

49
doc/api.md Normal file
View File

@ -0,0 +1,49 @@
# Core API
The core API is composed of several functions to make registering new items, nodes, and recipes for items and nodes more efficient and intuitive. Code for this public API is in `./api.lua`. This documentation is divided up per function.
#### `register_recipe(output, def)`
__Usage:__ `microexpansion.register_recipe(<output (string)>, <recipe (table)>)`
Though this may seem rather complex to understand, this is a very useful timesaving function when registering recipes. It allows registering multiple recipes at once in one table. The output must always remain the same as is specified as the first parameter, while the second parameter should be a table structured like one of the tables below.
__Single Recipe:__
```lua
microexpansion.register_recipe("default:steelblock", {
"single",
{
{ "default:steel_ingot", "default:steel_ingot", "default:steel_ingot" },
{ "default:steel_ingot", "default:steel_ingot", "default:steel_ingot" },
{ "default:steel_ingot", "default:steel_ingot", "default:steel_ingot" },
},
})
```
The above registers a single recipe for the item specified.
__Multiple Recipes:__
```lua
microexpansion.register_recipe("default:steelblock", {
"multiple",
{
{ "default:steel_ingot", "default:steel_ingot", "default:steel_ingot" },
{ "default:steel_ingot", "default:steel_ingot", "default:steel_ingot" },
{ "default:steel_ingot", "default:steel_ingot", "default:steel_ingot" },
},
{
{ "default:steel_ingot", "default:steel_ingot" },
{ "default:steel_ingot", "default:steel_ingot" },
}
})
```
The above registers multiple recipes for the item specified.
#### `register_item(itemstring, def)`
__Usage:__ `microexpansion.register_item(<itemstring (string)>, <item definition (table)>`
This API function accepts the same parameters in the definition table as does `minetest.register_craftitem`, however, it makes several modifications to the parameters before passing them on. A new parameter, `usedfor`, is introduced, which if provided is appened on a new line in grey to the item description, a good way to specify what the item does or include more information about it. The `inventory_image` parameter is modified to enforce the naming style adding `microexpansion_` to the beginning of the specified path, and `.png` to the end. If not `inventory_image` is provided, the itemstring is used and then undergoes the above modification. This allows shortening and even removing the `inventory_image` code, while passing everything else (aside from `usedfor`) on to `minetest.register_craftitem`.
#### `register_node(itemstring, def)`
__Usage:__ `microexpansion.register_node(<itemstring (string)>, <item definition (table)>`
This API function accepts the same parameters in the definition table as does `minetest.register_craftitem`, however, it makes several modifications to the parameters before passing them on. A new parameter, `usedfor`, is introduced, which if provided is appened on a new line in grey to the item description, a good way to specify what the item does or include more information about it. The `tiles` table is modified so as to simplify the definition when registering the node. Each texture in the `tiles` table has `microexpansion_` added to the beginning and `.png` to the end. This means that rather than specifying something like `microexpansion_chest_top.png`, only `chest_top` is required. __Note:__ the texture path "autocomplete" functionality can be disabled by settings `auto_complete` to `false` in the definition (useful if using textures from another mod).

5
doc/storage/README.md Normal file
View File

@ -0,0 +1,5 @@
# [Module] Storage
The storage module introduces storage systems to allow storing thousands of items inside a single ME Storage Drive. This modules registers an array of storage drives and many devices to make advanced interactions with drives in networks or by themselves. The documentation is divided by section in different files as seen below.
### `api.md`
This section documents the programmatic API used to register storage cells themselves and any other global storage-related functions.

33
doc/storage/api.md Normal file
View File

@ -0,0 +1,33 @@
# Storage API
The storage API introduces functions to help register and handle storage devices and related machines and controllers.
#### `register_cell(itemstring, def)`
__Usage:__ `microexpansion.register_cell(<itemstring (string)>, <cell definition (table)>`
This function registers an item storage cell modifying and adding content to the definition table before passing it on to `minetest.register_craftiem`. Only some definition fields are passed on, as drives are not functional outside of a drive bay or ME Chest. Only the `description` and `capacity` must be required. However, if the `inventory_image` base is any different from the `itemstring`, it should be provided as well. The capacity should be an integer specifying the number of items (not slots, or something else) that the drive can store.
#### `get_cell_size(name)`
__Usage:__ `microexpansion.get_cell_size(<full itemstring (string)>)`<br />
__Example__:__ `microexpansion.get_cell_size("microexpansion:cell_8k")`
Returns the integer containing the size of the storage cell specified (size as in max number of items). __Note:__ The itemstring should be for example `microexpansion:cell_8k`, not just `cell_8k`.
#### `int_to_stacks(int)`
__Usage:__ `microexpansion.int_to_stacks(int)`
Calculates the approximate number of stacks from the provided integer which should contain the max number of items.
#### `int_to_pagenum(int)`
__Usage:__ `microexpansion.int_to_pagenum(int)`
Calculates the approximate number of pages from the integer provided which should represent the total number of items.
#### `move_inv(inv1, inv2)`
__Usage:__ `microexpansion.move_inv(<from inventory (userdata)>, <to inventory (userdata)>)`
Moves all the contents of one inventory (`inv1`) to another inventory (`inv2`).
#### `cell_desc(inv, listname, stack_pos)`
__Usage:__ `microexpansion.cell_desc(<inventory (userdata)>, <list name (string)>, <stack position (integer)>)`
Updates the description of an ME Storage Cell to show the amount of items in it vs the max amount of items. The first parameter should be a `userdata` value representing the inventory in which the list containing the cell itemstack is found. The second parameter should contain the name of the list in which the cell itemstack is found. The third (and final) parameter must be an integer telling at what position to storage cell is in the inventory list.