From d8fe9ad16caea0b99fef5bcce0c882e29ee468fc Mon Sep 17 00:00:00 2001 From: SmallJoker Date: Sat, 19 Sep 2020 14:14:31 +0200 Subject: [PATCH] Merge new documentation with technic/doc --- README.md | 3 +- mod_api.md | 18 ---- technic/doc/api.md | 222 +++++++++++++++++++++++++++++---------------- 3 files changed, 143 insertions(+), 100 deletions(-) delete mode 100644 mod_api.md diff --git a/README.md b/README.md index 2a52855..c85aecc 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/mod_api.md b/mod_api.md deleted file mode 100644 index 87d49d1..0000000 --- a/mod_api.md +++ /dev/null @@ -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 - diff --git a/technic/doc/api.md b/technic/doc/api.md index 8ae6963..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,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_ = 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_ = 1` + * Makes the node connect to the cables of the matching tier name + * ``: 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 +* `.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 ------------------ +* `_EU_supply` - direction: output + * For nodes registered as `PR` or `BA` tier + * This is the EU value supplied by the node. +* `_EU_demand` - direction: output + * For nodes registered as `RE` or `BA` tier + * This is the EU value the node requires to run. +* `_EU_input` - direction: input + * For nodes registered as `RE` or `BA` tier + * This is the actual EU value the network can give the node. + +`` 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: - * `_EU_supply` : Exists for PR and BA node types. - This is the EU value supplied by the node. Output - * `_EU_demand` : Exists for RE and BA node types. - This is the EU value the node requires to run. Output - * `_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