Skip to main content

core.registry

core.registry is an AddonRegistry: a live directory of registered Core addons: the local addon plus compatible peers that advertise Core runtime metadata through discovery. Each entry retains the addon's complete AddonManifest, keyed by its namespace.

The directory itself is addons, a ReadonlyObservable list derived from discovery. all(), get() and has() all read that one list, so there is never a cached answer to "who is here" that can disagree with the live one.

Listener failures are isolated and reported without preventing other listeners from receiving the change. Subscriptions return idempotent unsubscribe functions. Dependency-availability subscriptions also belong to the registry lifetime.

Import​

import { core } from '@bedrock-core/server';
import type { AddonRegistry, RegisteredAddon, AddonListener, CollisionListener } from '@bedrock-core/server';

Only Core runtime advertisements appear in this directory. Raw Sync peers are transport participants and do not satisfy Core dependencies or emit Core registration callbacks. An incompatible Core peer is reported through the incompatibility API.

Usage​

core.registry.addons.subscribe(addons => redraw(addons)); // who is here, as a value

core.registry.all(); // readonly RegisteredAddon[] — self + all live peers
core.registry.get('drav0011_economy'); // by namespace, or undefined
core.registry.has('drav0011_economy'); // boolean

core.registry.onRegister(addon => console.warn('joined:', addon.id));
core.registry.onUnregister(addon => console.warn('left:', addon.id));
core.registry.onNamespaceCollision(info => console.error('collision on', info.id));

self​

core.registry.self returns the local RegisteredAddon entry. core.manifest reads that entry's manifest. API-only consumer endpoints have no local registration.

RegisteredAddon​

interface RegisteredAddon {
readonly manifest: AddonManifest;
readonly id: string;
readonly self: boolean;
readonly runtimeVersion: string;
readonly instanceId: string;
readonly apis: readonly string[];
readonly registries: readonly RegistryDescriptor[];
}

Every entry keeps native fields under manifest, including header.name, header.version, metadata.authors, module definitions and dependency objects. These runtime fields accompany it:

FieldMeaning
idThe explicit addon namespace. The key everything else uses.
manifestThe complete validated manifest, with native structure and values preserved.
selftrue for the local addon, false for a peer.
instanceIdThe current running instance; changes when the addon restarts.
apisReady public API entry names, installed by generated exports or framework libraries.
registriesCompact library registry descriptors: identity, record contract, dataset revision and optional Minecraft coverage.
runtimeVersionThe @bedrock-core/server-runtime version that addon was built against. the addon's version is manifest.header.version.

The registry preserves pack.name and pack.description in the manifest. Cross-addon displays qualify those keys with manifest.namespace when rendering them. For example, studio_shop.pack.name identifies Shop in a UI that lists several addons. Builder emits both the pack-local alias and the shared display lookup.

Peer validation

Discovery carries the manifest under meta.manifest, alongside runtimeVersion, ready apis and registry descriptors. A compatible peer appears only when its manifest is valid and its namespace and header version match the transport advertisement. A peer without a nonempty runtimeVersion is excluded from the Core directory. Invalid manifests are excluded rather than rewritten. Invalid or duplicate registry descriptors are ignored separately; an addon without descriptors remains a valid directory entry.

Ready API entries share this addon directory. Their setup is owned by Runtime registration; addon authors use normal package imports. An addon can register before all of its script entry has finished, so presence and the availability of a particular API entry can occur at different times.

Library registry descriptors share the same directory and stay outside the native manifest. They advertise available datasets without including records. Their revision describes the publisher's dataset independently of addon and Runtime versions. See library registry declarations.

API​

whenApi​

core.registry.whenApi(id: string, module: string, timeoutTicks = 100): Promise<RegisteredAddon>

Framework bindings wait for a public export using the existing registry. Resolves immediately when ready, otherwise follows registration metadata until the export is available or the timeout expires. Stopping the registry rejects outstanding waits.

addons​

core.registry.addons: ReadonlyObservable<readonly RegisteredAddon[]>

Every registered addon as an observable list, the local one first. Subscribe to it to track who is present; computed() over it to derive something from the set.

const addonCount = computed(() => core.registry.addons.get().length, [core.registry.addons]);

It republishes when an addon appears or disappears, and when a peer re-announces something new — never on the heartbeats that repeat what a peer already said.

all​

core.registry.all(): readonly RegisteredAddon[]

A snapshot of addons: the local addon first, then every live peer.

for (const addon of core.registry.all()) {
console.warn(`${addon.id} v${addon.manifest.header.version}${addon.self ? ' (me)' : ''}`);
}

get​

core.registry.get(id: string): RegisteredAddon | undefined

Look up an addon by its namespace. Returns the local addon when id === core.id.

has​

core.registry.has(id: string): boolean

Whether an addon with that namespace is present. Subscribe to registry.addons when behavior depends on presence. For API readiness, observe the imported API's state; see optional integrations.

onRegister​

core.registry.onRegister(listener: AddonListener): Unsubscribe

Fires when a peer becomes visible. Returns an unsubscribe function. This is a delta: to react to who is present rather than to each arrival, subscribe to addons.

const off = core.registry.onRegister((addon) => {
if (addon.id === 'drav0011_economy') { startTrading(); }
});

// later
off();
Not a replay

onRegister only fires for peers that appear after you subscribe. Peers already present are in all(). Since addons load in undefined order, combine an initial read with a subscription, or derive an optional integration from the addons observable.

onUnregister​

core.registry.onUnregister(listener: AddonListener): Unsubscribe

Fires when a Core peer disappears or stops advertising Core registration metadata. Discovery evicts disconnected peers after their TTL elapses without a heartbeat.

onNamespaceCollision​

core.registry.onNamespaceCollision(listener: CollisionListener): Unsubscribe

interface CollisionInfo {
id: string;
instanceId: string;
}

Fires when another instance is announcing this addon's namespace. The runtime also logs:

[bedrock-core] collision: another instance shares identity '<id>'

A collision is not recoverable at runtime; both addons share a transport address, a state namespace and a command namespace. Give each scripted addon its own manifest namespace. A behavior/resource pair can share that namespace because the resource pack does not register a runtime.

core.registry.onNamespaceCollision((info) => {
console.error(`[economy] another pack is using '${info.id}' (instance ${info.instanceId})`);
});

incompatible​

core.registry.incompatible(): readonly IncompatiblePeer[]

interface IncompatiblePeer {
id: string;
meta?: Record<string, unknown>;
pmin: number;
pmax: number;
}

Core addons heard on the bus whose protocol ranges do not overlap this build's range. Their announce metadata identifies them as Core participants, but they cannot exchange negotiated messages and remain absent from all().

They are listed rather than ignored because the alternative is worse than an error. An addon that cannot be reached, silently left out, looks exactly like an addon that was never installed — the catalog is confidently wrong instead of visibly incomplete.

onIncompatible​

core.registry.onIncompatible(listener: IncompatibleListener): Unsubscribe

Fires the first time such an addon is heard. The runtime also logs:

[bedrock-core] '<id>' speaks sync protocol <pmin>-<pmax>, this addon speaks <min>-<max>; the two cannot talk. Update whichever is older.

The fix is always to update one of the two packs; there is no runtime setting that bridges the gap.

Dependencies​

Declare required addon dependencies in the authored manifest with a native pack UUID/version and runtime namespace. Minecraft enforces native pack requirements. The registry observes addon registrations by namespace and reports missing registrations without blocking script execution. Optional dependencies add no native pack requirement.

import manifest from '../manifest.json';

core.register({ manifest });

missing​

core.registry.missing: ReadonlyObservable<readonly string[]>

The declared dependencies that are not currently present, as an observable list. Empty means satisfied.

missingDependencies​

core.registry.missingDependencies(): readonly string[]

A snapshot of missing.

core.registry.missingDependencies(); // ['drav0011_economy'] until it registers

onDependenciesSatisfied​

core.registry.onDependenciesSatisfied(listener: () => void): Unsubscribe

Fires when every declared dependency is present.

  • If they are already satisfied when you subscribe — including the common case of no dependencies declared at all — the listener fires immediately, synchronously, inside the onDependenciesSatisfied call.
  • After that it is edge-triggered: it fires once on each unsatisfied → satisfied transition, not on every peer that joins.
import { getBalance } from '@studio/economy';

core.registry.onDependenciesSatisfied(() => {
getBalance(player.id)
.catch((error: unknown) => console.warn(`[shop] ${String(error)}`));
});
Satisfied is not permanent

If a dependency later disappears the transition flips back, and a subsequent recovery fires your listener again. Write the callback so it is safe to run more than once.

Logging​

The registry writes to console.info when the dependency picture changes:

[bedrock-core] 'drav0011_shop' missing dependencies: drav0011_economy
[bedrock-core] 'drav0011_shop' dependencies resolved: drav0011_economy

The first is also emitted once at startup if anything is missing then. Collisions use console.error; nothing here throws.