Add api documentation (#361)

This commit is contained in:
you 2017-06-05 16:51:59 +02:00 committed by Vanessa Ezekowitz
parent 83a4bb60ca
commit 987cc5a6a4
2 changed files with 131 additions and 32 deletions

130
technic/doc/api.md Normal file

@ -0,0 +1,130 @@
This file is fairly incomplete. Help is welcome.
Tiers
-----
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
----------------
* `technic.pretty_num(num)`
* Converts the number `num` to a human-readable string.
* Use this function when showing players power values.
* `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.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.
* `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`.
* `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.
* The returned positions will not include the starting position `pos`.
* `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
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)`
* 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
Switching Station
-----------------
The switching station is the center of all power distribution on an electric
network.
The station collects power from sources (PR), distributes it to sinks (RE),
and uses the excess/shortfall to charge and discharge batteries (BA).
For now, all supply and demand values are expressed in kW.
It works like this:
All PR,BA,RE nodes are indexed and tagged with the switching station.
The tagging is a workaround to allow more stations to be built without allowing
a cheat with duplicating power.
All the RE nodes are queried for their current EU demand. Those which are off
would require no or a small standby EU demand, while those which are on would
require more.
If the total demand is less than the available power they are all updated with
the demand number.
If any surplus exists from the PR nodes the batteries will be charged evenly
with this.
If the total demand requires draw on the batteries they will be discharged
evenly.
If the total demand is more than the available power all RE nodes will be shut
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
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.

@ -1,35 +1,4 @@
-- SWITCHING STATION -- See also technic/doc/api.md
-- The switching station is the center of all power distribution on an electric network.
--
-- The station collects power from sources (PR), distributes it to sinks (RE),
-- and uses the excess/shortfall to charge and discharge batteries (BA).
--
-- For now, all supply and demand values are expressed in kW.
--
-- It works like this:
-- All PR,BA,RE nodes are indexed and tagged with the switching station.
-- The tagging is to allow more stations to be built without allowing a cheat
-- with duplicating power.
-- All the RE nodes are queried for their current EU demand. Those which are off
-- would require no or a small standby EU demand, while those which are on would
-- require more.
-- If the total demand is less than the available power they are all updated with the
-- demand number.
-- If any surplus exists from the PR nodes the batteries will be charged evenly with this.
-- If the total demand requires draw on the batteries they will be discharged evenly.
--
-- If the total demand is more than the available power all RE nodes will be shut down.
-- We have a brown-out situation.
--
-- Hence all the power distribution logic resides in this single node.
--
-- 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 toe meta data is because some machine could require several supplies to work.
-- This way the supplies are separated per network.
technic.networks = {} technic.networks = {}
technic.cables = {} technic.cables = {}