mcx-core

The core monorepo for MCX — a domain-specific language (DSL) for building Minecraft Bedrock Edition (MCBE) addons.

Disclaimer: MCX is not affiliated with or endorsed by Mojang/Microsoft. It is an independent, community-driven project.

---

Other README Versions

Language	Link
中文	./docs/README.zh.md
한국어	./docs/README.ko.md
日本語	./docs/README.ja.md

Introduction

MCX is a DSL that compiles .mcx source files into MCBE-compatible JSON components, UI forms, and event systems. It lets you build Minecraft Bedrock addons in a simple, declarative, and type-safe way — without hand-writing hundreds of JSON files.

The pipeline: .mcx file → parser → AST → transform (Babel) → compiled JS → MCBE JSON.

Features

• Component MCX — Generate MCBE component JSON (items, blocks, entities) fast and declaratively
• UI MCX — Build in-game UI forms with a simple syntax
• Event MCX — Subscribe to and handle game events cleanly
• App MCX — Tie components, UI, and events together into a runnable app
• MCX Client — Runtime framework (createApp, Event, ui, Utils) that runs your app in-game
• MCX Compiler — Core compiler with Rollup/Rolldown plugin support, paired with mbler for project scaffolding and builds
• Type-safe — Full TypeScript type definitions for all Minecraft component options, sound events, particle types, and more
• I18n — Built-in internationalization support (en / zh / ja / ko)
• Image assets — PNG, JPG, SVG, and GIF image components for texture generation

Packages

This is a pnpm workspace monorepo containing the following packages:

Package	Version	Description
@mbler/mcx-core		The DSL compiler — parser, AST, transform pipeline, and Rollup/Rolldown plugins
@mbler/mcx		Runtime framework — createApp, Event, ui, Utils
@mbler/mcx-types		Shared TypeScript type declarations for MCBE JSON formats
@mbler/mcx-component		Component runtime classes (Item, Block, Entity, Image) used at compile time
create-mbler		CLI scaffolding tool for new mbler projects

Monorepo Structure

mcx-core/
├── packages/
│   ├── core/              # @mbler/mcx-core — DSL compiler (parser → AST → transform → codegen)
│   ├── client/            # @mbler/mcx — runtime framework (createApp, Event, UI)
│   ├── types/             # @mbler/mcx-types — shared TypeScript type declarations
│   ├── mcx-component/     # @mbler/mcx-component — component runtime classes (Item, Block, Entity, Image)
│   └── create-mbler/      # create-mbler — CLI scaffolding tool for new mbler projects
├── docs/                  # README translations (zh, ja, ko) + TODO.md
├── scripts/               # verify-commit.js (commit-msg hook)
└── .github/workflows/     # CI (pnpm install → lint:packages → test)

Example MCX

Below is a complete example showcasing all four MCX file types — Component, Event, UI, and App.

1. Define an Item Component (items/custom_sword.mcx)

<Component>
  <items>
    <item id="sword.json">sword</item>
  </items>
</Component>
<script lang="ts">
import { ItemComponent } from "@mbler/mcx-component";

export const sword = new ItemComponent({
  id: "demo:custom_sword",
  name: "Custom Sword",
  components: {
    "minecraft:damage": 7,
    "minecraft:max_stack_size": 1,
    "minecraft:hand_equipped": true,
  },
});
</script>

2. Subscribe to a Game Event (events/player_join.mcx)

<Event @after>
playerJoin = onPlayerJoin
</Event>
<script lang="ts">
import { world } from "@minecraft/server";

export function onPlayerJoin(event: PlayerJoinAfterEvent) {
  event.player.sendMessage("Welcome to the server!");
}
</script>

3. Build a UI Form (ui/greeting.mcx)

<Ui>
<form title="Welcome" iconPath="textures/ui/icon_set_1.png">
  <label>Hello, {{ playerName }}!</label>
  <button click="handleClose">Close</button>
</form>
</Ui>
<script lang="ts">
export const prop = ["playerName"];

export function handleClose() {
  // close the form
}
</script>

4. Wire Everything Together in an App (app.mcx)

<script lang="ts">
import sword from "./items/custom_sword.mcx";
import "./events/player_join.mcx";
import { createApp } from "@mbler/mcx";
import { world } from "@minecraft/server";

createApp({}).mount(world);
</script>

Each .mcx file is compiled into MCBE-compatible JSON and TypeScript/JavaScript by the MCX compiler pipeline.

Quick Start

Create a new project

# Using the create-mbler CLI
pnpm create mbler my-addon
# or
npx create-mbler my-addon

Manual setup

# Install the compiler and runtime
pnpm add -D @mbler/mcx-core
pnpm add @mbler/mcx

Then configure your bundler (Rollup/Rolldown) with the MCX plugin and start writing .mcx files.

For full documentation and tutorials, visit the Docs.

Tech Stack

Layer	Technology
Language	TypeScript (strict mode)
Package manager	pnpm 11
Build	Rolldown
Bundler plugins	Rollup / Rolldown plugin for .mcx files
AST	Babel (@babel/parser, @babel/generator, @babel/types)
Type system	@volar/language-core for language service
Testing	Vitest
Linting	ESLint + Prettier
CI	GitHub Actions

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint all packages
pnpm lint:packages

# Full check (lint + test + typecheck)
pnpm check

# Format code
pnpm format

Contributing

Contributions are welcome! Please read the Contributing Guide before submitting a pull request.

Before committing, make sure to run:

pnpm check

Commit messages must follow the conventional commits standard (enforced via git hooks).

License

MIT © ruanhor