minetest-mods
/
technic
mirror of https://github.com/minetest-mods/technic.git
1
0
Fork 1
Code Issues Releases Wiki Activity

Merge new documentation with technic/doc

This commit is contained in:
SmallJoker 2020-09-19 14:14:31 +02:00
parent c06a56daff
commit d8fe9ad16c
3 changed files with 143 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@ -32,8 +32,7 @@ The modpack is explained in the [Manual](manual.md) included in this repository.
* Each machine type requires its own cable type. If you do not have a * Each machine type requires its own cable type. If you do not have a
matching circuit, consider using a "Supply Converter" for simplicity. matching circuit, consider using a "Supply Converter" for simplicity.
For modders: There is currently no API documentation. Any help to improve this The API documentation can be found here: [Technic API](technic/doc/api.md)
situation is greatly welcome. Please do not hesitate to submit a Pull Request.
## License ## License

18
mod_api.md
View File

@ -1,18 +0,0 @@
# technic API
This is an initial version of the API that can be used by mods.
* `technic.register_tier(tier, description)`
* Registers a network type (tier)
* `tier`: string, short name (ex. `LV`)
* `description`: string, long name (ex. `Low Voltage`)
* `technic.register_machine(tier, nodename, machine_type)`
* Registers a machine bound to the network tier
* `tier`: see `register_tier`
* `nodename`: string, node name
* `machine_type`: string, following options are possible:
* `"RE"`: Receiver
* `"PR"`: Producer
* `"BA"`: Battery, energy storage

222
technic/doc/api.md
View File

