Optional integrations
Use observables to decide when an integration is active and a declaration to own its subscriptions.
Declare the optional addon
Install the addon's package so its API and manifest are available to Builder. The behavior pack can remain absent from the world. Declare it in the consumer's manifest:
{
"optionalDependencies": [
{ "module_name": "@bedrock-core/example-leaderboard" }
]
}
Optional dependencies do not become native Minecraft pack requirements. Their imported state reads as undefined until a compatible provider publishes a snapshot. A registered namespace alone does not establish that its public API is ready.
Derive the decision
The Shop example forwards Economy balance events to the optional Leaderboard addon. It combines a local boolean config setting with the addon's scores snapshot:
import { scores } from '@bedrock-core/example-leaderboard';
import { computed } from '@bedrock-core/observable';
const enabled = computed(
() => configured.get() && scores.get() !== undefined,
[configured, scores],
);
configured is a boolean config leaf, which already implements ReadonlyObservable<boolean>. List every observable input explicitly. Local settings changes take effect immediately; addon availability follows snapshot delivery and discovery timeouts. A valid false, zero or empty snapshot is different from undefined.
For presence-only behavior, derive a boolean from core.registry.has(namespace) with [core.registry.addons] as the dependency list. For domain availability, read the provider's exported observable instead.
Own setup and cleanup
registerLeaderboardUpdates returns a Declaration<ReadonlyObservable<boolean>>. Its installer creates the computed value and attaches the event subscription while enabled:
let disconnect = (): void => {};
const stopEffect = effect(() => {
disconnect();
disconnect = () => {};
if (!enabled.get()) return;
disconnect = balanceChanged.subscribe(({ playerId, gold }) => {
void setScore(playerId, gold).catch(reportUpdateFailure);
});
}, [enabled]);
Inside install(core, lifetime), register lifetime.defer(() => enabled.dispose()) after creating the computed value and lifetime.defer(() => { stopEffect(); disconnect(); }) after creating the effect. Return { value: enabled } as the installation. Deferred cleanup also runs if setup throws. Stopping an effect only releases its dependency subscriptions; resources created inside its callback need their own cleanup. A computed value notifies only when its result changes, so score updates do not repeatedly reconnect an already active integration.
Install the declaration after configuration is available:
const { config } = core.register({
manifest,
config: registerConfig(configDef),
});
core.install(registerLeaderboardUpdates(
config.server.integrations.leaderboard,
));
The runtime stops declarations in reverse installation order. Disabling the setting or losing the addon disconnects balance forwarding; re-enabling or discovering a compatible provider reconnects it. Already dispatched calls can still complete, so handle rejections at the call site.
The Leaderboard example stores the latest submitted balances in memory. It starts empty, receives future balance events and resets when its runtime stops. It does not import historical balances. Other addons can read its scores observable through the same addon API.
Next steps
- Public addon APIs — export functions, observables and signals
- Declarations and services — install services with owned teardown
- Observable effects — react to explicit observable inputs