Back
TreeCapitator Wiki

Add-On Integration

Make your Add-On's trees work with TreeCapitator.

Dev mode scans your trees in-game and writes the registration code for you. Six steps and you're done.

Every log must connect to the trunk through other logs, side by side or diagonally. Logs floating inside the leaves, with no other log touching them, can't be detected, so trees built like that can't be supported.

Use a test world. Planting saplings in dev mode clears a large area around you.

1

Turn on dev mode

In a world with cheats on, run this command. Your TreeCapitator book now opens the dev menu.

/scriptevent treecapitator:dev
2

Plant your trees

Drop (Q) one of your saplings and TreeCapitator plants 10 of them around you. Bonemeal them to grow.

3

Scan them

Hold a stick and break a grown tree. It doesn't break: it gets scanned and works with TreeCapitator right away. Scan a few of each type to catch all their shapes.

4

Set the check item

Open the book, tap your Add-On, then Check item. Drop (Q) an item only your Add-On adds, like its guide book. TreeCapitator uses it to tell whether your Add-On is installed.

5

Export

Tap Export. The registration code appears in chat and in the Content Log (turn it on under Settings › Creator), ready to copy.

6

Paste it into your script

Paste the code into your Add-On's script. It looks like this:

import { system, world } from "@minecraft/server";

// TreeCapitator registration for "mynature"
world.afterEvents.worldLoad.subscribe(() => {
  system.sendScriptEvent("treecapitator:register_addon", `{"name":"mynature",...}`);
});

Done!

Your trees now work with TreeCapitator. Hold an axe and look at a trunk: the outline shows exactly what gets cut.

Good to know

  • Scanned trees are forgotten when the world reloads, so export before you leave.
  • The exported name is your namespace. Change it to your Add-On's real name, since players see it in TreeCapitator's settings. If the export was split into several events, change addonName in each of them too.
  • Custom axes work automatically when they have the minecraft:is_axe tag or their ID ends in _axe. For anything else, see Axes below.
  • Does your Add-On change vanilla trees, like their leaves, logs or shape? Scan those trees too. They're exported as vanilla overwrites, so TreeCapitator handles your version of the tree.

Reference

Only needed if you want to write or tweak the registration yourself.

Writing it by hand

Send treecapitator:register_addon with your Add-On as JSON when the world loads:

import { system, world } from "@minecraft/server";

const myAddon = {
  name: "My Nature Add-On",
  item_check: "mynature:guide_book",
  trees: [
    {
      id: "mynature:maple_log",
      leaves: { types: ["mynature:maple_leaves"], range: 6, sides_required: 3 },
      shape: { log_up_diagonal: true },
    },
  ],
};

world.afterEvents.worldLoad.subscribe(() => {
  system.sendScriptEvent("treecapitator:register_addon", JSON.stringify(myAddon));
});
FieldWhat it does
name requiredYour Add-On's name, shown in TreeCapitator's settings.
item_checkAn item only your Add-On adds, used to tell whether it's installed.
treesYour trees, see Tree fields.
axesYour axes, see Axes.
leaves.persistent_stateDefault leaf decay state for all your trees, so you don't have to repeat it per tree.
on_loadA command to run after your Add-On is registered.
Tree fields
FieldWhat it does
id requiredThe tree's log block ID.
leaves.types requiredThe tree's leaf block IDs.
leaves.range requiredHow far from the trunk to look for leaves, like vanilla leaf distance.
leaves.sides_required requiredHow many directions (north, east, south, west and up) need leaves for it to count as a tree. 1 to 5, not a leaf count.
leaves.persistent_stateThe block state that marks player-placed leaves, like persistent_bit. Those are left alone.
leaves.exclusive_typesFor leaf colors where each tree has only one, like red, orange and yellow poplar leaves. Stops a tree from taking a touching neighbour's leaves.
variantsOther logs of the same tree, like a mossy log.
attachmentsBlocks hanging on the tree, like fruit, nests or vines. They pop off when the tree is cut.
netherMarks a Nether tree, which has its own leaf setting.
langA different name to show in the settings: a language key or plain text. Defaults to the log's own name.
shape.stemA 2×2 trunk, like giant jungle trees.
shape.leaf_diagonalLeaves connect diagonally.
shape.log_up_diagonalLogs go diagonally upwards.
shape.log_up_diagonal_sideLogs go diagonally upwards and sideways.
shape.log_downBranches that droop back down.
shape.max_branchThe longest sideways branch. Only set it if your trees have sideways branches.
Axes

Axes are detected automatically when they have the minecraft:is_axe tag or their ID ends in _axe. Only register an axe when neither is true, or to give it a nicer name in the settings. Add it to your registration:

axes: [
  { id: "mynature:lumber_cleaver" },
  { id: "mynature:maple_axe", lang: "Maple Axe" },
],
FieldWhat it does
id requiredThe axe's item ID.
langA different name to show in the settings: a language key or plain text. Defaults to the axe's own name.
Large Add-Ons

A script event holds about 2000 characters. If your registration is bigger, register the Add-On first, then add trees and axes in batches. addonName must match name exactly. Dev mode's export splits it for you.

const name = "My Nature Add-On";
system.sendScriptEvent("treecapitator:register_addon", JSON.stringify({ name, item_check: "mynature:guide_book" }));
system.sendScriptEvent("treecapitator:add_trees", JSON.stringify({ addonName: name, trees: [/* first batch */] }));
system.sendScriptEvent("treecapitator:add_trees", JSON.stringify({ addonName: name, trees: [/* second batch */] }));
system.sendScriptEvent("treecapitator:add_axes", JSON.stringify({ addonName: name, axes: [/* ... */] }));
Changing vanilla trees

Send treecapitator:overwrite_trees with vanilla log IDs and only the fields you want to change. Leaf types and variants you list are added to the vanilla ones; everything else keeps its default. You can send it more than once.

system.sendScriptEvent(
  "treecapitator:overwrite_trees",
  JSON.stringify({
    "minecraft:oak_log": {
      leaves: { types: ["mynature:blossom_oak_leaves"] },
      shape: { max_branch: 3 },
    },
  })
);

Vanilla trees you can change:

minecraft:oak_log minecraft:birch_log minecraft:spruce_log minecraft:jungle_log minecraft:acacia_log minecraft:dark_oak_log minecraft:mangrove_log minecraft:cherry_log minecraft:pale_oak_log minecraft:poplar_log minecraft:crimson_stem minecraft:warped_stem