For Add-On Creators

Read current mana

import { world } from "@minecraft/server"

const player = /* your player */
const current = Number(player.getDynamicProperty("5fs:mana")) || 0
console.log(`Player has ${current} mana`)

Spend mana for your own spell

Same pattern every BR spell uses. The cost is always clamped at 0 and rejected if the player can't afford it.

function spendMana(player, cost) {
  const current = Number(player.getDynamicProperty("5fs:mana")) || 0
  if (current < cost) {
    player.setActionBar?.(`§cNot enough mana! Need ${cost}, have ${current.toFixed(1)}`)
    return false
  }
  player.setDynamicProperty("5fs:mana", Math.max(0, current - cost))
  return true
}

// in your item's onUse hook
if (!spendMana(source, 5)) return
// …cast the spell…

Maximum mana

Maximum mana is stored directly on the player as a dynamic property. BR's Sky Star and accessory systems write to it; an add-on that just wants to read the ceiling should do so and move on.

const MANA_DEFAULT_MAX = 10    // BR's out-of-the-box player max
const rawMax = Number(player.getDynamicProperty("5fs:maxMana"))
const max = Number.isFinite(rawMax) ? Math.max(rawMax, MANA_DEFAULT_MAX) : MANA_DEFAULT_MAX

Don't write 5fs:maxMana or 5fs:mana_points from an add-on. BR's accessory system recomputes max mana whenever the player's loadout changes and will clobber whatever you wrote. To grant temporary mana headroom, raise mana, not the cap.

Night-cost discount (not externally exposed)

BR's Talisman of Moonlight cuts every BR spell's mana cost by 20% at night (13000 ≤ time-of-day < 23000). The check uses BR's internal hasTalisman(player, "5fs_br:talisman_of_moonlight") helper, which walks the player's accessory-slot entities. That helper isn't exported to add-ons, so your custom spells can't mirror the discount yet. Two options:

• Charge full cost in your spell regardless of time-of-day and the discount simply won't apply. No crash, just less consistency with BR spells.
• Open a support request asking for hasTalisman + isNightTimeto be re-exported from BR's talismanSystem.js.

How a tree is detected

On break, the axe scans outward in waves up to MAX_TREE_SIZE blocks. A neighbor is part of the same tree if it shares the same family as the broken block (e.g. oak, maple, redwood). Wart blocks and shroomlight count as a universal nether family.

Tags

Add one of these block tags to every log/leaf in your custom tree. Use the same <group> across the whole tree so its blocks all match each other.

• 5fs_br:tree_log_<group> on every log / wood / hyphae block.
• 5fs_br:tree_leaves_<group> on every leaf block.
• 5fs_br:tree_root_<group> (optional) for root-style blocks like mangrove roots.

Block JSON example

// blocks/bloodwood_log.json
{
  "format_version": "1.21.0",
  "minecraft:block": {
    "description": { "identifier": "yourpack:bloodwood_log" },
    "components": {
      "tag:5fs_br:tree_log_bloodwood": {},
      "tag:minecraft:is_axe_item_destructible": {}
    }
  }
}

// blocks/bloodwood_leaves.json
"components": {
  "tag:5fs_br:tree_leaves_bloodwood": {}
}

Drops

Tag-defined logs and leaves drop themselves by default with no extra rolls. If you want sapling/stick rolls for your leaves or a custom drop item for your log, drop the BR team a list of block IDs in Requesting Supportand they'll get added to the LOG_DROPS / LEAF_DROPS tables. Tags handle 95% of the work; drop tables are an opt-in extra.

How vein-grouping works

Two blocks count as the same vein if their resolved vein key matches. For BR ores the key is the normalized id (Deepslate Iron Ore and Stone Iron Ore both resolve to minecraft:iron_ore). For your custom ores, the key is 5fs_br:vein:<group> derived from the tag below.

Tag

Add this tag to every variant of your ore (the regular and deepslate forms, for example) using the same <group>:

• 5fs_br:vein_ore_<group> on every ore block in the family.

Block JSON example

// blocks/cobalt_ore.json AND blocks/deepslate_cobalt_ore.json
"components": {
  "tag:5fs_br:vein_ore_cobalt": {},
  "tag:minecraft:is_pickaxe_item_destructible": {}
}

Drops

Tag-defined ores drop themselves once per vein block. The natural break already produces one drop, so the start block is skipped. By default there's no fortune scaling and no XP; opt in per ore with the tags below.

// blocks/cobalt_ore.json AND blocks/deepslate_cobalt_ore.json
"components": {
  "tag:5fs_br:vein_ore_cobalt": {},
  "tag:5fs_br:vein_drops_xp": {},
  "tag:5fs_br:vein_accepts_fortune": {},
  "tag:minecraft:is_pickaxe_item_destructible": {}
}

Tag-defined ores always drop themselves, not a raw material. If you want the ore to drop a different item (e.g. Raw Cobalt instead of the ore block), open a support request and the BR team will add a dropTable entry for your ore.

How lookup works

On every fuel check, BR walks three paths in order:

