From 43acec290067f9aca534647d46ba1f13cfeb377a Mon Sep 17 00:00:00 2001
From: TechDudie <73961295+TechDudie@users.noreply.github.com>
Date: Tue, 09 Feb 2021 19:03:55 +0100
Subject: [PATCH] Add Rubber Goo as replacement for the grinder (#578)
---
technic/doc/api.md | 218 +++++++++++++++++++++++++++++++++++-------------------
1 files changed, 142 insertions(+), 76 deletions(-)
diff --git a/technic/doc/api.md b/technic/doc/api.md
index 178ab0a..3343f11 100644
--- a/technic/doc/api.md
+++ b/technic/doc/api.md
@@ -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,54 +117,50 @@
* `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
+## 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.
@@ -118,16 +188,12 @@
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
--
Gitblit v1.8.0