Anvil — Python‑First Toolchain for Minecraft Bedrock

Anvil lets you build Bedrock addons the same way you write gameplay logic: in code, not in JSON editors. Write blocks, entities, items, recipes, animation controllers, and even Script API logic in clean, type‑safe Python. Run a single command and Anvil turns that code into perfectly‑validated Bedrock packs, ready for your development folder or the Marketplace submission portal.

How Anvil Helps You Ship Faster

A typical Bedrock project involves hundreds of JSON fragments that must all line up with Mojang’s ever‑shifting schemas. One typo breaks everything. Anvil collapses that surface area to a single Python DSL and gives you proper IDE support—autocomplete, static checks, refactors—plus Marketplace rule validation baked in. When Anvil finishes a build you know your packs load and for partners Microsoft won’t bounce the upload.

Zero‑to‑Pack Workflow

anvil create <namespace> <project_name> scaffolds a project folder, generates all required UUIDs, and writes anvilconfig.json.
Drop assets—Blockbench models, textures, mcstructure files, sounds, Script API code—into the assets tree. Put gameplay Python in assets/python/.
anvil run compiles Python ➞ JSON, optionally compiles TypeScript ➞ JavaScript, validates everything, and exports your chosen package format.

Project Scaffold

project/
├── assets/
│   ├── bbmodels/
│   ├── particles/
│   ├── textures/
│   └── sounds/
├── marketing/
├── output/
├── scripts/
│   ├── javascript/
│   └── python/
├── world/
│   └── structures/
├── anvilconfig.json
├── esbuild.js
├── package.json
└── tsconfig.json

Source stays put; anvil run copies only what Bedrock needs into dev Behaviour/Resource packs.

`anvilconfig.json` Reference

All project metadata lives in one file and auto‑propagates—no duplicated strings.

Section	Keys	Purpose / Restrictions
`[MINECRAFT]`	`vanilla_version`	Target engine version. Auto‑pulled, read‑only.
`[PACKAGE]`	`company`, `namespace` (≤ 8 chars), `project_name` (≤ 16 chars), `display_name`, `project_description`, `behavior_description`, `resource_description`, `target` (`world` or `addon`)	Marketplace metadata.
`[BUILD]`	`release` (semver), `rp_uuid[]`, `bp_uuid[]`, `pack_uuid`, `data_module_uuid`, `script_module_uuid`	Identity & versioning. Missing IDs regenerate automatically.
`[ANVIL]`	`debug`, `scriptapi`, `scriptui`, `pbr`, `random_seed`, `pascal_project_name`, `last_check`, `experimental`, `preview`, `entry_point`, `js_bundle_script`, `minify`.	Feature toggles.
`[NAMESPACE]`	(reserved for future per‑namespace overrides)

Anvil Flags

Flag	Action
`--preview`	Target Minecraft Preview paths instead of release.
`--scriptapi`	Enable Script API; compiles sources from `assets/javascript/`.
`--scriptui`	Same, but for the UI module.
`--pbr`	Insert the PBR capability token and copy normal/spec maps.
`--random_seed`	Enables procedural‐world hooks; limits packaging to dynamic worlds.
`--addon`	Force addon mode; extra Marketplace naming constraints apply.

--help and --version behave conventionally.

Asset Pipelines

TypeScript

When scriptapi=true (or --scriptapi) Anvil generates package.json and tsconfig.json, esbuild.js for you. Drop TypeScript files into assets/scripts/javascript/ and import them freely. Anvil runs esbuild to bundle. Or you can use your own javascript bundler; just set js_bundle_script in anvilconfig.json to your entrypoint.

Localization

All literal strings are stored in localization.xlsx in the project root with autogenerated keys for the rest of Minecraft supported languages. Anvil compiles this into en_US.lang and other language files automatically.

Validation & Error Handling

• Namespacing — minecraft is forbidden; namespace ≤ 8 chars; project name ≤ 16.

• Component ranges — numeric arguments are clamped or hard‑failed when outside Mojang bounds.

• Manifest sanity — UUID format, duplicates, required icons/marketing art, capability flags.

Any failure raises a Python exception with file‑exact context; exit code 1 indicates “build failed.”

Extensibility

Place new modules in assets/python/ and inherit from core classes (Entity, Block, Item, …). Mixins and helper libraries are plain Python; Anvil introspects them automatically. Define post‑build hooks with @anvil.hook decorators when you need custom packaging logic.

Packaging Targets

Call ANVIL.package_zip() and set target in anvilconfig.json.

Target	Output
`addon`	Marketplace‑ready addon ZIP.
`world`	Marketplace‑ready world template ZIP

Call ANVIL.mcaddon() to get a ready‑to‑use .mcaddon file, which is a ZIP containing both resource and behavior packs. Call ANVIL.mcworld() to get a ready‑to‑use .mcworld file, which is a ZIP containing the world template and its resource and behavior packs. Call ANVIL.generate_technical_notes() to generate a technical_notes.pdf file with all the project Entities, Blocks, Items, Recipes, sounds, and more, for easy reference.

Icon/Marketing requirements differ per target; Anvil refuses to package until mandatory art exists.

Version Support & Performance

Python ≥ 3.10 on Windows 10/11 (Bedrock’s official dev OS).
Always tracks the latest Bedrock release; back‑targets are intentionally unsupported.

Current Gaps

Several new entity components and commands are stubbed; Contributions are welcome—open a PR.

Licence

Anvil is released under GPL v3. No proprietary code, no bundled assets.

Should You Use It?

If you’re tired of JSON busy‑work and comfortable writing Python, yes. Anvil keeps you in a real programming language, auto‑validates Marketplace constraints, and ships in seconds. If you prefer visual node editors or must target old Bedrock versions, look elsewhere. Otherwise, pip install mcanvil, scaffold, script, run—done.