MBLER

A development toolchain for Minecraft Bedrock Edition Addons, built on Rolldown.

Features

• MCX DSL — Domain-specific language for Minecraft scripting with type safety
• Manifest Generator — Auto-generates manifest.json with deterministic UUIDs and module dependencies
• Bundle — Bundles scripts into single ESM files via Rolldown, with auto-externalization of Minecraft APIs
• Component build — Asset import support (.png, .svg, etc.) via MCX image components
• Watch mode — Incremental rebuild & file-copy on change via mbler watch
• Minification — Supports oxc (default), terser, and esbuild minifiers
• Build cache — Configurable caching (none/memory/file/filesystem/auto) for faster rebuilds
• Release packaging — Build .mcaddon archives via BUILD_MODULE=release environment variable
• PMNX Marketplace — Publish, install, uninstall, and manage addon packages
• i18n — Built-in internationalization (English & Chinese)
• mcx-tsc — Standalone MCX type-checker binary

Installation

Prerequisites: Node.js >= 20.0.0, pnpm (recommended) or npm

npm install -g mbler

Quick Start

pnpm create mbler

pnpm build

CLI Commands

Command	Alias	Description
help [command]	h	Show help for a command
init [args...]		Initialize a project config file
build		Build the addon (behavior + resources)
watch		Watch mode with incremental rebuild
work [path]	c	Set or display the working directory
set-work-dir <on|off>		Enable/disable persistent working directory
version [version]		Show or set version; -show commit|version
lang [zh|en]		Switch CLI language
config <get|set|point> [key] [value]		Global configuration
publish		Publish to PMNX marketplace (-tag, -build skip|enable)
unpublish <package>		Remove a package from PMNX
install <package>		Install a PMNX package
uninstall <package>		Remove a PMNX package
login [token]		Authenticate with PMNX marketplace
profile		View current user profile
view <package>		View package details
log <point|clean>		Log management

Configuration

Create a mbler.config.js in your project root:

// @ts-check
import { defineConfig } from 'mbler'
export default defineConfig({
  name: 'my-addon',
  description: 'A custom Minecraft addon',
  version: '0.0.1',
  mcVersion: '1.21.120',
  script: {
    main: 'index.ts',
    lang: 'mcx', // 'ts' | 'mcx' | 'js'
    ui: true, // enable @minecraft/server-ui
  },
  minify: false, // 'oxc' | 'terser' | 'esbuild'
  outdir: {
    behavior: './dist/dep',
    resources: './dist/res',
    dist: './dist.mcaddon',
  },
})

Project Structure

mbler/
├── bin/                    # CLI entry points
│   ├── mbler.js            # Main CLI binary
│   └── mcx-tsc.js          # MCX type-checker
├── src/
│   ├── cli/                # Command definitions & dispatcher
│   ├── build/              # Build engine (Rolldown-based)
│   │   ├── manifest.ts     # manifest.json generator
│   │   ├── release.ts      # .mcaddon packaging
│   │   ├── cache.ts        # Incremental build cache
│   │   ├── minify.ts       # Minifier plugins
│   │   └── sapi.ts         # SAPI version resolver
│   ├── publisher/          # PMNX marketplace integration
│   ├── i18n/               # Internationalization (zh, en)
│   ├── uuid/               # Deterministic UUID generation
│   └── utils/              # Shared utilities
├── example/mbler-int/      # Example addon project
├── tests/                  # Test suite (Vitest)
├── dist/                   # Build output
└── package.json

Related Repos

MCX Core · MCX Language Server · MCX Template · MNX Market

Documentation

• English Docs
• 中文文档
• 한국어
• 日本語

Release Platforms

GitHub · Gitee · npm

License

MIT