1. Direct id match against BR's bundled nativeFuels table (coal, coal block, dried kelp block, lava bucket, the whole wood family, …).
2. Tag match against the same table using the tag:item:<tag> lookup. This is how, for example, anything carrying minecraft:coals(like charcoal) inherits coal's burn time.
3. Creator-registered burn time encoded in a tag named 5fs_br:fuel_<ticks>. The number after the underscore is the burn duration in ticks (20 ticks = 1 second).

Item JSON example

Add the fuel tag to your item's minecraft:tags list. Same burn-time scale as vanilla: 1600 ticks (80 s) is one coal, 16000 ticks is a block of coal, 20000 ticks is a lava bucket.

// items/dense_coal.json
{
  "format_version": "1.21.0",
  "minecraft:item": {
    "description": { "identifier": "yourpack:dense_coal" },
    "components": {
      "minecraft:tags": {
        "tags": ["5fs_br:fuel_3200"]
      }
    }
  }
}

// burn time: 3200 ticks = 160 seconds, twice a normal coal.

Reference burn times

Gotchas

• BR reads the firstmatching tag it finds. Don't add multiple 5fs_br:fuel_* tags to the same item.
• Non-numeric or zero/negative tags are ignored silently. If your fuel isn't burning, double-check the integer after the underscore.
• Fuels that should leave a return item (like the lava bucket leaves an empty bucket) still need a dropTable entry in nativeFuels. Tag-based fuels always consume one unit and leave nothing.
• This only covers BR's custom furnaces and the Forge. The vanilla furnace / blast furnace / smoker use Minecraft's own fuel list and ignore this tag.

Supported stations

Note the spelling: the Rune Table's tag is runetable (one word), not rune_table. BR's built-in recipes use that exact tag, so a typo here means your recipe simply won't show up at the station.

Recipe JSON example

Standard minecraft:recipe_shaped with the station tag. Drop it in recipes/jeweling_station/ (or anywhere; only the tag matters).

// recipes/jeweling_station/charm_of_thunder.json
{
  "format_version": "1.20.80",
  "minecraft:recipe_shaped": {
    "description": { "identifier": "yourpack:charm_of_thunder" },
    "tags": ["jeweling_station"],
    "key": {
      "O": { "item": "minecraft:diamond" },
      "P": { "item": "yourpack:thunder_essence" }
    },
    "pattern": [
      "OPO",
      "PPP",
      "OPO"
    ],
    "result": [
      { "item": "yourpack:charm_of_thunder" }
    ]
  }
}

Stations that aren't recipe-driven

The Forge and Advanced Smithing Table use script-side recipe tables (forgeRecipes.js and an inline conversion map respectively), not vanilla recipe JSONs. Adding a recipe to either currently means a code edit. Open a support request with your inputs / output / smelt time and the BR team can ship the entry. The Charm Beacon, Magical Anvil, Ore Grinder, and Quarry tiers don't have a player-facing recipe surface at all; they consume specific items by id only.

Visibility

Your tag-based recipe works the moment a player tries to craft it at the matching station in-game. It will notshow up in BR's in-game guidebook (the guide pages are hand-curated, not auto-discovered) and won't appear on the Recipes wiki page either, since that page only indexes recipes shipped inside the BR pack itself.

How it works

When any custom entity spawns, BR reads the current world difficulty and fires one of three events on the entity:

• 5fs_br:set_easy on Easy
• (nothing on Medium; your base components are treated as the baseline)
• 5fs_br:set_hard on Hard
• 5fs_br:set_brutal on Brutal

Define these events on your mob with component groups that replace the relevant stats. If your mob ignores the events, it stays on its base stats on every difficulty; no crash, no warning.

Entity JSON example

This is the exact pattern every BR mob uses. Swap in your own stat values per tier.

// entities/mobs/my_cool_mob.json
{
  "minecraft:entity": {
    "description": { "identifier": "yourpack:my_cool_mob" },
    "component_groups": {
      "5fs_br:difficulty_easy": {
        "minecraft:health": { "value": 12, "max": 12 },
        "minecraft:attack": { "damage": 2 }
      },
      "5fs_br:difficulty_hard": {
        "minecraft:health": { "value": 34, "max": 34 },
        "minecraft:attack": { "damage": 5 }
      },
      "5fs_br:difficulty_brutal": {
        "minecraft:health": { "value": 50, "max": 50 },
        "minecraft:attack": { "damage": 8 }
      }
    },
    "components": {
      // Medium (baseline) values live on the entity itself.
      "minecraft:health": { "value": 20, "max": 20 },
      "minecraft:attack": { "damage": 3 }
    },
    "events": {
      "5fs_br:set_easy":   { "add": { "component_groups": ["5fs_br:difficulty_easy"]   } },
      "5fs_br:set_hard":   { "add": { "component_groups": ["5fs_br:difficulty_hard"]   } },
      "5fs_br:set_brutal": { "add": { "component_groups": ["5fs_br:difficulty_brutal"] } }
    }
  }
}

Projectile and explosion damage

