Addon manifests
Declare an addon's namespace and metadata in its owning behavior pack's manifest.json, then import that file in the script entry.
Register the addon
import { core } from '@bedrock-core/server';
import manifest from '../manifest.json';
core.register({ manifest });
Enable resolveJsonModule in the project's TypeScript configuration. Builder resolves manifest inheritance, project defaults and local pack requirements before bundling script imports.
Declare identity and metadata
The self-contained AddonManifest type describes native v3 fields and Core authoring extensions. JSON imports fit the type directly.
{
"$schema": "https://bedrock-core.drav.dev/schemas/builder/beta/pack-manifest.schema.json",
"format_version": 3,
"namespace": "studio_example",
"header": {
"name": "pack.name",
"description": "pack.description",
"uuid": "1c68c36d-d3b4-4dd3-85e3-f822cab39579",
"version": "1.0.0"
},
"metadata": { "authors": ["Studio", "Contributor"] },
"modules": [{
"type": "script",
"language": "javascript",
"uuid": "0cb96c35-179b-47d9-905a-783017a08dcc",
"entry": "scripts/main.ts"
}],
"dependencies": [
{ "uuid": "ac8642cf-82b7-4f63-8cd5-3edac55ad779", "version": "1.0.0" },
{ "module_name": "@minecraft/server" }
],
"optionalDependencies": [{
"uuid": "8376c971-a776-490e-91d3-38f3a6d395db",
"version": "1.0.0",
"namespace": "studio_extra"
}],
"thumbnail": "thumbnail.png"
}
Use unique pack and module UUIDs. The namespace uses lowercase letters, digits and underscores; minecraft is reserved. Each scripted addon has its own namespace. A linked BP/RP pair can use the same content namespace.
config.json contains the build configuration. Namespace declarations belong to individual manifests, including projects that build several independent addons. Namespace is the key for commands, discovery, RPC, shared state and persistence. Keep it stable across addon updates. Two behavior packs cannot share a namespace, including packs with data modules alone; runtime discovery also reports collisions between loaded addons.
| Source | Supplies |
|---|---|
Manifest namespace | Addon identity and the default prefix for owned UI, guides and translations |
Manifest header.name and header.description | Display text or localization keys |
Manifest header.version | Addon version |
Manifest metadata.authors | Author names |
Project name, description, authors | Defaults for omitted manifest metadata |
Root package.json version | Default for an omitted header version |
Explicit manifest fields win over defaults. Module versions default to the selected header version. Set header.name to pack.name and header.description to pack.description. Author their values as pack: { name, description } in each locale object.
The authored and exported manifest headers keep those literal keys. Each pack resolves them from its own texts/<locale>.lang file. A BP and RP may have different display values even when they share a namespace.
Core registry display fields and addon UI use <namespace>.pack.name and <namespace>.pack.description in the shared client language catalog. Builder emits those lookups automatically so two addons can show different names in the same UI. They are display references, not values to put in a manifest header. Authored locale objects do not include the namespace prefix.
Additional fields and validation
| Field | Rule |
|---|---|
namespace | Required Core addon identity; lowercase letters, digits and underscores, excluding minecraft |
dependencies[].namespace | Selects a local pack; references between scripted addons also require Core registration |
optionalDependencies | Same dependency objects as dependencies; creates no native load requirements |
thumbnail | PNG path inside the owning behavior pack or selected local resource pack |
extends | Builder-only relative manifest inheritance |
dependencies[].module_name | External addon or Minecraft scripting API; Builder resolves native requirements |
A BP/RP pair may share its namespace. A behavior pack's reference to its own namespace selects the paired resource pack; the resource pack can reference the behavior pack the same way. These are native pack links and create no Core self-dependency. References to another namespace select its behavior pack, or a unique resource pack when no behavior pack exists. Multiple resource candidates require an explicit UUID. Core dependencies cannot include the same addon as both required and optional. A Minecraft scripting API dependency cannot carry a Core namespace. Native author names stay in metadata.authors.
Builder validates native v3 semantic versions and pack structure. Inheritance and project defaults resolve before source imports are compiled. Authoring fields are stripped from exported native manifests. Module declarations become native module_name/version requirements before script imports are compiled.
Required and optional dependencies
Declare an addon once in the manifest to connect native pack loading and Core dependency resolution:
{
"dependencies": [
{ "module_name": "@minecraft/server" },
{ "module_name": "@bedrock-core/example-economy" }
]
}
Minecraft scripting API entries stay native module_name requirements. Builder infers an omitted version from the installed package without executing package code. Minecraft type-package prereleases include their game target: @minecraft/server-gametest@1.0.0-beta.1.26.50-stable produces native version 1.0.0-beta. A supplied version is an explicit override.
Other module entries identify external addons, normally Core addons. Their installed packages expose the addon's primary authored manifest through a standard package export:
{ "exports": { "./manifest.json": "./packs/BP/manifest.json" } }
For packages with several BPs, export each API from inside its owning pack and expose that pack's manifest as an explicit package subpath, such as ./stats/manifest.json. A dependency on @studio/addons/stats resolves the closest exported manifest above that entry's runtime source. Subpaths in another BP need their own required or optional declaration; a root dependency covers entries owned by its own BP. See public addon APIs for the complete layout.
Builder reads that manifest's UUID, version and scripted addon namespace. The dependency version comes from an explicit requirement, then the exported manifest's header, then package.json. A Core-aware addon exports the authored manifest with its namespace; the native Minecraft export has those authoring fields removed.
Shop's native export receives Economy's UUID/version requirement. Shop's bundled manifest retains Economy's namespace, which becomes a Core registry requirement. Ordinary npm libraries are handled through package.json and imports; a manifest module entry must describe an addon or native scripting API.
Import a @bedrock-core addon's public API through its normal package exports. Builder replaces these imports with typed client bindings; the provider's implementation stays in its own behavior pack. Functions use RPC, state handles read synchronized snapshots, and event handles subscribe to the provider. This also applies to optional addons. Minecraft scripting API imports remain native engine imports.
The same forms work in optionalDependencies. Optional records stay available to Core imports and create no native Minecraft load requirement.
Native and Core dependencies
A UUID/version record is a native pack requirement. For an external scripted addon, adding namespace declares a Core integration at that address:
{
"dependencies": [{
"uuid": "e8c7c5a5-809e-4aba-a075-f3a9ff76fa61",
"version": "2.0.0",
"namespace": "studio_library"
}]
}
A plain UUID reference remains native even when its target happens to register Core. A namespace-only reference, such as { "namespace": "studio_library" }, resolves a configured local pack. A link between two scripted addons retains the target namespace for Core discovery. BP/RP pair links and resource references resolve to native UUID/version records. Local references can omit their version; external UUID requirements include it.
The dependency declares intent. Availability is confirmed by the target's Core runtime registration and existing runtime metadata. Sharing a BP/RP namespace, using Builder, importing a library or announcing a raw Sync peer does not create another Core registration. Registry describes presence, missing dependencies and RPC-ready registrations.
Export a public API
Expose the authored API and manifest using normal package exports. The manifest identifies the scripted behavior pack that owns the API:
{
"exports": {
".": "./packs/BP/scripts/api/index.ts",
"./manifest.json": "./packs/BP/manifest.json"
}
}
Consumers install the addon package, declare its module_name in their manifest and import its public values:
import { getBalance, currency, balanceChanged } from '@studio/economy';
const balance = await getBalance(player.id);
const currentCurrency = currency.get();
const unsubscribe = balanceChanged.subscribe(updateBalance);
Builder inspects the public TypeScript contract without executing the provider. It binds exports in the owning pack and generates clients in consumers. Async functions, read-only state/event handles, nested API objects and static immutable JSON values are supported. Type-only imports erase normally. Public entries must belong to the scripted pack identified by the exported manifest.
See public addon APIs for authoring, lifecycle, errors and supported values. Ordinary npm libraries remain normal imports and package dependencies.
Catalog artwork
The icon comes from pack_icon.png at the behavior-pack root, with the linked resource-pack root as fallback. Builder retains the root image for the pack list and copies it to textures/<namespace>/pack_icon.png in the selected local resource pack. Catalog UI uses that texture path.
Set thumbnail to a PNG path relative to the behavior pack or its resource pack. Builder copies it to textures/<namespace>/thumbnail.png and supplies the texture path to runtime imports. Existing textures with different content are protected from replacement.
The resource destination follows the owner's direct local dependencies. When several resource packs are available, the UI stage's owner and resourcePack settings select the destination. Client artwork requires a resource-pack destination.
Editor schema and exported files
The authored-manifest schema covers native fields, inheritance and addon extensions. It is separate from the manifest-stage settings schema. Add it to each authored manifest or associate it through the editor.
Only one schema reference is needed in config.json; its project schema includes all built-in stage settings. See editor schemas.
Script imports receive the resolved authored manifest. Builder removes authoring fields before native validation and export, preserving native UUID/version requirements. Internal build data stays inside the build pipeline.
Next steps
- Configuration — profiles, pack paths and stage settings
- Runtime registration — addon declarations and services
- Translation authoring — localized pack display text