Getting Started

This walkthrough creates a fresh add-on, builds it, hot reloads it into Minecraft, and ships it as a .mcaddon. It takes about five minutes.

Prerequisites

• Node.js 20.19 or later. Check with node --version.
• A Minecraft install if you want bb run to copy files into the game. See Custom Deploy Path when auto detect misses.

Create a new project

npm install -g @aplok/bedrock-builder
$ bb init my-addon
$ cd my-addon
$ npm install

bb init writes the config, both manifests with fresh UUIDs, a working entry file, and the texture registries. Answer the prompts, or pass --here, --js, --git, and --install to skip them.

Look at what you got

my-addon/
  config.json
  package.json
  tsconfig.json
  src/main.ts
  packs/BP/
  packs/RP/
  dist/

Full breakdown: Workspace Layout.

Generate your first feature

bb new weapon fire_sword --mode 3d --icon sword

The generator writes the item JSON, the attachable, the render controller, and the texture plus lang entries. Generators accept prompts with defaults, or run fully flagged for scripts and CI. Full list: CLI: bb new.

Run your first build

bb build

The default build is dev mode: sourcemaps on, no minify, fast. Output lands in dist/packs/BP/ and dist/packs/RP/. Pass --release for minified output with no sourcemaps.

Hot reload into Minecraft

bb run --watch

This builds the project, copies the result into the game dev pack folders, and rebuilds on every save. Reload the world to see updates. Details: Hot Reload Setup.

Ship a .mcaddon

bb ship

This runs a release build, validates both manifests, and zips the packs into dist/my-addon-1.0.0.mcaddon. Details: Shipping a .mcaddon.

Next steps

• Learn the Build Pipeline and the Config Schema.
• Bookmark the CLI reference and the Exit Codes for CI.

Edit this page