# MMS

> MMS (Minecraft Metascript) is a language for Minecraft Java Edition data packs and resource packs. Declarations such as `LootTable`, `Recipe` and `Function` compile to the JSON files and `.mcfunction` files the game reads.

Every page below is Markdown. The same page as HTML is at its URL without `.md`.

## Start

- [Getting started](https://minecraftmetascript.github.io/mms/docs/start/getting-started.md): MMS is a small language that compiles to Minecraft Java Edition data packs. You declare resources and functions in .mms files, and mms build writes the JSON and .mcfunction files. The target is Minecraft 26.3.
- [Tutorial: a magic wand](https://minecraftmetascript.github.io/mms/docs/start/tutorial-custom-item.md): This tutorial makes a Blink Wand: a stick that throws its holder six blocks forward on right click, with a cooldown, durability, a recipe and a place in a loot table. It takes about fifteen minutes, and each step builds, so you can try the wand in a world as you go.
- [Tutorial: a wave arena](https://minecraftmetascript.github.io/mms/docs/start/tutorial-minigame.md): This tutorial builds a small game: mark some spawn points, start the arena, and waves of mobs come at you, each after a short rest. Beat the last wave and you win. Along the way it covers typed data, state that survives a /reload, function code, compile-time loops and tests that run without the game.
- [Tutorial: a guide book](https://minecraftmetascript.github.io/mms/docs/start/tutorial-book.md): This tutorial writes the book a map hands to new players: a few pages with headings, colours, links that turn pages and run commands, and the reader's death count. Then it puts longer books in files of their own and hides them in a chest.
- [Tutorial: a custom dimension](https://minecraftmetascript.github.io/mms/docs/start/tutorial-dimension.md): This tutorial builds a dimension of floating islands, step by step. The finished project is examples/sky-islands, split into dimension.mms, terrain.mms and visit.mms. In the web editor, open it from Examples. The tests build it on every change, so it stays in step with the language.
- [Tutorial: a jigsaw dungeon](https://minecraftmetascript.github.io/mms/docs/start/tutorial-structure.md): This tutorial grows a dungeon out of rooms and halls, the way the game grows villages and bastions. You build the pieces in the game, MMS wires them together, and the editor shows the layouts the game will make before you open a world.

## Guides

- [Writing resources](https://minecraftmetascript.github.io/mms/docs/guides/resources.md): Every JSON resource kind can be written as an object literal that mirrors the JSON. Two kinds of shorthand sit on top of that.
- [Functions](https://minecraftmetascript.github.io/mms/docs/guides/functions.md): Function bodies and event hooks (OnLoad, OnTick, OnFirstJoin, OnRespawn, OnAdvancement) compile to .mcfunction files.
- [Keeping state](https://minecraftmetascript.github.io/mms/docs/guides/state.md): A data pack has a few places to remember things between commands: scoreboards, command storage and tags on entities. MMS gives each a name you can read and write like a variable. This guide is about choosing between them.
- [Cutting repetition](https://minecraftmetascript.github.io/mms/docs/guides/repetition.md): Data packs repeat themselves. Sixteen colours need sixteen recipes, every mob's loot table has the same Looting rule, and a number that matters is typed into ten files. MMS has four tools for this, and they all run when the pack is compiled: the game only ever sees plain files.
- [Making your own kinds](https://minecraftmetascript.github.io/mms/docs/guides/blueprints.md): CustomItem, Book and JigsawStructure are not built into the compiler. Each is a Blueprint: a kind of declaration written in MMS, which turns a few fields into the declarations the game needs. You can write your own, and yours get the same completion, checking and hover as the built-in ones.
- [Testing functions](https://minecraftmetascript.github.io/mms/docs/guides/testing.md): Finding out whether a function works usually means building the pack, opening a world, running /reload, setting up some scores by hand and watching chat. A Test does that in a fraction of a second, without the game: mms has an interpreter for the commands functions compile to, and a test runs your functions in it and checks what they did.
- [Shaping terrain](https://minecraftmetascript.github.io/mms/docs/guides/terrain.md): A world's shape comes from one number per block, the density. Where it is above 0 the generator places stone, and where it is below 0 it leaves air, or water below sea level. A DensityFunction is the formula for that number, and shaping terrain means writing formulas.
- [Building jigsaw pieces](https://minecraftmetascript.github.io/mms/docs/guides/jigsaw-pieces.md): A jigsaw structure is only as good as the agreement between its pieces. The game joins two pieces when their jigsaw blocks face each other and their names match, and checks nothing else: a doorway one block too high, a floor at the wrong level or a wall of the wrong stone still joins, and looks wrong. Write the agreement down once, as a short spec, and anyone can build pieces to it: you, other people, or several AI agents at once, each building a few pieces in parallel. Pieces built to the same spec fit together the first time.
- [Building and playing](https://minecraftmetascript.github.io/mms/docs/guides/building.md): Writing a pack is a loop: edit, check, build, look at it in the game. This guide is about making that loop short, and about what to do with the pack once it works.
- [A tour of the editors](https://minecraftmetascript.github.io/mms/docs/guides/editors.md): MMS has two editors: the web editor, which needs no install, and the VS Code extension. Both run the same engine as the mms command line, so they report the same problems and build the same pack. This page shows what they can do and where to find it.
- [Lint rules](https://minecraftmetascript.github.io/mms/docs/guides/lint.md): The engine lints every declaration that checks without errors. Findings appear in the editor, in mms check (hints only with -hints), and as LSP diagnostics with quick fixes. mms fix and the editor's "Fix all" (Ctrl/⌘+Alt+F) apply every safe fix. In the web editor, Ctrl/⌘+. lists the quick fixes at the cursor, and Format is Shift+Alt+F (⌘+Shift+I on macOS) or Ctrl/⌘+S. A safe fix never changes the generated pack.
- [AI agents](https://minecraftmetascript.github.io/mms/docs/guides/agents.md): mms mcp is a Model Context Protocol server. It gives an AI agent that writes MMS the same engine the editors use, so the agent can check its work, see what it compiles to, run its tests and look names up without guessing.

## Concepts

- [How functions compile](https://minecraftmetascript.github.io/mms/docs/concepts/how-functions-compile.md): What a function becomes in the data pack: where its values live, and how branches, loops and early exits turn into commands. You don't need this to write functions, but it helps when reading the generated .mcfunction files.

## Language

- [Declarations](https://minecraftmetascript.github.io/mms/docs/reference/language/declarations.md): A file is a list of declarations. Each one starts with its kind, a PascalCase word, then its name:
- [Values and types](https://minecraftmetascript.github.io/mms/docs/reference/language/values.md): Values look like the JSON they become, with less punctuation. Every value is checked against the type its place expects, and that type also decides what shorthand means there.
- [Constants, templates and loops](https://minecraftmetascript.github.io/mms/docs/reference/language/reuse.md): Four tools cut repetition: const names a value, Template names a value with parameters, comprehensions build lists, and a top-level for repeats declarations. They all run at compile time and write nothing of their own: only the declarations that use them reach the pack. private keeps a name to the file it is written in.
- [Blueprints](https://minecraftmetascript.github.io/mms/docs/reference/language/blueprints.md): A Blueprint declares a new kind of declaration. Its fields are checked and completed like the game's own, its check block reports problems, and its emit block writes the declarations it stands for. CustomItem, Book and JigsawStructure are Blueprints written this way, in the prelude: their pages under Declaration kinds list their fields.
- [Functions](https://minecraftmetascript.github.io/mms/docs/reference/language/functions.md): A Function body is code that compiles to a .mcfunction file. It mixes raw commands, which start with /, with statements that compile to commands. The Functions guide explains each part at length, and How functions compile shows what it becomes.
- [Text](https://minecraftmetascript.github.io/mms/docs/reference/language/text.md): Wherever the game takes a text component, a string is markup: a small Markdown-like format for Minecraft text. A string without markup is the same plain string in the output.
- [Tests](https://minecraftmetascript.github.io/mms/docs/reference/language/tests.md): A Test runs functions in an interpreter, without starting the game, and checks what they did:

## Reference

- [Declaration kinds](https://minecraftmetascript.github.io/mms/docs/reference/kinds.md): the 92 kinds a declaration can have, and the folder each writes to
- [Book](https://minecraftmetascript.github.io/mms/docs/reference/kinds/Book.md): its fields, and what its name stands for
- [CustomItem](https://minecraftmetascript.github.io/mms/docs/reference/kinds/CustomItem.md): its fields, and what its name stands for
- [JigsawStructure](https://minecraftmetascript.github.io/mms/docs/reference/kinds/JigsawStructure.md): its fields, and what its name stands for
- [Templates and forms](https://minecraftmetascript.github.io/mms/docs/reference/prelude.md): the prelude's templates and types, and what each operator means by type
- [Helpers](https://minecraftmetascript.github.io/mms/docs/reference/helpers.md): 758 helpers in 54 groups, each building one typed object; each group has a page
- [Types](https://minecraftmetascript.github.io/mms/docs/reference/types.md): every named type from the game's schema, with values that fit
- [Lint rules](https://minecraftmetascript.github.io/mms/docs/reference/lint.md): the 21 lint rules and their default severities; each rule has a page

## Optional

- [Everything in one file](https://minecraftmetascript.github.io/mms/llms-full.txt): every page above, and every helper group and lint rule, as Markdown
- [Reference as YAML](https://minecraftmetascript.github.io/mms/docs/reference.yaml): kinds, helpers, types and lint rules as data