Skip to main content

Reference transport

References identify live objects. Runtime resolves native identities in the receiving addon and routes addon-owned object operations back to their owner through the existing RPC, State and Events services. Builder selects the reference contract from the declared public types.

Native references​

Public typeAddressResolution
EntityEntity IDCurrent valid native entity
PlayerEntity IDCurrent valid entity, checked as a player
DimensionDimension IDNative dimension
BlockDimension ID and integer coordinatesCurrent block at that location
Entity/block componentsOwner identity/location and component IDCurrent component, checked against the declared SDK class
ContainerCaptured owner and inventory lookupCurrent inventory on that native owner
ContainerSlotCaptured inventory lookup and slot indexCurrent native slot
export async function inspect(block: Block): Promise<{
block: Block;
dimension: Dimension;
typeId: string;
}> {
return { block, dimension: block.dimension, typeId: block.typeId };
}

Use type imports from @minecraft/server in public declarations. A block address follows the current contents of its location, including replacement. An unloaded block lookup resolves as unavailable. Unknown dimensions, malformed addresses and wrong native object types reject.

Required references reject when unavailable; nullable references use the declared missing value. A reference allowing both null and undefined uses undefined for absence. Arguments are resolved before invoking the provider. Native handles keep their normal engine lifetime and methods. Snapshot containers freeze while handles remain live.

Minecraft owns native handles independently of Core registration. Closing API transports and subscriptions does not itself remove Minecraft entities or blocks. A retained handle follows its SDK validity rules. A later decode resolves the address again, while an existing handle keeps its own lifetime.

State and event payloads resolve references when decoded. A cached state snapshot does not refresh merely because an entity is removed or a block changes. Read the handle's native validity where available, and obtain a fresh reference when needed. Use observable state for changes that subscribers must receive explicitly.

Inventory provenance​

Builder traces native acquisition only when a public API transfers components, containers or slots. It includes TypeScript and erased JavaScript dependencies, with one tracker shared by the addon's implementation and runtime. Native operations still execute normally; the tracker records how to find the result in the receiving addon.

import type { ContainerSlot, Entity } from '@minecraft/server';

export async function inventorySlot(entity: Entity, index: number): Promise<ContainerSlot> {
return entity.getComponent('minecraft:inventory')!.container!.getSlot(index);
}

A consumer receives a real ContainerSlot and calls native methods locally. It can forward a received container or slot through another API. A plain-bundler consumer cannot transfer an untracked locally acquired container or slot: expose an Entity or Block plus the slot index instead. Locally acquired entity/block components carry their own SDK owner fields and need no acquisition trace to encode.

A block-inventory lookup follows the current block at its location. Minecraft controls whether a retained native handle remains invalid or becomes valid after replacement; Core imposes no additional lifetime. Missing inventories resolve as unavailable, while malformed paths, invalid slot indexes and wrong component classes reject.

Native value snapshots​

Public BlockPermutation and supported ItemStack values use built-in codecs. Each decode creates an independent native value; nullable values preserve their declared absence. SDK snapshots stay usable as native objects inside read-only state containers.

BlockPermutation copies its block type and every state returned by getAllStates(). Decode requires the same complete state set and rejects unknown types, invalid states or a reconstruction that changes them.

ItemStack copies the amount, name tag, death/lock settings, raw lore and adventure-mode placement/destruction lists. Encoding reconstructs a candidate and requires native stacking compatibility, which compares item type and custom data independently of amount. Non-stackable items, dynamic properties and hidden data that cannot pass this fidelity check reject. Use a ContainerSlot to access arbitrary item data locally. See Microsoft's ItemStack API.

For explicit synchronous conversion, import itemStackCodec or blockPermutationCodec from @bedrock-core/server-runtime/api/native-values. These imports require the Minecraft runtime. Generated API bindings select the codecs from the public SDK types automatically.

Class-backed addon APIs​

Declare a finite public object interface using Promise-returning methods, ReadonlyObservable state and Signal events:

Public declarations
import type { ReadonlyObservable, Signal } from '@bedrock-core/observable';
import type { Money } from './values';

export interface Account {
readonly balance: ReadonlyObservable<Money | undefined>;
readonly changed: Signal<Money>;
deposit(
amount: Money,
confirm: (current: Money, amount: Money) => Promise<boolean>,
): Promise<Money>;
close(): Promise<void>;
}

export declare const accounts: {
open(key: string): Promise<Account>;
identity(account: Account, key: string): Promise<boolean>;
};

The provider can implement Account as a class with private fields. Annotate its factory result as the public interface. Builder emits the checked contract and keeps implementation code in its owner. Async method declarations or observable/signal members identify an API object contract. Function-valued callback fields in ordinary input data remain call-scoped callbacks.

Consumer
import { accounts, Money } from '@studio/economy';

const account = await accounts.open(player.id);
const stop = account.balance.subscribe(value => updateBalance(value));

await account.deposit(new Money(10), async (current, amount) => {
return current.gold + amount.gold <= 100;
});

await accounts.identity(account, player.id);
stop();
await account.close();

An address contains owner namespace, running instance, object ID and checked contract ID. Other addons receive a typed proxy. Repeated results for the same live instance preserve proxy identity. Passing a reference back to its owner resolves the original object; forwarding it through another addon preserves its owner.

Methods execute in the owner and keep their receiver, including private class state. Callbacks execute in the caller and expire with their containing call. State and signals use their existing local handles. Providers validate their own business inputs and permissions.

Ownership and disposal​

Runtime retains an exported instance until its owner releases it or stops. Release it when its business lifetime ends, for example from the implementation's async close() method:

Owner implementation: close method
async close(): Promise<void> {
accountsByKey.delete(this.key);
core.api.release(this);
}

core.api.release(instance) returns true on release and false for an instance not currently exported. Repeating it is safe. Another addon cannot release the owner's object; it invokes a public owner operation such as close().

Release removes RPC handlers, state publications and signal subscriptions. Consumers receive unavailable state and their object listeners detach. New operations reject; admitted operations may finish. Released instances cannot be exported again in the same Runtime. Create a new instance when reopening. Dropping a client variable or unsubscribing a listener does not release the owner object.

Withdrawing a factory's public module leaves previously returned objects owned by the Runtime. Runtime.stop() releases them all. Provider replacement invalidates old addresses, even when the new addon uses the same namespace. Released IDs are not reused within a running instance; a compact synchronized lifecycle marker keeps delayed references invalid.

Each instance has one checked public contract. API object contracts have required, named members and a finite, non-recursive shape. Synchronous remote methods and mutable computed metadata are unsupported; use async methods and observable state. Immutable literal metadata can be included. A class declaring a value codec retains value-copy semantics.

Minecraft coverage matrix​

Type or familyCurrent supportRemaining work
Entity, PlayerNative ID referencesAdditional native lifecycle scenarios
Dimension, BlockNative identity/location referencesAdditional world-boundary scenarios
Entity/block componentsNative owner/component referencesAdditional component-specific engine scenarios
Container, ContainerSlotCaptured native inventory referencesUntracked plain-bundler inputs reject
BlockPermutationComplete type/state snapshotsRequires matching native block definitions
ItemStackNative stacking-equivalent snapshotsNon-stackable and unverifiable data reject
Registry and scoreboard classesUnsupported as direct referencesVerify stable lookup and lifetime per type
Other native classesUnsupportedExplicit adapter or value contract
Addon-owned API objectsInstance-bound owner referencesRecursive contracts remain unsupported
Plain data and enumsChecked JSON signaturesUnsupported fields must be projected into a supported contract

An unsupported native handle can remain private in an addon-owned API implementation. Expose async operations around it and return supported values or references.

From the server repository, print the installed SDK's complete class inventory:

node scripts/reference-coverage.mjs

The report records the SDK package/version, every exported class, support status and any missing rule. It distinguishes native references, complete value codecs, conditional value codecs and unsupported classes. Other Minecraft packages have no built-in native adapters. Native GameTests and focused tests cover reference resolution, value fidelity, missing locators, forwarding, release, setup rollback and provider replacement.

Next steps​