defineRegistry
Install a typed registry accessor for compatible provider reads and local writes.
Import
import { defineRegistry, registryReference } from '@bedrock-core/server-runtime/library';
import type { RegistryAccessor, RegistryDefinition, RegistryOptions } from '@bedrock-core/server-runtime/library';
Library code owns registry definitions and exposes domain accessors to addon code. core.registry describes addons and their published datasets.
Signature
defineRegistry<T>(definition: RegistryDefinition<T>, options?: RegistryOptions<NoInfer<T>>): Declaration<RegistryAccessor<T>>
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
definition | RegistryDefinition<T> | — | Registry identity, contract and record validator |
options | RegistryOptions<T> | {} | Local publication metadata and provider selection |
Definition
| Option | Type | Default | Description |
|---|---|---|---|
id | string | — | Namespaced registry identity such as studio:textures |
contract | number | — | Positive integer identifying the record contract |
accepts | (value: unknown) => value is T | — | Validates each copied record |
Options
| Option | Type | Default | Description |
|---|---|---|---|
entries | Readonly<Record<string, T>> | — | Initial local records; supplying this starts publication |
revision | number | 1 when publishing | Nonnegative dataset revision; supplying this starts publication |
coverage | RegistryMinecraftCoverage | — | Inclusive published coverage with min and optional max version tuples |
minecraft | readonly [number, number, number] | — | Reader target version used to check provider coverage |
contracts | readonly number[] | Definition's contract | Accepted contract versions, all using the definition's validator |
providers | readonly string[] | All compatible providers | Limits reads to named addons |
retainOnDeparture | boolean | false | Retains departed provider records as stale data |
select | (candidates: readonly RegistryEntry<T>[]) => RegistryEntry<T> | undefined | First ordered candidate | Chooses a record when providers publish the same entry identity |
Registry identity is namespaced. Entry identity belongs to the dataset: a Core addon can publish a record for minecraft:stone while retaining its own addon identity.
Returns
A Declaration<RegistryAccessor<T>>. Install it through core.register() or core.install() to receive the accessor:
| Member | Purpose |
|---|---|
get(id), has(id) | Read the selected compatible entry |
all() | Read every candidate entry with provider provenance |
of(provider) | Read one provider's complete dataset |
snapshot | Observe provider availability and selected entries |
whenReady(timeoutTicks = 100) | Wait for the current reader snapshot to be ready |
resolve(reference, from?) | Resolve a typed link with optional source provenance |
set(id, value), delete(id), replace(entries) | Write only this addon's local publication |
stop() | Release this accessor's reader and local publication |
Records use Sync's structured copy semantics. Each write validates the copied value and deeply freezes it without freezing the authored source. A failed write preserves the previous snapshot. replace publishes the complete replacement atomically.
Usage
interface Texture { readonly path: string }
const textures: RegistryDefinition<Texture> = {
id: 'studio:textures',
contract: 1,
accepts: (value): value is Texture => typeof value === 'object'
&& value !== null && 'path' in value && typeof value.path === 'string',
};
const { dataset } = core.register({
manifest,
dataset: defineRegistry(textures, {
revision: 2,
coverage: { min: [1, 26, 50] },
entries: { 'minecraft:stone': { path: 'textures/blocks/stone' } },
}),
});
dataset.get('minecraft:stone');
The accessor reads compatible local and remote records immediately after installation. Supplying entries or revision starts a local publication. With both omitted, publication begins on the first set or replace; delete returns false while no local publication exists.
Libraries can compose this declaration with their service installation through core.install(). The parent installation owns nested declarations. A Runtime permits one local publication for a registry identity; another Runtime owns its own instance.
Ownership
Local publication advertises its compact descriptor alongside addon metadata. Creating or replacing a publication broadcasts its complete snapshot. Installing a reader requests current snapshots from compatible providers; only installed readers retain foreign records. Reading the addon directory alone retains no registry datasets.
stop() withdraws this accessor's local publication, clears its retained view and rejects further writes. Repeated withdrawal is safe. Runtime shutdown, uninstall and failed declaration installation release their owned resources. A failed core.install() after registration preserves unrelated, earlier installations.
Reading providers
const { view } = core.register({
manifest,
view: defineRegistry(textures, {
minecraft: [1, 26, 60],
}),
});
await view.whenReady();
view.get('minecraft:stone');
view.of('studio_metadata');
This installs the same accessor without initial local records. It reads compatible datasets without publishing until a write occurs. Local publications are read directly; matching remote readers share retained snapshots within one Runtime. Snapshot arrival and broadcast updates are asynchronous, so an initial get can return undefined.
The default contract policy accepts the definition's exact version. contracts can explicitly list other supported versions, with every received record still validated. Pass minecraft to enforce inclusive provider coverage for the library's target version; omitting it leaves coverage unrestricted. providers limits reads to named addons. Publication coverage and reader minecraft serve separate purposes.
The default selection prefers live data, higher dataset revision and then provider namespace in lexical order. select lets a domain choose among the ordered candidates; all() retains their individual provenance for domain-specific interpretation or merging. of(provider) reads that provider's complete dataset. Invalid snapshots are excluded atomically.
Departure drops data by default. retainOnDeparture: true keeps an explicitly stale cache; resolution reports stale. A replacement running instance acquires a fresh snapshot. Registry contract, Minecraft coverage, dataset revision and addon version remain independent.
snapshot exposes status, providers and selected entries. Provider descriptors carry the dataset revision; each provider's version counts snapshot changes within its current publication. get() reads available values synchronously; whenReady(timeoutTicks = 100) waits for the current reader to become ready. Its wait rejects on timeout or cleanup.
Typed references
const stone = registryReference(textures, 'minecraft:stone');
const resolved = view.resolve(stone);
if (resolved.status === 'ready') {
resolved.entry.value.path;
resolved.entry.provider;
}
A reference contains registry and entry identity, with optional dataset revision and snapshot version pins. Creating one acquires no dataset. isRegistryReference(definition, value) validates transported links against the target registry.
Libraries resolve cross-registry links through the corresponding installed accessor. Pass the source RegistryEntry as the second argument to resolve to retain its provider, running instance and dataset revision. Optional version pins prevent reading a replacement snapshot through an older link. A missing or withdrawn target cannot silently redirect that related lookup to another provider.
Resolution distinguishes ready, stale, missing, loading, unavailable, incompatible, invalid and stopped. Libraries decide which links are required and how to present optional or pending data.
Transport and cleanup
Sync owns snapshot replication and tracks publisher instances, publication generations and update revisions. Targeted initial responses carry a reader token so released or replaced watches cannot accept an older response. Providers broadcast replacements independently of active readers.
Releasing the final reader clears its retained remote snapshot. Runtime shutdown releases remaining readers and publications through the same declaration lifecycle as local services and modules.