Using datapack libraries

StewBeet's dependency system has two layers: official libraries auto-detected from function usage (no config), and custom load_dependencies declared in beet.yml. Both are auto-downloaded at build time and get runtime scoreboard version checks with clickable in-game error messages.

Config Reference: extensive/beet.yml

Real-world Example: SimplEnergy/beet.yml

Source Code: stewbeet/plugins/finalyze/dependencies/init.py

  • Auto-detect and download official libraries: no configuration needed
  • Declare custom dependencies in beet.yml with load_dependencies
  • Generate runtime version checks and Minecraft version compatibility checks
  • Provide clickable in-game error messages when dependencies are missing

Required: stewbeet.plugins.finalyze.dependencies in pipeline
Required: stewbeet.plugins.datapack.loading must run before
Position: Must be placed after all user functions have been written (scans them to auto-detect libraries)

Official Libraries (Auto-detected)

The plugin automatically scans all datapack functions during build and marks a library as used when its namespace appears. No configuration required: just use the library in your functions.

Detection Logic

  • Modrinth / static libs (furnace_nbt_recipes, common_signals, realistic_explosion, itemio, smithed.actionbar): detected when their namespace string appears in any function.
  • Bookshelf modules (bs.*): detected when a tag call #bs.X:... appears in any function.

Supported Official Libraries

Smithed

KeyNameURL
smithed.custom_blockSmithed Custom Blockwiki.smithed.dev
smithed.crafterSmithed Crafterwiki.smithed.dev
smithed.actionbarSmithed Actionbarwiki.smithed.dev
realistic_explosionRealisticExplosiongithub.com/Stoupy51/RealisticExplosion

Modrinth

KeyNameURL
itemioItemIOgithub.com/edayot/ItemIO
common_signalsCommon Signalsgithub.com/Stoupy51/CommonSignals
furnace_nbt_recipesFurnace NBT Recipesgithub.com/Stoupy51/FurnaceNbtRecipes
smart_ore_generationSmart Ore Generationgithub.com/Stoupy51/SmartOreGeneration

Bookshelf modules: all bs.* modules are supported (e.g. bs.math, bs.block, bs.raycast, ...). See the official Bookshelf releases for the full list.

Gamemode 4 libraries: detected from their namespace (gm4_forceload:, gm4_lore:, ...), downloaded from Smithed. Their version check reads the GM4 scores (gm4_forceload and gm4_forceload_minor in load.status).

KeyLibrary
gm4_forceloadlib_forceload
gm4_hooked_entitylib_hooked_entity
gm4_lorelib_lore
gm4_machineslib_machines
gm4_potion_trackinglib_potion_tracking
gm4_treeslib_trees

GM4's lib_player_motion is not present: use player_motion instead, which is original.

Note: smart_ore_generation also receives automatic function tag wiring: if your datapack contains calls/smart_ore_generation/generate_ores, denied_dimensions, or post_generation functions, they are wired into the corresponding smart_ore_generation:v1/signals/ tags automatically.

Generating custom ores with CustomOreGeneration

CustomOreGeneration writes those generate_ores functions for you, and using it pulls in smart_ore_generation. The library scans 96x96 regions around players and starts each vein at a random position next to air, so ores end up where players can find them.

python
from stewbeet import CustomOreGeneration

CustomOreGeneration.all_with_config({
    "steel_ore": [
        # Common veins, from y=0 to y=50
        CustomOreGeneration(dimensions=["minecraft:overworld"], minimum_height=0, maximum_height=50, veins_per_region=1.2),
        # Extra veins in badlands only, replacing terracotta that has terracotta above it
        CustomOreGeneration(
            dimensions=["minecraft:overworld"],
            minimum_height=60,
            maximum_height=120,
            veins_per_region=2,
            provider=["#minecraft:terracotta"],
            vein_conditions=["if biome ~ ~ ~ #minecraft:is_badlands"],
            block_conditions=["if block ~ ~1 ~ #minecraft:terracotta"],
        ),
    ],
    "deepslate_steel_ore": [
        CustomOreGeneration(dimensions=["minecraft:overworld"], maximum_height=0, veins_per_region=1.2),
    ],
})

Call it from a plugin that runs after the custom blocks exist, like src/link.py in the extensive template. Keys are custom block ids (or Block objects), and an ore with several configurations gets one vein function per configuration.

FieldDefaultMeaning
dimensionsrequiredDimensions to generate in, ex: ["minecraft:overworld", "stardust:cavern"]
minimum_heightNoneLowest y of a vein, None for the bottom of the overworld
maximum_height70Highest y of a vein
veins_per_region4Veins per region, the decimal part being a chance: 1.2 is one vein plus a 20% chance of a second
vein_size_logic0.4Vein size: 0.0 is a single block, 0.4 a small vein, 1.0 a large one
provideroverworld carver replaceablesBlock, block tag, or list of them, that the ore replaces
vein_conditions[]Conditions checked once at the start of the vein, cancelling all of it
block_conditions[]Conditions checked at every block of the vein
placer_commandplace the custom blockExecute subcommands ending with run ..., placing one ore at ~ ~ ~

