# minecraft-data: the versioned data layer behind Minecraft tooling > minecraft-data is a language independent catalogue of everything a program needs to know about a particular version of Minecraft: block and item identifiers, recipes, entities, biomes, and a full description of the network protocol. It is the layer that bots, servers and minigame libraries in seven languages all build on, and the interesting parts are how the data gets extracted and how the old numeric identifiers survive the flattening. **PrismarineJS/minecraft-data** — Language independent module providing minecraft data for minecraft clients, servers and libraries. - Repository: https://github.com/PrismarineJS/minecraft-data - Website: https://prismarinejs.github.io/minecraft-data - Stars: 957 · Forks: 300 - Language: JavaScript - License: not declared - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/prismarinejs-minecraft-data ## One catalogue, many consumers minecraft-data is described as a language independent module providing Minecraft data for Minecraft clients, servers and libraries. That is the whole idea in one sentence, and it is a good one to understand before looking at the details. The problem it solves is that Minecraft's internal identifiers are a mess that changes with every release. A block has a numeric id in one version and a namespaced string id in another, and the mapping between the two is not derivable by a rule, it is data. A recipe is a structured object whose shape changes. The protocol is a set of packet definitions whose names and field layouts change. A bot library, a server implementation and a client all need the same facts, and each version of the game shifts them. So the repository is a set of directories, one per supported version, each holding that version's data in a documented form. The top level listing shows the four pieces of the project: the data directory, the doc directory, the schemas directory and the tools directory. The schemas are JSON schemas that describe the shape of each data file, which is what lets a consumer validate what it is given and lets the documentation be generated from the same source of truth. The consumers list in the README shows the scale of the dependency. Mineflayer, the Node.js bot library, uses biomes, blocks, entities, instruments, items, materials and recipes. node-minecraft-protocol, which does the protocol serialisation, uses the protocol data. flying-squid, a server library, uses biomes, blocks and materials. SpockBot in Python, PhaseBot in Java, McEx in Elixir, VoxelGamesLib for Java minigame servers, Phpcraft in PHP, and MineSharp in C# all sit on top of it. That list is the strongest evidence for the design. Seven languages, three use cases, one data set, and the only reason this is maintainable is that the data lives in a language neutral form. ## Which versions are covered, and how a new one arrives The version coverage is long and the README prints it in full, and it covers both editions. For the Java edition the list starts at 0.30c, the classic version, and runs through 1.7.10, the 1.8 series, 1.9 including the 15w40b snapshot and the 1.9.2 and 1.9.4 releases, 1.10 and 1.10.2, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16 including the 20w13b and 20w14a snapshots and the 1.16 releases, 1.17 and 1.17.1, 1.18, 1.19, 1.20, 1.21 and its point releases, and the newer numbering through 26.1. For Bedrock the list runs from 0.14 and 0.15 through 1.0, the 1.16.2xx series, 1.17, 1.18, 1.19, 1.20, 1.21 and the 1.26 point releases. What is interesting is that the list includes snapshots, the pre-release builds with names like 15w40b and 20w13b, and that both lists are followed in the source by HTML comment markers, NEXT PC and NEXT BEDROCK. Those markers are the seams where a new version is spliced in, and they are visible in the README because the README is generated from the same source of truth as the data. That is a small sign of a project that generates rather than hand-maintains. The consequence for a user is straightforward. If you need data for a version, it is either there or it is not, and the extraction pipeline is what decides. If your game is on a version the data does not cover yet, nothing built on this will work until the extraction catches up, which is why the next part of the README matters. ## What is actually in the data The data table is the catalogue, and a few entries are worth reading closely because they solve problems that are not obvious until you hit them. The straightforward ones are blocks, items, entities, biomes, enchantments, effects, the language codes with their English strings, instruments for the sounds blocks emit, map icons as used by crafted maps, materials with tool speed multipliers for each surface type, particles, recipes, windows and their characteristics, and the version list. Four entries carry more weight. Protocol is a complete description of the protocol, and the README points to the ProtoDef documentation for it. That is what makes the data actionable rather than descriptive: the protocol file is structured so that a protocol implementation can be generated from it, which is exactly what node-minecraft-protocol does. Protocol Versions is the whole list of protocol versions, which is what lets a client negotiate. Legacy is the mapping between the legacy 1.12 blocks and items identifiers and the post-flattening 1.13 and later ones. This is the entry that saves a project that has to talk to both, because the flattening renumbered and restructured a large part of the game, and the old numeric ids and the new namespaced ids are related by a table that nobody can compute. A server implementation that supports both editions needs this mapping, and having it in one place is worth the file on its own. Commands is a tree structure for the vanilla server commands, with some of the information needed to implement sub-parsers, which is a slightly different kind of data: it is a model of the command grammar rather than a list of game facts, and it exists so that a server can parse the commands a player types. Then there are the version-conditional ones. Features can be used to check whether a specific feature is available in the current Minecraft version, which the README says is usually only required for handling version-specific functionality. Sounds provides mappings between network sound id and sound name for the versions that use a sound id over the network, 1.9 and later. Foods lists each food with its id, saturation and food points. Skin data covers the Bedrock edition skin geometry and texture data for the Steve skin. Block collision shapes is one of the more unusual entries, and it is the kind of data that turns out to matter: knowing the exact shape of a block rather than a full cube is what lets a bot or a physics implementation decide whether it can walk into a space. ## Seven wrappers, and how a new language joins Because the data is language independent, each language needs something to read it, and those somethings are the wrappers. The table lists them. node-minecraft-data for Node.js provides everything. python-minecraft-data and minebase, both in Python, also provide everything. McData in Elixir provides the protocol. ProtocolGen in Java generates Java files from protocol.json so that a Java implementation can read and write Minecraft packets. mcdata in Go and minecraft-data-rs in Rust provide everything. The split between the wrappers is informative. Most of them expose the whole catalogue, which suggests the data is straightforward to load once you have a JSON parser. The Elixir one is protocol only, which suggests a narrower use. And ProtocolGen does something different from the rest, since it generates source code rather than serving data at run time, which is the right approach when you want compile-time types for packets. For a language that is not on the list, the README's advice is to create a new wrapper, and it links to a document for that, doc/make-a-new-wrapper.md. The threshold for a new wrapper is therefore low, and that is by design: the PrismarineJS organisation built a data core and let the ecosystem grow around it, and the wrappers in Rust, Go, Elixir and C# are all evidence that other people took that invitation. The JavaScript package at the root of this repository is the wrapper for Node.js, and the data itself is the JSON in the data directory. That separation is the point of the whole design, and it is why the wrappers can be written in any language with a JSON parser. ## The extraction pipeline, and where the data really comes from The data is not typed in by hand, and the README describes the machinery that produces it. For the Java edition, the recommended way to extract the data is documented in a file called add-data-new-version.md, and the pipeline is described as the minecraft-data-auto-updater calling minecraft-data-generator-server. Two separate projects, one that knows when something changed and one that knows how to extract data from the game. For Bedrock, there is a separate document, bedrock.md, with information on updating the data, and the same two projects do the work. There is also a list of projects that provide data, which shows the second source of truth. minecraft-wiki-extractor, in Node.js, extracts blocks, items, entities and recipes from the Minecraft wiki. mcdevs-wiki-extractor appears in the same list, also working from the wiki. So there are two inputs to the same catalogue. The game itself is the authority for things only the game knows, and the wiki is the authority for things the wiki documents well, such as recipes and item properties. Reconciling those two into one consistent set per version is the actual work, and it is the reason this project exists as a separate repository rather than as a set of scripts inside one client library. For a team adding support for a new Minecraft release, the process is therefore: run the auto-updater, which calls the generator server, which produces the data for that version, and then check the output against the wiki-derived extraction. The document for adding a new version is the entry point for that work, and it is the reason a new release eventually appears in the version list. ## Schemas, generated documentation and the projects that depend on it The schemas directory is the quiet part of the design and it is what makes the rest reliable. Each data file has a JSON schema describing its shape, and those schemas are used to validate the data and to generate the documentation. The README says the documentation is generated using the JSON schemas and docson, and it is hosted at prismarinejs.github.io/minecraft-data, the project homepage. The doc directory also carries the documentation that a generator cannot produce. There is doc/history.md, a textual description of the recipe format in doc/recipes.md, and the extraction and wrapper guides already mentioned. Looking at the dependency list from the perspective of an adopter, the pattern is consistent. A bot library needs the world data, a protocol library needs the protocol, a server implementation needs the blocks and items so that it can answer queries about them, and a minigame server needs the blocks and items so that it can place and check them. MineSharp in C# is the most comprehensive of the list, using the protocol, blocks, items, entities, biomes, recipes and enchantments. Two things follow from that. First, the data layer is a genuine alternative to reverse engineering the game yourself, in any language. Second, the consumers are projects that implement the game server or the player, and their existence is the strongest argument that the approach works across languages. The maintenance picture is a mixed one that is worth reading carefully. The repository is not archived and the last push was on 2026-10-13. The releases are frequent, with 3.117.0 on 2026-09-22, 3.116.0 on 2026-09-05 and 3.115.0 on 2026-08-31, so the data package is being republished as versions arrive, which is what a data project should do. But the repository's licence field is recorded as unknown and no licence is named in the visible README, while the data is by definition extracted from a commercial game and from a wiki. A project that ships game data has a rights question that a library that ships code does not, and the absence of a stated licence is something to resolve with the maintainers before you redistribute the data inside a product. ## Conclusion Adopt minecraft-data, through one of the wrappers, if you are writing anything that has to know Minecraft's identifiers or its protocol, because re-deriving that from the game is a project in itself and the extraction pipeline is maintained for you. It is the wrong tool if you need the game assets themselves, since this is metadata rather than textures or sounds, and the wrong tool if you need a licence you can point at, because the repository records no licence and the data is extracted from the game and the wiki. Before depending on it, pin the version of the data package you use and check the extraction document for the version you are adding, since a new Minecraft release needs a new data entry before anything else works. ## FAQ ### What is minecraft-data and who uses it? It is a language independent catalogue of Minecraft data for every supported version, providing blocks, items, recipes, entities, biomes, the protocol and more. It is used by bot libraries such as mineflayer and SpockBot, by server libraries such as flying-squid, and by projects in Java, Elixir, PHP, C# and Go. ### Which Minecraft versions does minecraft-data support? For the Java edition, from 0.30c classic through 1.7.10, the 1.8 to 1.21 series and their snapshots, up to 26.1. For Bedrock, from 0.14 and 0.15 through 1.0, the 1.16.2xx series, 1.17 to 1.21 and the 1.26 point releases. ### How do I use minecraft-data from a language other than JavaScript? Through a wrapper. The README lists node-minecraft-data for Node.js, python-minecraft-data and minebase for Python, McData for Elixir, ProtocolGen for Java, mcdata for Go and minecraft-data-rs for Rust, and advises creating a new wrapper for any other language using the guide it links. ### What is the Legacy data in minecraft-data for? It is the mapping between the legacy 1.12 blocks and items ids and the post-flattening 1.13 and later identifiers. The flattening renumbered and restructured a large part of the game, and the relation between the old and new identifiers is a table rather than a rule, so a project supporting both eras needs it. ### How is new version data added to minecraft-data? The README points to a document for adding a data for a new version. The pipeline is the minecraft-data-auto-updater calling minecraft-data-generator-server, with wiki-derived extraction from projects such as minecraft-wiki-extractor supplying blocks, items, entities and recipes. ## Sources - [Issues](https://github.com/PrismarineJS/minecraft-data/issues) - [PrismarineJS/minecraft-data on GitHub](https://github.com/PrismarineJS/minecraft-data) - [Project website](https://prismarinejs.github.io/minecraft-data) - [README](https://github.com/PrismarineJS/minecraft-data/blob/master/README.md) - [Releases](https://github.com/PrismarineJS/minecraft-data/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/prismarinejs-minecraft-data