Amethyst: a native C++ modding layer for Minecraft Bedrock, now part closed

What Amethyst is: native C++ modding for the Bedrock client

The project description is terse: native c++ modding for MCBE 1.21.0.3 for building client side mods. That is the whole scope, and it is a scope with a specific audience. The topics attached to the repository are `minecraft`, `minecraft-bedrock` and `modding`, so this is Bedrock, and the client side qualifier means the work targets the client process rather than a server.

Building in native code rather than through a scripting API is the defining choice. A mod that is a C++ library linked into the client can reach far deeper into the game than a script that is limited to whatever a sandbox exposes. The cost of that reach is that the mod author is writing code against a specific client version, and the repository is organised around that reality.

The primary language is C++, and the tree is laid out like a library project rather than a game: a `src/` directory, an `AmethystAPI/` directory that carries the name of the library's API, a `data/` directory, a `mod.json` manifest, and a `LICENSE` file. There is also a `.gitmodules` file, which indicates the build pulls in external repositories as submodules, and a `.github/` directory for workflow definitions.

For the reader deciding whether to adopt this, the honest assessment is that Amethyst is infrastructure for people who already know how to build native Minecraft Bedrock modifications, not a framework that gives a JavaScript or Python developer a new capability.

The version split: open 1.21.x, mixed source 1.26.x

The README states that Amethyst for 1.26.x is a mixed source library, that the core runtime is fully open source, and that past 1.21 the project is largely a bring your own types library. That last phrase is doing significant work and it is worth reading literally: past 1.21, the types are expected to come from elsewhere, and Amethyst supplies the runtime rather than a complete, self-contained set of declarations.

The author is also direct about which line to pick. The README says 1.21.x code will remain fully open source, that for people interested in trying out modding, 1.21.x is really the best version to mod, and that 1.26.x is pretty unapproachable to beginners, which is partly why the author is stopping trying to cater to that target group.

That last sentence matters for planning. It is a stated intention to narrow the audience for the newer line rather than an accident, so a team that plans to live on the 1.26.x branch is betting that a closed core and externally supplied types will keep working for them, with no promise of the openness that 1.21.x still has.

One discrepancy is worth flagging before you dive in. The project description still points at MCBE 1.21.0.3, while the README discusses 1.26.x as the active direction. The description is the older of the two statements, and the tree has no separate branch naming to disambiguate which line a given commit belongs to.

Why the author closed parts of the source

The README has a section headed Why close source parts of amethyst, and the reasoning is personal and economic rather than technical, which is unusual to see written down and useful to know before you rely on the project.

The first reason is adoption. The author says that Amethyst has gone pretty unused by the general developer community, that the extra work being done to keep the project open source does not feel particularly worth it, and that going closed source would allow more freedom and speed. In other words, the closed parts are a response to a perceived lack of return on the effort of keeping them open.

The second reason is about the audience for reverse engineering work. The README argues that reverse engineering Minecraft is not applicable to 99% of people in the Minecraft space, and that if Amethyst were to remain usable by others, the best thing would be to build a scripting layer in JavaScript for client side modding. That is explicitly described as not on the near term roadmap, but something the author has considered.

The third is the beginner question already mentioned. A JavaScript scripting layer is the shape of the project that would reach the community the author wants, and the author is candid that the current 1.26.x line is not it. Anyone expecting the direction of travel to become more open over time should note that the documented intention points the other way, toward a proprietary core with a scripting layer on top.

The build is driven by xmake.lua, and the README documents no commands

The repository contains a single build definition file, `xmake.lua`, alongside the Makefile-free tree. That tells you the project is built with xmake rather than with CMake, a plain Makefile, or a Visual Studio project checked into the tree.

What the repository does not contain is any documentation of how to run that build. The README has no installation section, no prerequisites, no compiler version requirement, no list of dependencies, and no command to compile the library or to produce a mod. There is also no example mod directory and no sample manifest, only the `mod.json` file for the project itself.

That absence is the single biggest practical obstacle for a new adopter, and it is not a small one. Native modding means the toolchain matters: the C++ standard, the SDK the code compiles against, the linker settings, and the exact client version, and none of that is written down in the repository. The `.gitmodules` file implies external sources are vendored as submodules, which is another step that the README does not walk through.

So a first-time user has to reverse engineer the build from `xmake.lua` and `src/`, or ask the community linked in the README header. That is feasible for an experienced native developer, and it is a real cost compared with a project that ships a one-line build command.

Apache-2.0 on the licence file, mixed reality in the tree

The licence recorded for the repository is Apache-2.0, and a `LICENSE` file sits at the top level of the tree. Apache-2.0 is a permissive licence with an explicit patent grant, which is a reasonable choice for a library that others are meant to link into their own mods.

The complication is the mixed source arrangement. The metadata describes the repository as a whole under one licence, and the README says the core runtime for 1.26.x is fully open source while the project is a mixed source library overall. If parts of the 1.26.x line are not in this repository under that Apache-2.0 grant, then the grant plainly cannot cover them, and the practical reading is that the Apache-2.0 terms apply to the open portion and to the 1.21.x line, not to any closed component that is delivered separately.

This is a description of what the licence metadata and the README imply, not legal advice. A developer planning to redistribute a mod built on Amethyst, or to contribute a patch to the open 1.21.x code, should read the `LICENSE` file directly and confirm which files it covers.

The `AmethystAPI/` directory is worth a look in that context, since a directory named after the API is the natural place for the header set a downstream modder includes, and headers are where a licence boundary would be felt first.

Release history and what the tags tell you

The repository has three tagged releases in its history: `v2.0.2` dated 2025-10-04, `v2.1.1` dated 2025-11-01, and `v2.2.1` dated 2025-11-05, with release notes in each case reading the same way. Two of the three landed within the same week in November 2025, which reads as a burst of release activity rather than a slow drip.

The last push to the default branch was on 2026-10-16, so commits are landing on `main` well after the newest tag. That gap is a real decision to make: build against `v2.2.1` and you get a named version but code from November 2025, or track `main` and you get recent fixes with no version marker and no promise of stability.

For a library whose whole purpose is hooking a specific client build, the version of the game matters more than the version of the library, so the practical question for an adopter is which client release the `v2.2.1` code targets and whether `main` has moved on to a different target since. The README does not document that mapping, and there is no changelog file in the top level of the tree to consult.

A companion point on scope: nothing in the repository documentation addresses server side modding, and the description restricts the project to client side mods for a specific version. If the goal is to modify server behaviour, this library is the wrong shape of tool regardless of how good the code is.

Editorial conclusion

Amethyst makes sense for a developer who already writes native code and wants to hook client side Minecraft Bedrock behaviour at the C++ level rather than through a scripting layer, and the 1.21.x line is the version to start on because its author calls it the most approachable. It does not make sense for a beginner modder, for a team that needs every line of the 1.26.x runtime to be auditable, or for anyone who needs a documented install path, since the README gives no build command and the only build artefact named in the tree is `xmake.lua`. Before you commit, check the `LICENSE` file for what the Apache-2.0 grant actually covers in a mixed source tree, confirm which of the two `1.21.0.3` and `1.26.x` versions your target client expects, and look at the tagged releases, where the newest is `v2.2.1` from 2025-11-05.

Frequently asked questions

Official sources

1. FrederoxDev/Amethyst on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases