| 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 | |
| Y | 5 | |
| d8fe9a | 6 | ## Tiers |
| S | 7 | Tier are network types. List of pre-registered tiers: |
| 8 | ||
| 9 | * `"LV"`, Low Voltage | |
| 10 | * `"MV"`, Medium Voltage | |
| 11 | * `"HV"`, High Voltage | |
| 12 | ||
| 13 | Available functions: | |
| 14 | ||
| 15 | * `technic.register_tier(tier, description)` | |
| 16 | * Registers a network type (tier) | |
| 17 | * `tier`: string, short name (ex. `LV`) | |
| 18 | * `description`: string, long name (ex. `Low Voltage`) | |
| 19 | * See also `tiers` | |
| 20 | ||
| 21 | ||
| 22 | ## Cables | |
| 23 | * `technic.register_cable(tier, size)` | |
| 24 | * Registers an existing node as cable | |
| 25 | * `tier`: string | |
| 26 | * `size`: number, visual size of the wire | |
| 27 | * `technic.get_cable_tier(nodename)` | |
| 28 | * Retrieves the tier assigned to the provided node name | |
| 29 | * `nodename`: string, name of the node | |
| 30 | * Returns the tier (string) or `nil` | |
| 31 | * `technic.is_tier_cable(nodename, tier)` | |
| 32 | * Tells whether the node `nodename` is the cable of the tier `tier`. | |
| 33 | * Short version of `technic.get_cable_tier(nodename) == tier` | |
| 34 | ||
| 35 | ||
| 36 | ## Machines | |
| 37 | The machine type indicates the direction of power flow. | |
| 38 | List of pre-registered machine types: | |
| 39 | ||
| 40 | * `technic.receiver = "RE"` e.g. grinder | |
| 41 | * `technic.producer = "PR"` e.g. solar panel | |
| 42 | * `technic.producer_receiver = "PR_RE"` supply converter | |
| 43 | * `technic.battery = "BA"` e.g. LV battery box | |
| 44 | ||
| 45 | Available functions: | |
| 46 | ||
| 47 | * `technic.register_machine(tier, nodename, machine_type)` | |
| 48 | * Register an existing node as machine, bound to the network tier | |
| 49 | * `tier`: see `register_tier` | |
| 50 | * `nodename`: string, node name | |
| 51 | * `machine_type`: string, following options are possible: | |
| 52 | * `"RE"`: Receiver | |
| 53 | * `"PR"`: Producer | |
| 54 | * `"BA"`: Battery, energy storage | |
| 55 | * See also `Machine types` | |
| 56 | ||
| 57 | Functions to use for callbacks: | |
| 58 | ||
| 59 | * `technic.can_insert_unique_stack(pos, node, stack, direction)` | |
| 60 | * `technic.insert_object_unique_stack(pos, node, stack, direction)` | |
| 61 | * Functions for the parameters `can_insert` and `insert_object` to avoid | |
| 62 | filling multiple inventory slots with same type of item. | |
| 63 | ||
| 64 | ### Specific machines | |
| 65 | * `technic.register_solar_array(data)` | |
| 66 | * data is a table (TODO) | |
| 67 | ||
| 68 | ||
| 69 | ## Tools | |
| 70 | * `technic.register_power_tool(itemname, max_charge)` | |
| 71 | * Register or configure the maximal charge held by an existing item | |
| 72 | * `craftitem`: string, item or node name | |
| 73 | * `max_charge`: number, maximal EU capacity | |
| 74 | ||
| 75 | ||
| 76 | ## Helper functions | |
| 77 | Unsorted functions: | |
| 78 | ||
| 41f175 | 79 | * `technic.EU_string(num)` |
| d8fe9a | 80 | * Converts num to a human-readable string (see `pretty_num`) |
| 41f175 | 81 | and adds the `EU` unit |
| H | 82 | * Use this function when showing players energy values |
| 987cc5 | 83 | * `technic.pretty_num(num)` |
| 41f175 | 84 | * Converts the number `num` to a human-readable string with SI prefixes |
| d8fe9a | 85 | * `technic.config:get(name)` |
| S | 86 | * Some configuration function |
| 87 | * `technic.tube_inject_item(pos, start_pos, velocity, item)` | |
| 88 | * Same as `pipeworks.tube_inject_item` | |
| 89 | ||
| 90 | ### Energy modifiers | |
| 987cc5 | 91 | * `technic.set_RE_wear(itemstack, item_load, max_charge)` |
| d8fe9a | 92 | * Modifies the power tool wear of the given itemstack |
| S | 93 | * `itemstack`: ItemStack to modify |
| 94 | * `item_load`: number, used energy in EU | |
| 95 | * `max_charge`: number, maximal EU capacity of the tool | |
| 96 | * The itemdef field `wear_represents` must be set to `"technic_RE_charge"`, | |
| 97 | otherwise this function will do nothing. | |
| 98 | * Returns the modified itemstack | |
| 987cc5 | 99 | * `technic.refill_RE_charge(itemstack)` |
| Y | 100 | * This function fully recharges an RE chargeable item. |
| 101 | * If `technic.power_tools[itemstack:get_name()]` is `nil` (or `false`), this | |
| 102 | function does nothing, else that value is the maximum charge. | |
| 103 | * The itemstack metadata is changed to contain the charge. | |
| d8fe9a | 104 | |
| S | 105 | ### Node-specific |
| 106 | * `technic.get_or_load_node(pos)` | |
| 107 | * If the mapblock is loaded, it returns the node at pos, | |
| 108 | else it loads the chunk and returns `nil`. | |
| 109 | * `technic.swap_node(pos, nodename)` | |
| 110 | * Same as `mintest.swap_node` but it only changes the nodename. | |
| 111 | * It uses `minetest.get_node` before swapping to ensure the new nodename | |
| 112 | is not the same as the current one. | |
| 987cc5 | 113 | * `technic.trace_node_ray(pos, dir, range)` |
| Y | 114 | * Returns an iteration function (usable in the for loop) to iterate over the |
| 115 | node positions along the specified ray. | |
| 116 | * The returned positions will not include the starting position `pos`. | |
| 117 | * `technic.trace_node_ray_fat(pos, dir, range)` | |
| 118 | * Like `technic.trace_node_ray` but includes extra positions near the ray. | |
| 119 | * The node ray functions are used for mining lasers. | |
| 120 | ||
| 121 | ||
| d8fe9a | 122 | ## Item Definition fields |
| S | 123 | Groups: |
| 987cc5 | 124 | |
| d8fe9a | 125 | * `technic_<tier> = 1` |
| S | 126 | * Makes the node connect to the cables of the matching tier name |
| 127 | * `<tier>`: name of the tier, in lowercase (ex. `lv`) | |
| 128 | * `technic_machine = 1` | |
| 129 | * UNRELIABLE. Indicates whether the item or node belongs to technic | |
| 130 | * `connect_sides = {"top", "left", ...}` | |
| 131 | * Extends the Minetest API. Indicates where the machine can be connected. | |
| 132 | ||
| 133 | Additional definition fields: | |
| 134 | ||
| 135 | * `wear_represents = "string"` | |
| 136 | * Specifies how the tool wear level is handled. Available modes: | |
| 137 | * `"mechanical_wear"`: represents physical damage | |
| 138 | * `"technic_RE_charge"`: represents electrical charge | |
| 139 | * `<itemdef>.technic_run(pos, node)` | |
| 987cc5 | 140 | * This function is currently used to update the node. |
| Y | 141 | Modders have to manually change the information about supply etc. in the |
| 142 | node metadata. | |
| 143 | ||
| d8fe9a | 144 | ## Node Metadata fields |
| S | 145 | Nodes connected to the network will have one or more of these parameters as meta |
| 146 | data: | |
| 987cc5 | 147 | |
| d8fe9a | 148 | * `<tier>_EU_supply` - direction: output |
| S | 149 | * For nodes registered as `PR` or `BA` tier |
| 150 | * This is the EU value supplied by the node. | |
| 151 | * `<tier>_EU_demand` - direction: output | |
| 152 | * For nodes registered as `RE` or `BA` tier | |
| 153 | * This is the EU value the node requires to run. | |
| 154 | * `<tier>_EU_input` - direction: input | |
| 155 | * For nodes registered as `RE` or `BA` tier | |
| 156 | * This is the actual EU value the network can give the node. | |
| 157 | ||
| 158 | `<tier>` corresponds to the tier name registered using | |
| 159 | `technic.register_tier` (ex. `LV`). It is possible for the machine to depend on | |
| 160 | multiple tiers (or networks). | |
| 161 | ||
| 162 | ||
| 163 | ## Switching Station mechanics | |
| 987cc5 | 164 | The switching station is the center of all power distribution on an electric |
| Y | 165 | network. |
| 166 | ||
| 167 | The station collects power from sources (PR), distributes it to sinks (RE), | |
| 168 | and uses the excess/shortfall to charge and discharge batteries (BA). | |
| 169 | ||
| 170 | For now, all supply and demand values are expressed in kW. | |
| 171 | ||
| 172 | It works like this: | |
| 173 | All PR,BA,RE nodes are indexed and tagged with the switching station. | |
| 174 | The tagging is a workaround to allow more stations to be built without allowing | |
| 175 | a cheat with duplicating power. | |
| 176 | All the RE nodes are queried for their current EU demand. Those which are off | |
| 177 | would require no or a small standby EU demand, while those which are on would | |
| 178 | require more. | |
| 179 | If the total demand is less than the available power they are all updated with | |
| 180 | the demand number. | |
| 181 | If any surplus exists from the PR nodes the batteries will be charged evenly | |
| 182 | with this. | |
| 183 | If the total demand requires draw on the batteries they will be discharged | |
| 184 | evenly. | |
| 185 | ||
| 186 | If the total demand is more than the available power all RE nodes will be shut | |
| 187 | down. We have a brown-out situation. | |
| 188 | ||
| 189 | Hence for now all the power distribution logic resides in this single node. | |
| 190 | ||
| d8fe9a | 191 | ## Deprecated functions |
| 987cc5 | 192 | |
| d8fe9a | 193 | Following functions are either no longer used by technic, or are planned to |
| S | 194 | be removed soon. Please update mods depending on technic accordingly. |
| 195 | ||
| 196 | * `technic.get_RE_item_load` | |
| 197 | * Scales the tool wear to a certain numeric range | |
| 198 | * `technic.set_RE_item_load` | |
| 199 | * Scales a certain numeric range to the tool wear | |
