Tracking

Tracking a local catalog

Each get / list / match round-trips to the host. track keeps a copy in RAM: it subscribes, pulls overlay list, and applies later notifications. catalog() is undefined until track succeeds.

Vanilla content is already on the host. track defaults to overlay-only (vanilla: false): other packs’ documents, not the vanilla snapshot. Use list / get on registry when you need vanilla without seeding.

const ok = await registry.waitReady();
if (ok) {
  await registry.track({
    kinds: ["fluid", "item", "loot"],
    source: "mymod",
    filters: {
      fluid: { vanilla: false },
      item: { vanilla: false },
      loot: { vanilla: false },
    },
  });

  const replica = registry.catalog();
  if (replica) {
    replica.listDocuments("fluid");
    replica.listDocuments("item");
  }
}

replica is the in-memory catalog. listDocuments uses the same kind of filter as registry.list, without another round trip to the host.

To answer vanilla from catalog() without asking the host again, seed documents from @mcbe-registry/host. That package is the host catalog on npm; /vanilla is the snapshot the behavior pack also loads:

import { VANILLA_FLUIDS, VANILLA_LOOT, VANILLA_RECIPES } from "@mcbe-registry/host/vanilla";

await registry.track({
  kinds: ["fluid", "loot", "recipe"],
  source: "mymod",
  seed: [
    { kind: "fluid", documents: VANILLA_FLUIDS },
    { kind: "loot", documents: VANILLA_LOOT },
    { kind: "recipe", documents: VANILLA_RECIPES },
  ],
});

You only need that dependency if you seed. Most addons can skip it.

Field	Meaning
kinds	Tables to subscribe and overlay-list
source	Ignore notifications from that pack; add writes the replica as that owner
filter / filters	Overlay list options (vanilla defaults to false)
seed	Documents inserted locally (not listed from the host)

add / register still go to the host. Tracked kinds also land on the replica immediately.