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 type | Address | Resolution |
|---|---|---|
Entity | Entity ID | Current valid native entity |
Player | Entity ID | Current valid entity, checked as a player |
Dimension | Dimension ID | Native dimension |
Block | Dimension ID and integer coordinates | Current block at that location |
| Entity/block components | Owner identity/location and component ID | Current component, checked against the declared SDK class |
Container | Captured owner and inventory lookup | Current inventory on that native owner |
ContainerSlot | Captured inventory lookup and slot index | Current 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:
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.
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:
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 family | Current support | Remaining work |
|---|---|---|
Entity, Player | Native ID references | Additional native lifecycle scenarios |
Dimension, Block | Native identity/location references | Additional world-boundary scenarios |
| Entity/block components | Native owner/component references | Additional component-specific engine scenarios |
Container, ContainerSlot | Captured native inventory references | Untracked plain-bundler inputs reject |
BlockPermutation | Complete type/state snapshots | Requires matching native block definitions |
ItemStack | Native stacking-equivalent snapshots | Non-stackable and unverifiable data reject |
| Registry and scoreboard classes | Unsupported as direct references | Verify stable lookup and lifetime per type |
| Other native classes | Unsupported | Explicit adapter or value contract |
| Addon-owned API objects | Instance-bound owner references | Recursive contracts remain unsupported |
| Plain data and enums | Checked JSON signatures | Unsupported 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.