External packs (scripts)

Your add-on has scripts? Register your advancements from them, report your own events, and listen for completions. No dependency on BedrockAdvancements.

#Setup

Copy scripts/baClient.js from the example plugin pack into your scripts. Your pack needs @minecraft/server 2.0.0 or later. It doesn't need a dependency on BedrockAdvancements, and does nothing when it isn't installed.

import { BAClient } from "./baClient.js";

const ba = new BAClient("fishing_plus", { pack: "Fishing+" });
ba.register({
  tabs: [
    { id: "main", title: "Fishing+", icon: "textures/items/fishing_rod_uncast", background: "textures/blocks/prismarine_bricks" },
  ],
  advancements: [
    {
      id: "root", tab: "main", title: "Gone Fishing", description: "Craft a fishing rod",
      icon: "textures/items/fishing_rod_uncast",
      criteria: { rod: { trigger: "inventory_changed", item: "fishing_rod" } },
    },
    {
      id: "dawn", tab: "main", parent: "root", title: "Early Bird", description: "Cast at dawn",
      icon: "textures/items/clock_item", frame: "goal",
      criteria: { cast: { trigger: "event", event: "fishing_plus:dawn_cast" } },
    },
  ],
});

register() sends your definitions once the world is running, and again whenever BedrockAdvancements reloads (it announces itself with the ba:ready script event). Big payloads are split to fit the 2048-character script event limit automatically.

#Reporting progress

ba.emit(player, "fishing_plus:dawn_cast");     // progresses { trigger: "event", event: "fishing_plus:dawn_cast" }
ba.award(player, "fishing_plus:root", "rod");  // completes one goal
ba.grant(player, "fishing_plus:root");         // completes the whole advancement
ba.revoke(player, "fishing_plus:root");
ba.open(player, "fishing_plus:main");          // opens the screen on your tab

Pass a value with the event and a goal can require it: { trigger: "event", event: "fishing_plus:catch", data: "salmon" } only counts ba.emit(player, "fishing_plus:catch", "salmon"). Add count to need it several times.

#Listening for completions

ba.onCompleted((e) => {
  // e.player, e.playerId, e.id, e.tab, e.frame
  if (e.id === "fishing_plus:dawn") e.player.sendMessage("The fish are biting!");
});

#Definitions

Definitions are JSON: the tab, advancement and criteria fields, with any built-in trigger plus event. Functions (test, custom triggers) aren't available here; use a script plugin for those.

#The raw script events

If you'd rather not use the helper, send these with system.sendScriptEvent:

BedrockAdvancements sends ba:ready once the world has loaded (re-send your ba:register on it) and ba:completed with {"player", "playerId", "id", "tab", "frame"} on every completion.