BR also multiplies damage that your mob deals to players via projectiles or explosions by a world-wide scalar (0.6 / 1.0 / 1.7 / 2.5 for Easy / Medium / Hard / Brutal). You don't need to do anything; any custom mob projectile that hits a player runs through the same damage pipeline. Melee damage is not scaled this way; put tier-specific damage values in the event component groups above instead.

Reading the current difficulty from scripts

The world difficulty lives on the world as a dynamic property. Read it directly if your own script logic needs to branch on the tier (e.g. a spell that scales its damage with the world difficulty):

import { world } from "@minecraft/server"

const tier = world.getDynamicProperty("5fs_br:world_difficulty")
//   → "easy" | "medium" | "hard" | "brutal" | undefined

// undefined means the operator hasn't picked a tier yet.
// Fall back to "medium" so your mob behaves reasonably in that window.
const effective = tier ?? "medium"

Do not set 5fs_br:world_difficulty from an add-on. BR's UI is the only place that writes it, and operator-only by design.

Gotchas

• Medium has no event. Your base components are the Medium values. Don't try to add a 5fs_br:difficulty_medium group, it won't fire.
• BR applies the event on spawn. Mobs that spawned before the operator set a difficulty keep their base stats; new spawns pick up the current tier.
• A mob that already has minecraft:type_family entries like player, minecraft:item, or minecraft:xp_orb is skipped by the scaler. Only entities with a minecraft:health component that aren't on BR's skip list get the event.

The pattern

Define a component group holding the variant's replacement stats, then hook it to a minecraft:entity_spawned event that filters on has_biome_tag. Biome tags come from the biome's own definition (vanilla Minecraft sets tags like forest, desert, and BR adds redwood_forest, maple_forest, etc.).

Entity JSON example

Copied from BR's Vulture. The sequencearray runs both branches on spawn; each branch's filter controls whether its add block actually applies. Add more branches for additional biomes.

// entities/mobs/my_mob.json (abridged)
"component_groups": {
  "yourpack:redwood_variant": {
    "minecraft:attack":   { "damage": 6 },
    "minecraft:health":   { "value": 40, "max": 40 },
    "minecraft:movement": { "value": 1 }
  },
  "yourpack:ground_mode": { /* shared baseline behaviors */ }
},
"events": {
  "minecraft:entity_spawned": {
    "sequence": [
      {
        "filters": {
          "test": "has_biome_tag",
          "operator": "==",
          "value": "redwood_forest"
        },
        "add": {
          "component_groups": [
            "yourpack:ground_mode",
            "yourpack:redwood_variant"
          ]
        }
      },
      {
        "filters": {
          "test": "has_biome_tag",
          "operator": "!=",
          "value": "redwood_forest"
        },
        "add": {
          "component_groups": ["yourpack:ground_mode"]
        }
      }
    ]
  }
}

Interop with Difficulty Scaling

Biome variants and difficulty events stack cleanly as long as the component groups touch different components. If both the redwood_variant group and the difficulty_hard group set minecraft:health, the one applied last wins. BR's scaler runs after entity_spawned, so the difficulty group overrides the biome group. If you want a redwood × brutal tier, author that combination as its own component group and trigger it from the biome branch.

Biome tags available

BR's custom biomes add tags matching their identifier (e.g. the Redwood Forest biome carries the tag redwood_forest). For vanilla biome tags see Mojang's biome reference; common ones include desert, forest, mesa, jungle, ocean, overworld, nether.

Tree Capitator (block tags)

See the Tree Capitator section above for the full integration.

Vein Miner (block tag)

See the Vein Miner section above for the full integration.

Block-behavior tags

Item tags BR reads

Tier gates (which tier breaks which category)

Each row is a block category from limitEvents.js; a tool can break that category if its tier tag appears in the second column.mummifiedis BR's quest-line tool and isn't a step in the hierarchy.

Note: crystalline is intentionally excluded from nether, and obsidian from meteorite / advancedNether. These match the hand-tuned source-of-truth allowlists in limitEvents.js.

Tags BR sets but doesn't read (yet)

These tags appear on BR blocks for documentation / future-proofing, but no script consumes them today. Tagging your block won't affect anything until BR ships a reader.

• 5fs_br:stone_tier_destructible

Internal-only tags

BR also uses tags like 5fs_br:lit, 5fs_br:active, 5fs_br:bounced, 5fs_br:despawning, 5fs_br:body, 5fs_br:head, and assorted cardinal-direction / pipe / piping tags for runtime state on entities and connectable blocks. These are managed by BR scripts at runtime; setting them yourself in JSON has no defined effect and may break in future updates.

How to add a tag

Drop the tag into minecraft:tags on your item, or use the tag:<name> component on your block:

// item JSON
"components": {
  "minecraft:tags": {
    "tags": ["minecraft:is_pickaxe", "5fs_br:steel_tier"]
  }
}

// block JSON
"components": {
  "tag:5fs_br:vein_ore_cobalt": {},
  "tag:minecraft:is_pickaxe_item_destructible": {}
}