API

Mechanization is modularized into a set of event calls and scoreboard information. As such, it is very easy to develop add-ons that use Mechanization's features to create a seamless experience. This page documents everything you might find useful in creating an add-on.

Important References:

Mechanization depends on Datapack Utils for things like crafting, smelting, custom tools and world generation. Since Mech depends on DU, you can use all of its API in your project as well. You can get more information over on its wiki.

Mechanization follows (as closely as possible) the conventions specified by the Minecraft Datapacks community, which helps to maintain compatibility between datapacks. You can reference them here: https://mc-datapacks.github.io/en/

Energy API

Mechanization's foremost feature is the energy grid. This is conducted wirelessly by batteries and/or capacitors. To add a machine to the energy grid, summon an entity with one of the following tags. Then, set its score mech_power to 0

mech_transmitter: Indicates that this device generates power, and should have power taken from it and put into batteries.
mech_receiver: Indicates that this device uses power, and should take power from batteries.

Example:

summon item_frame ~ ~ ~ {Tags:["mech_receiver","custom_machine"],Fixed:1b}
scoreboard players set @e[tag=custom_machine,sort=nearest,limit=1] mech_power 0

If you've created a machine correctly, it should automatically be included in the energy grid and batteries/capacitors will start taking or sending power respectively. Now, if you want to generate power, increase the value of the mech_power score, and if you want to consume power, decrease the value of the mech_power score.

Adding Batteries/Capacitors

To create a new battery that can send and receive power, summon an entity with the tag mech_power_storage. Then, in the devices ticking function run both as and at the entity (recommend 1 time per second), run this code:

scoreboard players set $in_0 mech_data <max transfer speed>
scoreboard players set $in_1 mech_data <max machine buffer capacity>
scoreboard players set $in_2 mech_data <max battery capacity>
scoreboard players set $in_3 mech_data <Range: 4,8,12,16,20,24,28, or 32>
scoreboard players set $in_4 mech_data <0 for no effects (particle, sound), 1 for effects>
function mechanization:base/energy/standard

#Alternitive: it your device is supposed to be a battery and draw power from nearby capacitors when they are full, use this command:
#function mechanization:base/energy/battery

#Alternitive: it your device is supposed to be a capacitor and draw energy from nearby batteries when empty, use this command:
#function mechanization:base/energy/capacitor

If you plan on making a standalone datapack compatible use Mech's energy system by copying the energy transfer function, make sure to also copy the supporting files. At your convenience, these can be renamed or put in a different location if you also modify the references in the energy transfer function.

data/mechanization/predicates/matches_gridid
data/mechanization/predicates/base/valid_transmitter

Also make sure to initialize these scoreboards in your load function:

scoreboard objectives add mech_data dummy
scoreboard objectives add mech_power dummy
scoreboard objectives add mech_gridid dummy

Portable Energy

Mechanization supports drawing energy from compatible items in the player's hotbar. This is done using these lines of code:

scoreboard players set in_0 mech_data <amount>
function mechanization:base/tools/player_energy/use_energy

execute if score $out_0 mech_data matches 1 run <do something>

It is recommended to use built-in portable energy items (like Gadget's Portable Battery), but if you would like to make your own, you can use the following command:

give @s carrot_on_a_stick{ mech_battery:{energy:0, max_energy:32000, models:8, base_model:6424900} }

energy: how much power the battery has- usually new batteries have 0
max_energy: how much the battery can hold- the Portable Battery holds 32000 kJ
models: how many models the battery uses to represent charged states. For example, the Portable Battery has a green bar the goes up and down based on energy level that uses 8 models. If you don't have any extra models, set this to 1.
base_model: the stating CMD for extra models. If you don't have extra models, this should be the items normal CMD.

Events

There are several event hooks built into mechanization. These are run using a function tag. To extend the event, in your datapack create the folder data/mechanization/tags/functions/[function] and add your functions in that tag (make sure to extend, not overwrite!).

Tools

• wrench_break: triggers when player shift+right clicks a wrench, at the location they are looking. Should be used to safely break machines.
• wrench_function: triggers when player right clicks the wrench, at the location they are looking. Should be used to altar a machine setting, i.e. changing modes or rotating.
• multimeter_readout: triggers when player right clicks a multimeter, at the location they are looking. By default, prints out how much power the device is currently storing. Can be used to print out additional information.

Machine Tags

These are entity tags (ie. tag add @s mech_no_upgrade). Some states are tracked using tags.

• mech_transmitter: indicates the devices should send power (ie. is a generator)
• mech_receiver: indicates the devices should receive power (ie. is a machine)
• mech_power_storage: indicates the device acts like a battery/capacitor and stores power. Enables interactions with the Energy Relay.
• mech_no_upgrade: By default, any device can be upgraded. Adding this tag prevents that from happening.
• mech_upgraded: Tag added to a machine when a machine upgrade is applied. You should add in effects for each machine when upgraded (works faster, uses less energy, etc).
• mech_ender_upgrade: Tag added to a machine when an ender upgrade is applied. Machines require a machine upgrade to already be installed to add an ender upgrade (machine will have this tag AND mech_upgraded). This upgrade is exclusive to Nether Upgrades, so only 1 of the 2 can be added. Ender upgrades typically increase operating efficiency.
• mech_nether_upgrade: Tag added to a machine when an nether upgrade is applied. Machines require a machine upgrade to already be installed to add an nether upgrade (machine will have this tag AND mech_upgraded). This upgrade is exclusive to Ender Upgrade, so only 1 of the 2 can be added. Nether upgrades typically increase speed or power, but at a cost.
• mech_rotatable: indicates a machine's model should be rotated by a wrench (like the alloy furnace)

Scoreboard Information

---

• mech_data: For math, temp variables and other misc data storage. Also used to store an extra bit of data on machines. Could be anything.
• mech_power: indicates power level on a machine/generator/battery.
• mech_gridid: used internally to specify machines' grid ids. You probably shouldn't mess with this.
• mech_usedid: has the Mechanization item ID of whatever the player is holding (if it has an ID), specified by the mech_itemid:<id> nbt tag. Very useful for checking what a player is holding instead of using an NBT check.
• mech_fluid: used to track how much fluid a machine is holding in its tank. Other objectives may be used if the machine has multiple tanks.
• mech_timer: used by machines to track the length of their current operation

Liquid Mechanics

---

Coming Soon™

Ore Dictonary

---

As of v3.0, Mechanization's ore dictonary system as been updated to follow the Minecraft Datapacks community guidelines on Ore Dict. You can reference them here: https://mc-datapacks.github.io/en/conventions/common_trait.html

The shorthand is Mech now uses the following format: Item.tag.ctc{id:"tin_ingot", from:"mechanization", traits:{ingot:1b, "metal/tin":1b}}

Tips

---

• While your free to create any content in an add on if you want, it’s generally better to avoid overlapping content for performance reasons. Like, don't add another machine for processing ores unless it's unique.
• Need an API hook or think that something should be added to the API? Please post a suggestion in the issue tracker or on discord.