Conditions are execute subcommands starting with if or unless , and all of them must hold. Use vein_conditions for what is the same across a vein, like a biome (if biome ~ ~ ~ #minecraft:is_badlands), and block_conditions for what depends on each block, like its neighbours (if block ~ ~-1 ~ minecraft:deepslate). To only replace some blocks, set provider instead of adding a block condition.

When both x_ore and deepslate_x_ore are defined, the default placer keeps x_ore off deepslate and deepslate_x_ore off stone.


Custom load_dependencies

Use load_dependencies in beet.yml to declare libraries that should be downloaded and version-checked at runtime. Three source types are supported.

Configuration Structure

yaml
meta:
  stewbeet:
    load_dependencies:
      # --- Smithed API (latest MC-compatible version auto-fetched) ---
      "smithed.crafter":
        name: "Smithed Crafter"
        url: "https://wiki.smithed.dev/libraries/crafter/"
        source: "smithed"
        smithed_id: "crafter"
        has_resource_pack: true   # optional, default false

      # --- Modrinth API (latest release for the current MC version auto-fetched) ---
      "itemio":
        name: "ItemIO"
        url: "https://github.com/edayot/ItemIO"
        source: "modrinth"
        modrinth_slug: "itemio"

      # --- Static URL (version pinned, zip downloaded from given URL per MC version) ---
      "common_signals":
        version: [0, 2, 0]
        name: "Common Signals"
        url: "https://github.com/Stoupy51/CommonSignals"
        source: "static"
        static_urls:
          "((1, 21, 7), (0, 2, 0))": "https://github.com/Stoupy51/CommonSignals/releases/download/v0.2.0/CommonSignals_datapack.zip"

Tip: The key (e.g. "smithed.crafter") becomes the dependency namespace used in the runtime scoreboard version check (score #smithed.crafter.major load.status).

Source Types

sourceExtra required fieldsBehavior
"smithed"smithed_idFetches the latest MC-compatible version from the Smithed API
"modrinth"modrinth_slugFetches the latest release for the current MC version from Modrinth
"static"static_urlsDownloads the pinned zip URL for the best matching ((mc_ver), (dep_ver)) key

Configuration Field Reference

FieldRequiredTypeDescription
name✅strDisplay name shown in runtime error messages
url✅strClickable link shown when the dependency is missing
source✅strDownload method: "smithed", "modrinth", or "static"
smithed_idSmithed onlystrSmithed pack ID used to query the API
has_resource_packSmithed onlyboolWhether to also download the resource pack (default: false)
modrinth_slugModrinth onlystrModrinth project slug used to query the API
static_urlsStatic onlydictMaps "((mc_ver), (dep_ver))" string keys to download URLs
versionStatic onlylist[int]Resolved automatically from static_urls at build time

Real-world Example: SimplEnergy

SimplEnergy uses a single Smithed dependency:

yaml
# Excerpt from SimplEnergy/beet.yml
meta:
  stewbeet:
    load_dependencies:
      energy:
        name: "DatapackEnergy"
        url: "https://github.com/ICY105/DatapackEnergy"
        source: "smithed"
        smithed_id: "energy"

At build time, StewBeet fetches the latest DatapackEnergy version compatible with the configured Minecraft version and merges it into the output automatically.


Runtime Behaviour

When the world loads, the generated functions run in this sequence:

  1. Lantern Load triggers each dependency's #dep:load tag so libraries publish their version scores to load.status.
  2. check_dependencies: sets #dependency_error ns.data flag if any version score is too old.
  3. valid_dependencies: waits for a player entity, reads DataVersion to verify the Minecraft version (against the minimum from mc_supports), then sends tellraw @a with clickable error links if anything fails. Calls confirm_load only when all checks pass.

In-game error messages when dependencies are missing:

Generated check_dependencies function:


Generated Files

FileTypeDescription
minecraft:load tagTagEntry point: triggers #load:_private/load
load:load tagTagPoints to #ns:load
ns:load tagTagCalls [#ns:enumerate, #ns:resolve]
ns:enumerate tagTagPrepended with #ns:dependencies
ns:dependencies tagTagLists #dep:load for every dependency
load:_private/initFunctionResets the load.status scoreboard
ns:vX.Y.Z/load/secondaryFunctionRegisters ns.data scoreboard, calls check/valid
ns:vX.Y.Z/load/check_dependenciesFunctionSets #dependency_error via scoreboard version checks
ns:vX.Y.Z/load/valid_dependenciesFunctionWaits for player, checks DataVersion, shows errors
ns:vX.Y.Z/load/confirm_loadFunctionCalled only when all checks pass
ns:vX.Y.Z/load/tick_verificationFunctionRoutes tick function only when the correct version is loaded

Glossary

TermMeaning
load_dependenciesA beet.yml metadata dict where you declare external libraries to auto-download and version-check at runtime.
Source typeHow to resolve and download a library: "smithed" (Smithed API), "modrinth" (Modrinth API), or "static" (pinned zip URL per MC version).
Official libraryA pre-registered library in StewBeet's OFFICIAL_LIBS registry, detected automatically from function usage: no configuration needed.
Lantern LoadA community standard for datapack loading order; StewBeet sets it up automatically.
DataVersionAn entity NBT field used to detect the current Minecraft version at runtime; compared against the minimum from mc_supports.

Next steps