@ -1,41 +1,115 @@
This file is fairly incomplete. Help is welcome. # technic API
Tiers This file documents the functions within the technic modpack for use in mods.
-----
The tier is a string, currently `"LV"`, `"MV"` and `"HV"` are supported.
Network
-------
The network is the cable with the connected machine nodes. Currently the
switching station handles the network activity.
Helper functions ## Tiers
---------------- Tier are network types. List of pre-registered tiers:
* `"LV"`, Low Voltage
* `"MV"`, Medium Voltage
* `"HV"`, High Voltage
Available functions:
* `technic.register_tier(tier, description)`
* Registers a network type (tier)
* `tier`: string, short name (ex. `LV`)
* `description`: string, long name (ex. `Low Voltage`)
* See also `tiers`
## Cables
* `technic.register_cable(tier, size)`
* Registers an existing node as cable
* `tier`: string
* `size`: number, visual size of the wire
* `technic.get_cable_tier(nodename)`
* Retrieves the tier assigned to the provided node name
* `nodename`: string, name of the node
* Returns the tier (string) or `nil`
* `technic.is_tier_cable(nodename, tier)`
* Tells whether the node `nodename` is the cable of the tier `tier`.
* Short version of `technic.get_cable_tier(nodename) == tier`
## Machines
The machine type indicates the direction of power flow.
List of pre-registered machine types:
* `technic.receiver = "RE"` e.g. grinder
* `technic.producer = "PR"` e.g. solar panel
* `technic.producer_receiver = "PR_RE"` supply converter
* `technic.battery = "BA"` e.g. LV battery box
Available functions:
* `technic.register_machine(tier, nodename, machine_type)`
* Register an existing node as machine, bound to the network tier
* `tier`: see `register_tier`
* `nodename`: string, node name
* `machine_type`: string, following options are possible:
* `"RE"`: Receiver
* `"PR"`: Producer
* `"BA"`: Battery, energy storage
* See also `Machine types`
Functions to use for callbacks:
* `technic.can_insert_unique_stack(pos, node, stack, direction)`
* `technic.insert_object_unique_stack(pos, node, stack, direction)`
* Functions for the parameters `can_insert` and `insert_object` to avoid
filling multiple inventory slots with same type of item.
### Specific machines
* `technic.register_solar_array(data)`
* data is a table (TODO)
## Tools
* `technic.register_power_tool(itemname, max_charge)`
* Register or configure the maximal charge held by an existing item
* `craftitem`: string, item or node name
* `max_charge`: number, maximal EU capacity
## Helper functions
Unsorted functions:
* `technic.EU_string(num)` * `technic.EU_string(num)`
* Converts num to a human-readable string (see pretty_num) * Converts num to a human-readable string (see `pretty_num`)
and adds the `EU` unit and adds the `EU` unit
* Use this function when showing players energy values * Use this function when showing players energy values
* `technic.pretty_num(num)` * `technic.pretty_num(num)`
* Converts the number `num` to a human-readable string with SI prefixes * Converts the number `num` to a human-readable string with SI prefixes
* `technic.swap_node(pos, nodename)` * `technic.config:get(name)`
* Same as `mintest.swap_node` but it only changes the nodename. * Some configuration function
* It uses `minetest.get_node` before swapping to ensure the new nodename * `technic.tube_inject_item(pos, start_pos, velocity, item)`
is not the same as the current one. * Same as `pipeworks.tube_inject_item`
* `technic.get_or_load_node(pos)`
* If the mapblock is loaded, it returns the node at pos, ### Energy modifiers
else it loads the chunk and returns `nil`.
* `technic.set_RE_wear(itemstack, item_load, max_charge)` * `technic.set_RE_wear(itemstack, item_load, max_charge)`
* If the `wear_represents` field in the item's nodedef is * Modifies the power tool wear of the given itemstack
`"technic_RE_charge"`, this function does nothing. * `itemstack`: ItemStack to modify
* `item_load`: number, used energy in EU
* `max_charge`: number, maximal EU capacity of the tool
* The itemdef field `wear_represents` must be set to `"technic_RE_charge"`,
otherwise this function will do nothing.
* Returns the modified itemstack
* `technic.refill_RE_charge(itemstack)` * `technic.refill_RE_charge(itemstack)`
* This function fully recharges an RE chargeable item. * This function fully recharges an RE chargeable item.
* If `technic.power_tools[itemstack:get_name()]` is `nil` (or `false`), this * If `technic.power_tools[itemstack:get_name()]` is `nil` (or `false`), this
function does nothing, else that value is the maximum charge. function does nothing, else that value is the maximum charge.
* The itemstack metadata is changed to contain the charge. * The itemstack metadata is changed to contain the charge.
* `technic.is_tier_cable(nodename, tier)`
* Tells whether the node `nodename` is the cable of the tier `tier`. ### Node-specific
* `technic.get_cable_tier(nodename)` * `technic.get_or_load_node(pos)`
* Returns the tier of the cable `nodename` or `nil`. * If the mapblock is loaded, it returns the node at pos,
else it loads the chunk and returns `nil`.
* `technic.swap_node(pos, nodename)`
* Same as `mintest.swap_node` but it only changes the nodename.
* It uses `minetest.get_node` before swapping to ensure the new nodename
is not the same as the current one.
* `technic.trace_node_ray(pos, dir, range)` * `technic.trace_node_ray(pos, dir, range)`
* Returns an iteration function (usable in the for loop) to iterate over the * Returns an iteration function (usable in the for loop) to iterate over the
node positions along the specified ray. node positions along the specified ray.
@ -43,58 +117,50 @@ Helper functions
* `technic.trace_node_ray_fat(pos, dir, range)` * `technic.trace_node_ray_fat(pos, dir, range)`
* Like `technic.trace_node_ray` but includes extra positions near the ray. * Like `technic.trace_node_ray` but includes extra positions near the ray.
* The node ray functions are used for mining lasers. * The node ray functions are used for mining lasers.
* `technic.config:get(name)`
* Some configuration function
* `technic.tube_inject_item(pos, start_pos, velocity, item)`
* Same as `pipeworks.tube_inject_item`
Registration functions
----------------------
* `technic.register_power_tool(itemname, max_charge)`
* Same as `technic.power_tools[itemname] = max_charge`
* This function makes the craftitem `itemname` chargeable.
* `technic.register_machine(tier, nodename, machine_type)`
* Same as `technic.machines[tier][nodename] = machine_type`
* Currently this is requisite to make technic recognize your node.
* See also `Machine types`
* `technic.register_tier(tier)`
* Same as `technic.machines[tier] = {}`
* See also `tiers`
### Specific machines ## Item Definition fields
* `technic.register_solar_array(data)` Groups:
* data is a table
* `technic.can_insert_unique_stack(pos, node, stack, direction)`
* `technic.insert_object_unique_stack(pos, node, stack, direction)`
* Functions for the parameters `can_insert` and `insert_object` to avoid
filling multiple inventory slots with same type of item.
Used itemdef fields * `technic_<tier> = 1`
------------------- * Makes the node connect to the cables of the matching tier name
* groups: * `<tier>`: name of the tier, in lowercase (ex. `lv`)
* `technic_<ltier> = 1` ltier is a tier in small letters; this group makes * `technic_machine = 1`
the node connect to the cable(s) of the right tier. * UNRELIABLE. Indicates whether the item or node belongs to technic
* `technic_machine = 1` Currently used for * `connect_sides = {"top", "left", ...}`
* `connect_sides` * Extends the Minetest API. Indicates where the machine can be connected.
* In addition to the default use (see lua_api.txt), this tells where the
machine can be connected. Additional definition fields:
#
# * `wear_represents = "string"`
* `technic_run(pos, node)` * Specifies how the tool wear level is handled. Available modes:
* `"mechanical_wear"`: represents physical damage
* `"technic_RE_charge"`: represents electrical charge
* `<itemdef>.technic_run(pos, node)`
* This function is currently used to update the node. * This function is currently used to update the node.
Modders have to manually change the information about supply etc. in the Modders have to manually change the information about supply etc. in the
node metadata. node metadata.
Machine types ## Node Metadata fields
------------- Nodes connected to the network will have one or more of these parameters as meta
There are currently following types: data:
* `technic.receiver = "RE"` e.g. grinder
* `technic.producer = "PR"` e.g. solar panel
* `technic.producer_receiver = "PR_RE"` supply converter
* `technic.battery = "BA"` e.g. LV batbox
Switching Station * `<tier>_EU_supply` - direction: output
----------------- * For nodes registered as `PR` or `BA` tier
* This is the EU value supplied by the node.
* `<tier>_EU_demand` - direction: output
* For nodes registered as `RE` or `BA` tier
* This is the EU value the node requires to run.
* `<tier>_EU_input` - direction: input
* For nodes registered as `RE` or `BA` tier
* This is the actual EU value the network can give the node.
`<tier>` corresponds to the tier name registered using
`technic.register_tier` (ex. `LV`). It is possible for the machine to depend on
multiple tiers (or networks).
## Switching Station mechanics
The switching station is the center of all power distribution on an electric The switching station is the center of all power distribution on an electric
network. network.
@ -122,16 +188,12 @@ down. We have a brown-out situation.
Hence for now all the power distribution logic resides in this single node. Hence for now all the power distribution logic resides in this single node.
### Node meta usage ## Deprecated functions
Nodes connected to the network will have one or more of these parameters as meta
data:
* `<LV|MV|HV>_EU_supply` : Exists for PR and BA node types.
This is the EU value supplied by the node. Output
* `<LV|MV|HV>_EU_demand` : Exists for RE and BA node types.
This is the EU value the node requires to run. Output
* `<LV|MV|HV>_EU_input` : Exists for RE and BA node types.
This is the actual EU value the network can give the node. Input
The reason the LV|MV|HV type is prepended to meta data is because some machine Following functions are either no longer used by technic, or are planned to
could require several supplies to work. be removed soon. Please update mods depending on technic accordingly.
This way the supplies are separated per network.
* `technic.get_RE_item_load`
* Scales the tool wear to a certain numeric range
* `technic.set_RE_item_load`
* Scales a certain numeric range to the tool wear