core
core is the registered addon runtime: identity, API bindings, discovery and owned library services.
Import
import { core, Runtime } from '@bedrock-core/server';
import type { AddonManifest, Declaration } from '@bedrock-core/server';
@bedrock-core/server-runtime exposes the same runtime independently of the umbrella package.
Registration
import manifest from '../manifest.json';
core.register({ manifest });
Register once per behavior pack. registered and inert API bindings are available before registration; the other services require a live runtime.
| Member | Purpose |
|---|---|
registered | Whether registration completed |
id, namespace | Authored manifest namespace |
manifest | Validated AddonManifest |
api | Imported API modules and provider bindings |
registry | Addon presence, display metadata and dependency availability |
provideService, service | Typed local library service installation and lookup |
Normal addon integrations use public package imports. Framework libraries use api for callable behavior when the owner is selected dynamically. The API subsystem owns provider bindings, reference lifetimes and consumer subscriptions over RPC, State and Events. Ready export names are advertised through the manifest-backed addon registry. Dataset publications and interests use the registry layer; translations are accessed through the i18n integration.
Providers of class-backed API objects call core.api.release(instance) when an object's lifetime ends. It returns true for a released instance and false when it is not currently exported. Only the owner can release it. See reference transport for identity, forwarding and disposal rules.
Library services use core.api.createModule(ownerNamespace, localApiObject) to read the same checked API contract from another owner. The object must carry generated metadata from a public API entry or a library module factory. The returned view has async methods and read-only state and event handles.
api.createModule()
core.api.createModule<T extends object>(namespace: string, implementation: T): ApiModule<T>
Pass the owning addon's namespace and an implementation object with a generated contract. The result projects that contract onto the selected owner: functions return promises, state reads can be undefined, and event handles expose subscription without emission. Constants remain immutable client metadata.
const remote = core.api.createModule('studio_shop', declaration.api);
Creating this view does not install or publish the local declaration. Missing generated metadata throws immediately; provider availability is checked when the view is used. Addons with a fixed provider normally use public package imports.
register()
register<O extends RegisterOptions>(options: O): this & Omit<Declared<O>, keyof this>
The options contain a manifest and any number of declarations. A declaration installs a service and exposes its accessor on Core under the same key. Public API objects use a declaration such as shop: registerModule(API); see public addon APIs.
const registered = core.register({
manifest,
config: registerConfig(configDefinition),
catalog: registerCatalog(),
guides: registerGuides(),
});
registered.config.server.get();
Registration returns the same Core object, with inferred read-only properties for the declared accessors. Capturing that result gives typed access such as registered.textureRegistry. Existing imports of the singleton see the same installed properties at runtime; their static type stays the base Runtime. Re-exporting the typed result is optional.
Declaration keys cannot replace Runtime members, including api, registry and stop. Choose a domain name for each accessor. Stopping or rolling back registration removes the installed property aliases.
Declarations install synchronously in key order on the live runtime. Failed registration rolls back installed declarations and services, leaving the runtime unregistered. Read other services through their library accessors at use time, so installation order does not require a second pass. Minecraft APIs that need a later lifecycle phase must be deferred by the owning library.
install()
install<T>(declaration: Declaration<T>): T
Install a declaration after registration and receive its accessor directly. If installation fails, its partial resources and nested declarations are stopped and its new services are removed. Modules, services and registries all use this same installation contract:
interface Declaration<T> {
install(core: Runtime, lifetime: InstallationLifetime): Installation<T>;
}
interface Installation<T> {
readonly value: T;
readonly stop?: () => void;
}
interface InstallationLifetime {
defer(stop: () => void): void;
}
Writing one
export function registerWidgets(definition: WidgetDefinition): Declaration<Widgets> {
return {
install(core, lifetime) {
const service = new WidgetService(core.api, core.namespace);
lifetime.defer(() => service.stop());
core.provideService('acme:widgets', service);
return { value: service.define(definition) };
},
};
}
Register cleanup with lifetime.defer() as each resource is acquired, so it also runs if later setup throws. The returned installation can include a stop hook for a completed instance. Keep instance state inside install so one declaration can create independent instances for different runtimes.
Cleanup stops nested installations in reverse order, invokes the returned stop, then runs deferred callbacks in reverse order. Every cleanup is attempted. A Runtime rejects installing the same declaration object twice while it remains installed.
uninstall()
core.uninstall(declaration): boolean
Withdraw one installed declaration and its nested installations. It releases owned services, subscriptions and registration aliases. Repeating withdrawal returns false; stopping Core withdraws all remaining installations.
Services
The library that owns a service adds its key and instance type to RuntimeServices:
declare module '@bedrock-core/server-runtime' {
interface RuntimeServices { 'acme:widgets': WidgetService }
}
This type declaration creates no runtime objects. Addon authors receive declaration accessor types from core.register(); they do not need to repeat the library's service-key declarations.
core.provideService(key, value) installs a local service on a registered Runtime; duplicate registration throws. During declaration installation, the service key belongs to that installation and is removed during its cleanup. Register the instance's resource cleanup with its lifetime. core.service(key) returns that instance or undefined. The owning library decides how to handle absence. Service instances remain local; libraries publish cross-addon operations through module declarations.
Libraries use defineRegistry from @bedrock-core/server-runtime/library to install one accessor for reads and local writes. Installing opens compatible provider snapshots; initial entries or a write start the local publication. Addon discovery exposes published descriptors through RegisteredAddon.registries. core.registry remains the public addon directory.
Manifest fields
AddonManifest describes authored native v3 fields and Core identity/dependencies. Import the JSON file directly. Builder resolves defaults, inheritance and dependency metadata before compiling it.
| Access | Meaning |
|---|---|
manifest.namespace | Addon address |
manifest.header.name, .description | Display text or translation keys |
manifest.header.version | Pack version |
manifest.metadata?.authors | Authors |
manifest.dependencies | Required native and Core dependencies |
manifest.optionalDependencies | Optional integrations |
manifest.thumbnail | Catalog artwork |
Use pack.name and pack.description in the header and define their strings in i18n. Icons come from pack_icon.png. See addon manifests.
stop()
core.stop();
Reject pending API calls, release subscriptions and provider bindings, stop declarations in reverse install order, release registry publications and retained reader snapshots, and take the addon offline. Every cleanup is attempted; failures are reported together in an AggregateError after identity and service state have been cleared. Repeated calls are safe. Calling it before registration also clears queued API subscriptions. Remote disappearance follows discovery visibility.
Several runtimes in one realm
new Runtime() creates an independent identity for integration tests. Each instance registers its own manifest, installs its own services, and owns its API bindings and teardown. Shipped behavior packs normally use the core singleton.
RUNTIME_VERSION
import { RUNTIME_VERSION } from '@bedrock-core/server';
The runtime version announced automatically during discovery. Registry entries expose it as runtimeVersion; addons do not author this value in their manifests.
isUsable
import { isUsable } from '@bedrock-core/server';
if (isUsable(player)) { player.sendMessage('Ready'); }
Checks whether an engine handle remains valid before accessing its other properties.