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

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
• Form MCX (<Form>) — Build in-game forms using traditional FormData (ModalFormData / ActionFormData / MessageFormData)
• UI MCX (<Ui>) — Build in-game CustomForm UIs with Observable reactive binding (DDUI)
• Explicit form type — Set type="modal|action|message" on <Ui> or <Form> to override heuristic detection
• Nested UI elements — Child elements recursively flattened; grouping containers supported
• for loops with in / of — Iterate over arrays in templates with for="item in items" or for="item of items"
• Setup system — <Form setup> / <Ui setup> auto-collect declarations, no manual export needed
• defineProp macro — Compile-time prop declarations with defaults
• Lifecycle hooks — onStartup (once) and onMounted (per show) for setup logic
• 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: {},
});
sword.setDam;
</script>

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

<Event @after>
playerJoin = onPlayerJoin
</Event>
<script lang="ts">
import { world } from '@minecraft/server';
import { showForm } from '@mbler/mcx';
import form from '../ui/greeting.mcx';
export function onPlayerJoin(event: PlayerJoinAfterEvent) {
  const player = world.getPlayers({
    name: event.playerName,
  });
  player.sendMessage('Welcome to the server!');
  showForm(form, player, {
    playerName: event.playerName,
  });
}
</script>

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

Use <Form> for traditional FormData (ModalFormData / ActionFormData / MessageFormData):

<Form>
  <label>{{ playerName }}!</label>
  <label>Hello</label>
  <button click="onClick">Close</button>
</Form>
<script lang="ts">
export function onClick() {
  // close the form
}
</script>

3b. Build a CustomForm (ui/settings.mcx)

Use <Ui> for new CustomForm with Observable reactive binding:

<Ui setup>
  <title>Settings</title>
  <input :value="name">Player name</input>
  <toggle :value="enabled">Enabled</toggle>
  <slider :value="volume" min="0" max="100">Volume</slider>
  <button :if="advanced" click="onAdvanced">Advanced</button>
  <button click="handleSave">Save</button>
</Ui>
<script>
import { ref } from '@mbler/mcx';

const name = defineProp('Player'); // → ObservableString
const enabled = defineProp(false); // → ObservableBoolean
const volume = defineProp(50); // → ObservableNumber
const advanced = ref(true); // ref() works too

function onAdvanced() {
  advanced.value = !advanced.value;
}

function handleSave() {
  // name.getData() gets current value
}
</script>

defineProp accepts string / boolean / number literal defaults (including template literals and negative numbers) and wraps them in the matching Observable automatically. Non-literal defaults are passed through as plain values.

Reactive bindings: {{ x }} interpolation unwraps Ref/Observable values, :value gives two-way binding, :if toggles visibility live, and :disabled / :tip / :description accept Ref/Observable bindings. Elements inside for="x in list" loops support :if and the other attributes too.

4. Auto subscribe event in App mcx (app.mcx)

<script lang="ts">
import event from './events/player_join.mcx';
event.subscribe();
// also can use: event.subscribe("playerJoin")
</script>

5. CreateApp in index.ts (index.ts)

import app from './app.mcx';
import { createApp } from '@mbler/mcx';
import { world } from '@minecraft/server';

createApp(app).mount(world);

More Usage See Bedwars Addon

Quick Start

Create a new project

# Using the create-mbler CLI
pnpm create mbler

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