| commit | author | age | ||
| d8fe9a | 1 | # technic API |
| 987cc5 | 2 | |
| d8fe9a | 3 | This file documents the functions within the technic modpack for use in mods. |
| 987cc5 | 4 | |
| 9a39a9 | 5 | [Switch to plaintext format](https://raw.githubusercontent.com/minetest-mods/technic/master/technic/doc/api.md) |
| S | 6 | |
| 7 | **Undocumented API may change at any time.** | |
| 8 | ||
| 987cc5 | 9 | |
| d8fe9a | 10 | ## Tiers |
| S | 11 | Tier are network types. List of pre-registered tiers: |
| 12 | ||
| 13 | * `"LV"`, Low Voltage | |
| 14 | * `"MV"`, Medium Voltage | |
| 15 | * `"HV"`, High Voltage | |
| 16 | ||
| 17 | Available functions: | |
| 18 | ||
| 19 | * `technic.register_tier(tier, description)` | |
| 20 | * Registers a network type (tier) | |
| 21 | * `tier`: string, short name (ex. `LV`) | |
| 22 | * `description`: string, long name (ex. `Low Voltage`) | |
| 23 | * See also `tiers` | |
| 24 | ||
| 25 | ||
| 26 | ## Cables | |
| 27 | * `technic.register_cable(tier, size)` | |
| 28 | * Registers an existing node as cable | |
| 29 | * `tier`: string | |
| 30 | * `size`: number, visual size of the wire | |
| 31 | * `technic.get_cable_tier(nodename)` | |
| 32 | * Retrieves the tier assigned to the provided node name | |
| 33 | * `nodename`: string, name of the node | |
| 34 | * Returns the tier (string) or `nil` | |
| 35 | * `technic.is_tier_cable(nodename, tier)` | |
| 36 | * Tells whether the node `nodename` is the cable of the tier `tier`. | |
| 37 | * Short version of `technic.get_cable_tier(nodename) == tier` | |
| 38 | ||
| 39 | ||
| 40 | ## Machines | |
| 41 | The machine type indicates the direction of power flow. | |
| 42 | List of pre-registered machine types: | |
| 43 | ||
| 9a39a9 | 44 | * `technic.receiver = "RE"`: consumes energy. e.g. grinder |
| S | 45 | * `technic.producer = "PR"`: provides energy. e.g. solar panel |
| d8fe9a | 46 | * `technic.producer_receiver = "PR_RE"` supply converter |
| 9a39a9 | 47 | * `technic.battery = "BA"`: stores energy. e.g. LV battery box |
| d8fe9a | 48 | |
| S | 49 | Available functions: |
| 50 | ||
| 9a39a9 | 51 | * `technic.register_base_machine(data)` |
| S | 52 | * Registers a new node and defines the underlying machine behaviour. `data` fields: |
| 53 | * `tier`: string, see #Tiers | |
| 54 | * `typename`: string, equivalent to the processing type registered | |
| 55 | by `technic.register_recipe`. Examples: `"cooking"` `"alloy"` | |
| 56 | * `machine_name`: string, node name | |
| 57 | * `machine_desc`: string, node description | |
| 58 | * `demand`: table, EU consumption values for each upgrade level. | |
| 59 | Up to three indices. Index 1 == no upgrade. Example: `{3000, 2000, 1000}`. | |
| 60 | * `upgrade`: (boolean), whether to add upgrade slots | |
| 61 | * `modname`: (string), mod origin | |
| 62 | * `tube`: (boolean), whether the machine has Pipeworks connectivity | |
| 63 | * `can_insert`: (func), see Pipeworks documentation | |
| 64 | * Accepts all inputs by default, if `tube = 1` | |
| 65 | * See also: `technic.can_insert_unique_stack` | |
| 66 | * `insert_object`: (func), see Pipeworks documentation | |
| 67 | * Accepts all inputs by default, if `tube = 1` | |
| 68 | * See also: `technic.insert_object_unique_stack` | |
| 69 | * `connect_sides`: (table), see Lua API documentation. Defaults to all directions but front. | |
| d8fe9a | 70 | * `technic.register_machine(tier, nodename, machine_type)` |
| S | 71 | * Register an existing node as machine, bound to the network tier |
| 9a39a9 | 72 | * `tier`: string, see #Tiers |
| d8fe9a | 73 | * `nodename`: string, node name |
| S | 74 | * `machine_type`: string, following options are possible: |
| 9a39a9 | 75 | * `technic.receiver = "RE"`: Consumes energy |
| S | 76 | * `technic.producer = "PR"`: Provides energy |
| 77 | * `technic.battery = "BA"`: Energy storage | |
| d8fe9a | 78 | * See also `Machine types` |
| S | 79 | |
| 9a39a9 | 80 | Callbacks for pipeworks item transfer: |
| d8fe9a | 81 | |
| S | 82 | * `technic.can_insert_unique_stack(pos, node, stack, direction)` |
| 83 | * `technic.insert_object_unique_stack(pos, node, stack, direction)` | |
| 84 | * Functions for the parameters `can_insert` and `insert_object` to avoid | |
| 85 | filling multiple inventory slots with same type of item. | |
| 86 | ||
| 9a39a9 | 87 | ### Recipes |
| S | 88 | |
| 89 | * `technic.register_recipe_type(typename, recipedef)` | |
| 90 | * Registers a new recipe type used for machine processing | |
| 91 | * `typename`: string, name of the recipe type | |
| 92 | * Fields of `recipedef`: | |
| 93 | * `description`: string, descriptor of the recipe type | |
| 94 | * `input_size`: (numeric), count of input ItemStacks. default 1 | |
| 95 | * `output_size`: (numeric), count of output ItemStacks. default 1 | |
| 96 | * `technic.register_recipe(recipe)` | |
| 97 | * Registers a individual input/output recipe. Fields of `recipe`: | |
| 98 | * `input`: table, integer-indexed list of input ItemStacks. | |
| 99 | * `output`: table/ItemStack, single output or list of output ItemStacks. | |
| 100 | * `time`: numeric, process time in seconds. | |
| 101 | * `technic.get_recipe(typename, items)` | |
| 102 | * `typename`: string, see `technic.register_recipe_type` | |
| 103 | * `items`: table, integer-indexed list of input ItemStacks. | |
| 104 | * Returns: `recipe` table on success, `nil` otherwise | |
| 105 | ||
| 106 | ||
| 107 | The following functions can be used to register recipes for | |
| 108 | a specific machine type: | |
| 109 | ||
| 110 | * Centrifuge | |
| 111 | * `technic.register_separating_recipe(recipe)` | |
| 112 | * Compressor | |
| 113 | * `technic.register_compressor_recipe(recipe)` | |
| 114 | * Furnaces (electric, normal) | |
| 115 | * `minetest.register_recipe(recipe)` | |
| 116 | * Extractor | |
| 117 | * `technic.register_extractor_recipe(recipe)` | |
| 118 | * Freezer | |
| 119 | * `technic.register_freezer_recipe(recipe)` | |
| 120 | * Grinder | |
| 121 | * `technic.register_grinder_recipe(recipe)` | |
| d8fe9a | 122 | |
| S | 123 | |
| 124 | ## Tools | |
| 125 | * `technic.register_power_tool(itemname, max_charge)` | |
| 126 | * Register or configure the maximal charge held by an existing item | |
| 127 | * `craftitem`: string, item or node name | |
| 128 | * `max_charge`: number, maximal EU capacity | |
| 129 | ||
| 130 | ||
| 131 | ## Helper functions | |
| 132 | Unsorted functions: | |
| 133 | ||
| 41f175 | 134 | * `technic.EU_string(num)` |
| d8fe9a | 135 | * Converts num to a human-readable string (see `pretty_num`) |
| 41f175 | 136 | and adds the `EU` unit |
| H | 137 | * Use this function when showing players energy values |
| 987cc5 | 138 | * `technic.pretty_num(num)` |
| 41f175 | 139 | * Converts the number `num` to a human-readable string with SI prefixes |
| d8fe9a | 140 | * `technic.config:get(name)` |
| S | 141 | * Some configuration function |
| 142 | * `technic.tube_inject_item(pos, start_pos, velocity, item)` | |
| 143 | * Same as `pipeworks.tube_inject_item` | |
| 144 | ||
| 145 | ### Energy modifiers | |
| 987cc5 | 146 | * `technic.set_RE_wear(itemstack, item_load, max_charge)` |
| d8fe9a | 147 | * Modifies the power tool wear of the given itemstack |
| S | 148 | * `itemstack`: ItemStack to modify |
| 149 | * `item_load`: number, used energy in EU | |
| 150 | * `max_charge`: number, maximal EU capacity of the tool | |
| 151 | * The itemdef field `wear_represents` must be set to `"technic_RE_charge"`, | |
| 152 | otherwise this function will do nothing. | |
| 153 | * Returns the modified itemstack | |
| 987cc5 | 154 | * `technic.refill_RE_charge(itemstack)` |
| Y | 155 | * This function fully recharges an RE chargeable item. |
| 156 | * If `technic.power_tools[itemstack:get_name()]` is `nil` (or `false`), this | |
| 157 | function does nothing, else that value is the maximum charge. | |
| 158 | * The itemstack metadata is changed to contain the charge. | |
| d8fe9a | 159 | |
| S | 160 | ### Node-specific |
| 161 | * `technic.get_or_load_node(pos)` | |
| 162 | * If the mapblock is loaded, it returns the node at pos, | |
| 163 | else it loads the chunk and returns `nil`. | |
| 164 | * `technic.swap_node(pos, nodename)` | |
| 165 | * Same as `mintest.swap_node` but it only changes the nodename. | |
| 166 | * It uses `minetest.get_node` before swapping to ensure the new nodename | |
| 167 | is not the same as the current one. | |
| 987cc5 | 168 | * `technic.trace_node_ray(pos, dir, range)` |
| Y | 169 | * Returns an iteration function (usable in the for loop) to iterate over the |
| 170 | node positions along the specified ray. | |
| 171 | * The returned positions will not include the starting position `pos`. | |
| 172 | * `technic.trace_node_ray_fat(pos, dir, range)` | |
| 173 | * Like `technic.trace_node_ray` but includes extra positions near the ray. | |
| 174 | * The node ray functions are used for mining lasers. | |
| 175 | ||
| 176 | ||
| d8fe9a | 177 | ## Item Definition fields |
| S | 178 | Groups: |
| 987cc5 | 179 | |
| d8fe9a | 180 | * `technic_<tier> = 1` |
| S | 181 | * Makes the node connect to the cables of the matching tier name |
| 182 | * `<tier>`: name of the tier, in lowercase (ex. `lv`) | |
| 183 | * `technic_machine = 1` | |
| 184 | * UNRELIABLE. Indicates whether the item or node belongs to technic | |
| 185 | * `connect_sides = {"top", "left", ...}` | |
| 186 | * Extends the Minetest API. Indicates where the machine can be connected. | |
| 187 | ||
| 188 | Additional definition fields: | |
| 189 | ||
| 9a39a9 | 190 | * `<itemdef>.wear_represents = "string"` |
| d8fe9a | 191 | * Specifies how the tool wear level is handled. Available modes: |
| S | 192 | * `"mechanical_wear"`: represents physical damage |
| 193 | * `"technic_RE_charge"`: represents electrical charge | |
| 140701 | 194 | * `<itemdef>.technic_run = function(pos, node) ...` |
| S | 195 | * This callback is used to update the node. |
| 987cc5 | 196 | Modders have to manually change the information about supply etc. in the |
| Y | 197 | node metadata. |
| 9a39a9 | 198 | * Technic-registered machines use this callback by default. |
| 140701 | 199 | * `<itemdef>.technic_disabled_machine_name = "string"` |
| S | 200 | * Specifies the machine's node name to use when it's not connected connected to a network |
| 201 | * `<itemdef>.technic_on_disable = function(pos, node) ...` | |
| 202 | * This callback is run when the machine is no longer connected to a technic-powered network. | |
| 0211c5 | 203 | * `<itemdef>.technic_get_charge = function(itemstack) ...` |
| 9a39a9 | 204 | * Optional callback to overwrite the default charge behaviour. |
| S | 205 | * `itemstack`: ItemStack, the tool to analyse |
| 206 | * Return values: | |
| 207 | * `charge`: Electrical charge of the tool | |
| 208 | * `max_charge`: Upper charge limit | |
| 0211c5 | 209 | * Etc. `local charge, maxcharge = itemdef.technic_get_charge(itemstack)` |
| S | 210 | * `<itemdef>.technic_set_charge = function(itemstack, charge) ...` |
| 9a39a9 | 211 | * Optional callback to overwrite the default charge behaviour. |
| S | 212 | * `itemstack`: ItemStack, the tool to update |
| 213 | * `charge`: numeric, value between `0` and `max_charge` | |
| 140701 | 214 | |
| 987cc5 | 215 | |
| d8fe9a | 216 | ## Node Metadata fields |
| S | 217 | Nodes connected to the network will have one or more of these parameters as meta |
| 218 | data: | |
| 987cc5 | 219 | |
| d8fe9a | 220 | * `<tier>_EU_supply` - direction: output |
| S | 221 | * For nodes registered as `PR` or `BA` tier |
| 222 | * This is the EU value supplied by the node. | |
| 223 | * `<tier>_EU_demand` - direction: output | |
| 224 | * For nodes registered as `RE` or `BA` tier | |
| 225 | * This is the EU value the node requires to run. | |
| 226 | * `<tier>_EU_input` - direction: input | |
| 227 | * For nodes registered as `RE` or `BA` tier | |
| 228 | * This is the actual EU value the network can give the node. | |
| 229 | ||
| 230 | `<tier>` corresponds to the tier name registered using | |
| 231 | `technic.register_tier` (ex. `LV`). It is possible for the machine to depend on | |
| 232 | multiple tiers (or networks). | |
| 233 | ||
| 234 | ||
| 9a39a9 | 235 | ## Manual: Network basics |
| S | 236 | |
| 987cc5 | 237 | The switching station is the center of all power distribution on an electric |
| 9a39a9 | 238 | network. This node is used to calculate the power supply of the network and |
| S | 239 | to distribute the power across nodes. |
| 987cc5 | 240 | |
| 9a39a9 | 241 | The switching station is the center of all electricity distribution. It collects |
| S | 242 | power from sources (PR), distributes it to sinks (RE), and uses the |
| 243 | excess/shortfall to charge and discharge batteries (BA). | |
| 987cc5 | 244 | |
| 9a39a9 | 245 | As a thumb of rule, "EU" (energy unit) values are expressed in kW. |
| 987cc5 | 246 | |
| 9a39a9 | 247 | Network functionality: |
| 987cc5 | 248 | |
| 9a39a9 | 249 | 1. All PR, BA, RE nodes are indexed and tagged with one switching station. |
| S | 250 | The tagging is a workaround to allow more stations to be built without allowing |
| 251 | a cheat with duplicating power. | |
| 252 | 2. All the RE nodes are queried for their current EU demand. | |
| 253 | If the total demand is less than the available power they are all updated | |
| 254 | with the demand number. | |
| 255 | 3. BA nodes are evenly charged from energy surplus. | |
| 256 | 4. Excess power draw will discharge batteries evenly. | |
| 257 | 5. If the total demand is more than the available power all RE nodes will be shut | |
| 258 | down. We have a brown-out situation. | |
| 987cc5 | 259 | |
| d8fe9a | 260 | ## Deprecated functions |
| 987cc5 | 261 | |
| d8fe9a | 262 | Following functions are either no longer used by technic, or are planned to |
| S | 263 | be removed soon. Please update mods depending on technic accordingly. |
| 264 | ||
| 265 | * `technic.get_RE_item_load` | |
| 266 | * Scales the tool wear to a certain numeric range | |
| 267 | * `technic.set_RE_item_load` | |
| 268 | * Scales a certain numeric range to the tool wear | |
