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

@ -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
matching circuit, consider using a "Supply Converter" for simplicity.
For modders: There is currently no API documentation. Any help to improve this
situation is greatly welcome. Please do not hesitate to submit a Pull Request.
The API documentation can be found here: [Technic API](technic/doc/api.md)
## License

@ -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

@ -1,41 +1,115 @@
This file is fairly incomplete. Help is welcome.
# technic API
Tiers
-----
The tier is a string, currently `"LV"`, `"MV"` and `"HV"` are supported.
This file documents the functions within the technic modpack for use in mods.
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)`
* 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
* Use this function when showing players energy values
* `technic.pretty_num(num)`
* Converts the number `num` to a human-readable string with SI prefixes
* `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.get_or_load_node(pos)`
* If the mapblock is loaded, it returns the node at pos,
else it loads the chunk and returns `nil`.
* `technic.config:get(name)`
* Some configuration function
* `technic.tube_inject_item(pos, start_pos, velocity, item)`
* Same as `pipeworks.tube_inject_item`
### Energy modifiers
* `technic.set_RE_wear(itemstack, item_load, max_charge)`
* If the `wear_represents` field in the item's nodedef is
`"technic_RE_charge"`, this function does nothing.
* Modifies the power tool wear of the given itemstack
* `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)`
* This function fully recharges an RE chargeable item.
* If `technic.power_tools[itemstack:get_name()]` is `nil` (or `false`), this
function does nothing, else that value is the maximum 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`.
* `technic.get_cable_tier(nodename)`
* Returns the tier of the cable `nodename` or `nil`.
### Node-specific
* `technic.get_or_load_node(pos)`
* 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)`
* Returns an iteration function (usable in the for loop) to iterate over the
node positions along the specified ray.
@ -43,58 +117,50 @@ Helper functions
* `technic.trace_node_ray_fat(pos, dir, range)`
* Like `technic.trace_node_ray` but includes extra positions near the ray.
* 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
* `technic.register_solar_array(data)`
* 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.
## Item Definition fields
Groups:
Used itemdef fields
-------------------
* groups:
* `technic_<ltier> = 1` ltier is a tier in small letters; this group makes
the node connect to the cable(s) of the right tier.
* `technic_machine = 1` Currently used for
* `connect_sides`
* In addition to the default use (see lua_api.txt), this tells where the
machine can be connected.
#
#
* `technic_run(pos, node)`
* `technic_<tier> = 1`
* Makes the node connect to the cables of the matching tier name
* `<tier>`: name of the tier, in lowercase (ex. `lv`)
* `technic_machine = 1`
* UNRELIABLE. Indicates whether the item or node belongs to technic
* `connect_sides = {"top", "left", ...}`
* Extends the Minetest API. Indicates where the machine can be connected.
Additional definition fields:
* `wear_represents = "string"`
* 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.
Modders have to manually change the information about supply etc. in the
node metadata.
Machine types
-------------
There are currently following 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 batbox
## Node Metadata fields
Nodes connected to the network will have one or more of these parameters as meta
data:
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
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.
### Node meta usage
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
## Deprecated functions
The reason the LV|MV|HV type is prepended to meta data is because some machine
could require several supplies to work.
This way the supplies are separated per network.
Following functions are either no longer used by technic, or are planned to
be removed soon. Please update mods depending on technic accordingly.
* `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