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