Mojang/bedrock-protocol-docs: the Bedrock protocol schemas and how to build them locally

The site is generated from GitHub Releases, not from the schemas in main

The usual assumption about a documentation repository is that the checked-in source is the source of truth and the published site is a rendering of it. This project inverts that. The README states that the website is assembled from the metadata found in the repository's GitHub Releases and not from source in `main`. The `json/` directory holds the protocol schemas, but the published release history is derived from the Releases tab instead.

That choice has consequences for anyone who clones the repository expecting to read a versioned history locally. The versions you see on the site are tied to release artifacts, each of which carries its own tag and its own archive. The preparation step calls the GitHub API and downloads those release archives, so the version list cannot be produced without network access to GitHub.

It also means the branch content and the published history can drift in different ways. A reader who wants to know which packet layout applied to a given client build has to follow the release chain, not the git history of the schema files.

A repository split into schemas, guides, scripts and an Astro app

The layout divides responsibility in a way that is easy to follow once you know where to look. `json/` holds the protocol schemas. `additional_docs/` holds the source Markdown and assets for the guides section, so prose documentation lives apart from machine-readable type data. `legacy_changelogs/` holds changelogs that predate the generated release history, which is the escape hatch for versions the automated pipeline does not cover.

`scripts/` prepares release metadata and generates the data and pages consumed by the site, and `tools/protocol-docs-generator/` contains the Astro application that renders the documentation. There is also a `vendor/` directory at the top level, and the package manifest installs the generator as a local tarball rather than from a registry.

A practical consequence is that a contributor touching the schema data and a contributor writing a guide work in different trees, and only the second one can reason about a page without worrying about the release pipeline.

Building the docs locally needs Node 24 and npm 11

The build instructions are short. The README asks for Node.js 24 or newer and npm 11 or newer, and the manifest pins the package manager as `[email protected]` with engines of `>=24.0.0` for Node and `>=11.0.0` for npm. From the repository root the local loop is two commands:

npm ci
npm run dev

`npm ci` installs from the committed lockfile, which matters here because one dependency resolves to a file inside `vendor/` and must exist on disk for the install to work. `npm run dev` runs the metadata preparation with a cache flag, then the generation step, then starts the Astro development server against `tools/protocol-docs-generator`.

The two additional commands cover the other two common needs:

npm run check
npm run build

`npm run check` performs the same preparation and generation and then runs `astro check`, while `npm run build` ends with `astro build`. Both begin with the same TypeScript project check over the scripts directory, so type errors in the preparation code surface before anything is rendered.

prepare:metadata is the step that fails without a GitHub token

Every script in the manifest funnels through the same preparation step, and that step is the fragile part of the local loop. The README says the preparation calls the GitHub API and downloads release archives, and that you should set `GITHUB_TOKEN` when necessary to authenticate those requests or avoid the unauthenticated API rate limit.

So the realistic failure mode on a fresh machine is not a code error. It is a rate limit or an authentication error surfacing during metadata preparation, before the generator or the Astro server ever starts. The fix is documented: set the environment variable to a token with enough access to read releases and their archives, then rerun the command.

The `dev` script passes `--cache` to the preparation step, so repeated local runs reuse previously downloaded metadata. The `check` and `build` scripts do not pass that flag. Anyone working offline should expect `npm run dev` to behave differently from `npm run build` in a fresh checkout.

Version tags such as v1.26.70-preview.20 drive the generated history

The recent releases carry preview version names of the form `v1.26.70-preview.20`, `v1.26.60-preview.30` and `v1.26.60-preview.29`, published on 2026-10-13, 2026-10-06 and 2026-09-30 respectively. These names are the identifiers the site sorts and pages by, and they encode both a game version and a preview iteration.

Deployment follows the same tags. The Pages workflow runs for pushes to `main`, for version tags matching `v*`, for release changes, and for manual dispatches. That is four separate trigger paths, which gives contributors a quick way to publish a docs-only fix without a full release, and gives release automation a path that does not depend on branch state.

Because the naming carries an explicit preview counter, a reader looking for the protocol of a stable client has to read past several preview entries to find the release that matches the build in front of them. The `legacy_changelogs/` directory covers the other end of the range.

What this repository deliberately does not give you

This is documentation of a protocol, not an implementation of one. Nothing in the layout provides a client library, a packet encoder or decoder, a session handler, or a way to connect to a server. A reader looking for those will not find them here, and the README does not point to any such component.

There is also no stated compatibility guarantee. The repository description says the protocol is subject to change release over release, and the README repeats that the protocol can change between releases. Any tooling built against these schemas has to assume that field names, type identifiers and enum values may move between releases, and that assumption has to be handled on the reader's side.

The alternatives differ in approach rather than in brand. A generated schema site tells you the shape of a packet and where it sits in a version, which suits verification, tooling, and code generation. A hand-written client implementation embeds behavior and protocol assumptions in code, which suits connecting to a server but has to be maintained release by release. A third path is to consume the schemas programmatically instead of reading the pages, which is possible given the `json/` directory and the generation scripts, but the repository does not document a stable public API for doing it.

Licence, vendored generator, and the shape of upgrade work

The licence is reported as Other, meaning a custom licence that GitHub cannot classify, and the README points readers to the LICENSE file. That is the starting point for any use decision, and it needs to be read directly rather than inferred from the fact that the schemas describe a game protocol. Nothing here is legal advice.

The dependency list shows `@minecraft/api-docs-generator` installed as a local file from `vendor/minecraft-api-docs-generator-2.1.0.tgz`, alongside `astro`, `gray-matter`, `markdown-it`, `semver` and `tar`. Vendoring the generator means the site build does not depend on a package that could disappear from a registry, but it also means the version in use is fixed in the tarball unless someone updates it in the repository.

Upgrade work is therefore mostly version chasing. Each release tag can move schema details, and the person maintaining a consumer has to re-read the relevant release notes and re-check the generated pages. On the maintenance side, the repository is not archived and the last push was on 2026-10-13.

Editorial conclusion

Adopt this repository if you need the authoritative shape of Bedrock packets and enums and can live with a protocol that the project itself says changes between releases. Do not adopt it if you wanted a client implementation, a test harness, or stable semantics. Before anything else, verify that a release matching your target client version already exists in the generated history, and read the LICENSE file yourself, since GitHub classifies the licence as Other and this repository is not a legal opinion.

Frequently asked questions

Official sources

1. Issues
2. Mojang/bedrock-protocol-docs on GitHub
3. README
4. Releases