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:
| Field | Meaning |
|---|---|
id | The explicit addon namespace. The key everything else uses. |
manifest | The complete validated manifest, with native structure and values preserved. |
self | true for the local addon, false for a peer. |
instanceId | The current running instance; changes when the addon restarts. |
apis | Ready public API entry names, installed by generated exports or framework libraries. |
registries | Compact library registry descriptors: identity, record contract, dataset revision and optional Minecraft coverage. |
runtimeVersion | The @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.
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();
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
onDependenciesSatisfiedcall. - 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)}`));
});
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.