Java Edition protocol/Registries

Registries are repositories of data that contain entries pertaining to certain aspects of the game, such as the world, the player, among others. Each registry enumerates entries of a certain type, such as minecraft:block or minecraft:enchantment, assigning each entry a namespaced identifier, a numeric ID, and tags.

The contents of built-in registries are fixed for a given protocol version. These registries can only be changed through modding. Data-driven registries on the other hand can be modified through data packs. Some data-driven registries are only used by the server, while other synchronized registries are sent over the network when a player connects, and used by both the client and the server. This ability for the server to send customized registries to the client was introduced in 1.16.3, and allows for a great deal of customization over certain features of the game.

Of these, synchronized registries demand the most consideration from a protocol implementer. Supporting built-in registries properly is also important, as their contents, and consequently IDs, are liable to change between versions.

Built-in registries

These registries are defined directly in Minecraft's code, and can only be changed though modding. The client and server implicitly agree on which numeric IDs correspond to which entries. Unlike pre-flattening block and item IDs, these IDs can and often will change between versions.

For versions 1.14 and above the mapping from names to IDs can be obtained from the built-in data generators.

List of built-in registries

This list only includes built-in registries that are used directly in the protocol, including ones that are only referenced in Update Tags, but excluding those that are only referenced in registry data NBT.

Synchronized registries

The server sends these registries to the client via Registry Data packets during the configuration phase, one packet for each registry.

The ordering of the entries in the Entries array defines the numeric IDs that they will be assigned to, starting from 0 and counting upwards. It is essential to maintain consistency between server and client, since many parts of the protocol reference these entries by their ID. The client will disconnect upon receiving a reference to a non-existing entry.

The NBT data of registry entries has the same structure as their definitions in data packs, but represented in NBT instead of JSON. The format for each registry is defined in the list of registries below.

Obtaining vanilla registry data

The default contents of data-driven registries are defined as JSON in the default data pack, which is located inside both client.jar and server.jar under data/. These files can be extracted using any ZIP extraction utility. Note however that since 1.18 the server.jar (but not client.jar) distributed by Mojang is wrapped inside a bundler, and extracting the data pack requires first extracting the inner server.jar located at META-INF/versions/*/server-*.jar from the outer server.jar.

Alternatively, the data is available as a single JSON file for the following versions:

• 1.21
• 1.20.6
• 1.20.2
• 1.20.1
• 1.19.2
• 1.19

Known packs negotiation

In order to save bandwidth, the client and server can negotiate which data packs are known by both peers, and avoid sending NBT sourced from those packs over the network. In practice the vanilla client and server as of 1.21.8 only recognize one data pack, minecraft:core, which contains the default definitions. Data from custom data packs is always sent over the network.

1. S→C: Clientbound Known Packs (with all data packs known by the server)
2. C→S: Serverbound Known Packs (with the subset of data packs also known by the client)
3. Server computes the mutually supported data packs
4. S→C: Multiple Registry Data (for each registry, containing all entries, but excluding mutually known NBT)
5. S→C: Update Tags
6. Client accumulates registry and tag data for later resolution
7. S→C: Finish Configuration
8. Client resolves registry and tag data, loading data from packs when requested, and detecting unbound references to entries and tags

When resolving an entry from a Registry Data packet, the client will always use the NBT data specified in the packet if it is present. Otherwise it will look for the data in the selected known packs. Tag data is never sourced from known packs, and must always be sent by the server in full.

If an entry is not mentioned in a Registry Data packet, it will not exist in the game session, even if it exists in one of the known packs. All entries that will be used in the session must be listed in Registry Data packets; only the NBT part can be omitted.

When multiple known packs are selected, the client will combine them the same way resource and data packs are normally combined. The packs are listed in Clientbound Known Packs from the bottom of the stack to the top, so earlier packs are overridden by later ones.

A custom server implementation may choose to skip sending Clientbound Known Packs, in which case all NBT data must be present in the Registry Data packets, or to require that the client knows about minecraft:core, in which case no NBT needs to be sent. Similarly a custom client may respond with an empty Serverbound Known Packs packet, and require the server to send all registry NBT. All of these incomplete implementations are compatible with the vanilla implementation, but interoperability between them will be limited.

List of synchronized registries

Damage type requirements

The following damage types must be defined for the vanilla client to accept a Login (play) packet:

Dimension type requirements

The minecraft:dimension_type registry is technically optional, but due to the required Dimension Type field, it is impossible to send a valid Login (play) packet unless the registry has at least one entry.

Biome requirements

A biome named minecraft:plains must be defined for the vanilla client to accept a Login (play) packet. It is used as the default for unloaded chunks.

This article is licensed under a Creative Commons Attribution-ShareAlike 3.0 license.

 

This article has been imported from wiki.vg or is a derivative of such a page. Thus, the wiki's usual license does not apply.
Derivative works must be licensed using the same or a compatible license.