From 247718bb7493f50543b4c7692f11baae8e1acf03 Mon Sep 17 00:00:00 2001 From: Eclipse Date: Tue, 4 Aug 2026 10:46:49 +0000 Subject: [PATCH] Update custom-skulls page for JSON mappings --- wiki/geyser/custom-skulls.md | 139 ------------------------------- wiki/geyser/custom-skulls.mdx | 100 ++++++++++++++++++++++ wiki/geyser/custom-waypoints.mdx | 2 +- 3 files changed, 101 insertions(+), 140 deletions(-) delete mode 100644 wiki/geyser/custom-skulls.md create mode 100644 wiki/geyser/custom-skulls.mdx diff --git a/wiki/geyser/custom-skulls.md b/wiki/geyser/custom-skulls.md deleted file mode 100644 index 9c16ee6..0000000 --- a/wiki/geyser/custom-skulls.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Custom Skulls -description: Geyser allows mapping of custom skulls to custom blocks for use in inventories and on entities. ---- - -Unlike Java Edition, Bedrock does not have native support for custom skull items. As a result, any method to display custom skulls with Geyser is, to some extent, a workaround. Geyser has long supported in-world custom skulls via the spawning of player entities. This, however, does not allow for the use of custom skulls in inventories, nor does it allow them to be worn by entities. To resolve this, Geyser now allows for the pre-registration of custom skulls via a config file. Geyser will then use this config file to generate a custom resource pack on start that contains the geometry and textures for the pre-registered custom skulls. To the client, these skulls are blocks. Therefore, they can be held in player inventories. In additional, attachables are defined for each skull block so that it is displayed correctly when worn and held by entities. - -To setup custom skulls in geyser, you have to choose how you are going to register your blocks. The easiest is [using custom-skulls.yml](#custom-skullsyml), but you can also [use a Geyser extension](#geyser-extensions). - -## Enabling custom skulls {#enabling-custom-skulls} - -To enable custom skulls, you must set `gameplay.enable-custom-content` to `true` in the `config.yml` file. This will enable the generation of the custom resource pack and the translation of custom skulls to custom blocks. You can then add custom skulls to the `custom-skulls.yml` file. - -```yaml -# Whether to add any items and blocks which normally does not exist in Bedrock Edition. -# This should only need to be disabled if using a proxy that does not use the "transfer packet" style of server switching. -# If this is disabled, furnace minecart items will be mapped to hopper minecart items. -# Geyser's block, item, and skull mappings systems will also be disabled. -# This option requires a restart of Geyser in order to change its setting. -enable-custom-content: true -``` - -## custom-skulls.yml {#custom-skullsyml} - -The configuration file `custom-skulls.yml` is present in Geyser's configuration folder and is laid out as follows: - -```yml -# -------------------------------- -# Geyser Custom Skull Configuration Files -# -# This file is ignored with `add-custom-skull-blocks` disabled. -# See `config.yml` for the main set of configuration values -# -# Custom skulls with the player username, UUID, or texture specified in this file -# will be translated as custom blocks and be displayed in the inventory and on entities. -# -------------------------------- - -# Java player usernames -# Skins will be updated when Geyser starts and players will have to re-download -# the resource pack if any players had changed their skin. -player-usernames: - - GeyserMC - -# Java player UUIDs -# Skins will be updated when Geyser starts and players will have to re-download -# the resource pack if any players had changed their skin. -player-uuids: - - 8b8d8e8f-2759-47c6-acb5-5827de8a72b8 - -# The long string of characters found in the NBT of custom player heads -player-profiles: - - ewogICJ0aW1lc3RhbXAiIDogMTY1NzMyMjIzOTgzMywKICAicHJvZmlsZUlkIiA6ICJjZGRiZTUyMGQwNDM0YThiYTFjYzlmYzkyZmRlMmJjZiIsCiAgInByb2ZpbGVOYW1lIiA6ICJBbWJlcmljaHUiLAogICJ0ZXh0dXJlcyIgOiB7CiAgICAiU0tJTiIgOiB7CiAgICAgICJ1cmwiIDogImh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTkwNzkwYzU3ZTE4MWVkMTNhZGVkMTRjNDdlZTJmN2M4ZGUzNTMzZTAxN2JhOTU3YWY3YmRmOWRmMWJkZTk0ZiIsCiAgICAgICJtZXRhZGF0YSIgOiB7CiAgICAgICAgIm1vZGVsIiA6ICJzbGltIgogICAgICB9CiAgICB9CiAgfQp9 - -# The hash of the skin on Minecraft's skin server -skin-hashes: - - a90790c57e181ed13aded14c47ee2f7c8de3533e017ba957af7bdf9df1bde94f -``` - -To add a skull, you need to choose any of the four methods, and add a new entry. The following sections will explain each method: - -### Player usernames {#player-usernames} - -Skulls can be registered in this section via player usernames. These will be updated when Geyser starts. As a result, they may change if the player's username or skin changes. - -### Player UUIDs {#player-uuids} - -Skulls can be registered in this section via player UUIDs. These will be updated when Geyser starts. As a result, they may change if skin changes. - -### Player profiles {#player-profiles} - -Skulls can be registered in this section via the texture string found in the NBT of custom player heads. Unless the value is changed manually, these will not be updated when Geyser starts. As a result, they will not change if the player's username or skin changes. The data is simply base64 encoded JSON. For instance, the example given in the config decodes as follows: - -```json -{ - "timestamp" : 1657322239833, - "profileId" : "cddbe520d0434a8ba1cc9fc92fde2bcf", - "profileName" : "Amberichu", - "textures" : { - "SKIN" : { - "url" : "http://textures.minecraft.net/texture/a90790c57e181ed13aded14c47ee2f7c8de3533e017ba957af7bdf9df1bde94f", - "metadata" : { - "model" : "slim" - } - } - } -} -``` - -If on a paper server, this data can be obtained for a skull by holding the item in hand, and running the command `/paper dumpitem`. This will output the NBT data of the item to chat and console. The texture string is found in the `SkullOwner` tag, under the `Properties` tag, under the `textures` tag, under the `Value` tag. For example: - -```log -[05:58:07 INFO]: .KastleFirefox issued server command: /paper dumpitem -[05:58:07 INFO]: minecraft:player_head{display: {Name: '{"text":"Test"}'}, SkullOwner: {Properties: {textures: [{Value: "ewogICJ0aW1lc3RhbXAiIDogMTY1NzMyMjIzOTgzMywKICAicHJvZmlsZUlkIiA6ICJjZGRiZTUyMGQwNDM0YThiYTFjYzlmYzkyZmRlMmJjZiIsCiAgInByb2ZpbGVOYW1lIiA6ICJkYXZjaG9vIiwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlL2E5MDc5MGM1N2UxODFlZDEzYWRlZDE0YzQ3ZWUyZjdjOGRlMzUzM2UwMTdiYTk1N2FmN2JkZjlkZjFiZGU5NGYiLAogICAgICAibWV0YWRhdGEiIDogewogICAgICAgICJtb2RlbCIgOiAic2xpbSIKICAgICAgfQogICAgfQogIH0KfQ"}]}, Id: [I; -229048314, -553040501, -1407961158, 465313087]}} -``` - -### Skin Hashes {#skin-hashes} - -Skulls can be registered in this section via the hash of the skin on Minecraft's skin server. This is found at the end of the URL. For example, in the URL `http://textures.minecraft.net/texture/a90790c57e181ed13aded14c47ee2f7c8de3533e017ba957af7bdf9df1bde94f` the hash is `a90790c57e181ed13aded14c47ee2f7c8de3533e017ba957af7bdf9df1bde94f`.Unless the value is changed manually, these will not be updated when Geyser starts. As a result, they will not change if the player's username or skin changes. - -This can be obtained by decoding the base64 data obtained from a player profile. - -## Geyser extensions {#geyser-extensions} - -In this example, we will register a custom skull from a player profile. We will use the player profile from the example above. - -First, create a class that implements Geyser's Extension class: - -```java -public class RegisterCustomSkull implements Extension { - //... -} -``` - -Next, create a method to register your blocks in the `GeyserDefineCustomSkullsEvent`: - -```java -public class RegisterCustomSkull implements Extension { - @Subscribe - public void onDefineCustomSkulls(GeyserDefineCustomSkullsEvent event) { - //... - } -} -``` - -Finally, register your skull in the event. Use the enum SkullTextureType to specify that the value being passed is a player profile: - -```java -public class RegisterCustomSkull implements Extension { - @Subscribe - public void onDefineCustomSkulls(GeyserDefineCustomSkullsEvent event) { - String profile = "ewogICJ0aW1lc3RhbXAiIDogMTY1NzMyMjIzOTgzMywKICAicHJvZmlsZUlkIiA6ICJjZGRiZTUyMGQwNDM0YThiYTFjYzlmYzkyZmRlMmJjZiIsCiAgInByb2ZpbGVOYW1lIiA6ICJkYXZjaG9vIiwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlL2E5MDc5MGM1N2UxODFlZDEzYWRlZDE0YzQ3ZWUyZjdjOGRlMzUzM2UwMTdiYTk1N2FmN2JkZjlkZjFiZGU5NGYiLAogICAgICAibWV0YWRhdGEiIDogewogICAgICAgICJtb2RlbCIgOiAic2xpbSIKICAgICAgfQogICAgfQogIH0KfQ" - event.register(profile, SkullTextureType.PROFILE); - } -} -``` - -## Scraping custom skulls from a world {#scraping-custom-skulls-from-a-world} - -Custom skulls can be extracted from an existing world for easy implementation via mappings or API using the tool [HeadExtractor](https://github.com/davchoo/HeadExtractor) made by Amberichu. See the linked repository for usage instructions. diff --git a/wiki/geyser/custom-skulls.mdx b/wiki/geyser/custom-skulls.mdx new file mode 100644 index 0000000..ec3b456 --- /dev/null +++ b/wiki/geyser/custom-skulls.mdx @@ -0,0 +1,100 @@ +--- +title: Custom Skulls +description: Geyser allows mapping of custom skulls to custom blocks for use in inventories and on entities. +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Unlike Minecraft: Java Edition, Bedrock Edition does not have native support for custom skull items. +As a result, any method to display custom skulls with Geyser is, to some extent, a workaround. +Geyser has long supported in-world custom skulls via the spawning of player entities. +This, however, does not allow for the use of custom skulls in inventories, nor does it allow them to be worn by entities. + +To resolve this, Geyser allows for the pre-registration of custom skulls via custom JSON mappings +or the Geyser API. Geyser will then generate a custom resource pack on start that contains the geometry and textures +for the pre-registered custom skulls. + +To the client, these skulls are blocks. Therefore, they can be held in player inventories. +In addition, attachables are defined for each skull block, so that it is displayed correctly when worn and held by entities. + +To set up custom skulls in geyser, you have to choose how you are going to register them. +The easiest is using custom JSON mappings, but you can also use the Geyser API, for example using a Geyser extension. + +:::warning +Whilst Geyser tries its best to convert custom skulls automatically, it does not generate custom skull mappings. +However, you can use automatic tools such as [Rainbow](/wiki/other/rainbow/) to make converting content simpler. +::: + +## Registering custom skulls + +Custom skulls can be registered through 4 methods: + +- By player username. These will be updated when Geyser starts. As a result, they may change if the player's username or skin changes. + - Use this option for skulls marked `Dynamic` on Java Edition. +- By player UUID. These will also be updated when Geyser starts. As a result, they may change if skin changes. + - Use this option for skulls marked `Dynamic` on Java Edition. +- By the base-64 encoded `textures` property of game profiles. These will only ever change when the registered value itself changes, as they hold a static reference to a skin. + - You can get these values from a custom skull in your hand using the following command in Minecraft: Java Edition: `/data get entity @s SelectedItem.components."minecraft:profile".properties[{name:"textures"}].value`. + - Please note that this command has only been tested on Java Edition 26.2. If the command fails, that could mean your custom skull is a dynamic one, and you should register a UUID or username instead. +- By skin texture hash. These will also only ever change when the value itself changes. They are a static reference to a skin texture over at `https://textures.minecraft.net/texture/`. + - You generally don't need to use this option, as it is often easier to just use the base-64 profile found in a skull. + - If you want to publish an extension or custom skull mappings however, this option can be useful to hide player names/UUIDs, if you wish to do so. + + + + JSON mappings have to specify the `format_version` set to `1`, and list all custom skulls under the + `skulls` key. This key holds an object in which Java Edition usernames, user UUIDs, profile hashes or skin texture + hashes can be specified. + + For example, take the following `custom_skulls.json` file: + ```json + { + "format_version": 1, + "skulls": { + "username": [ + "GeyserMC" + ], + "uuid": [ + "8b8d8e8f-2759-47c6-acb5-5827de8a72b8" + ], + "profile": [ + "ewogICJ0aW1lc3RhbXAiIDogMTY1NzMyMjIzOTgzMywKICAicHJvZmlsZUlkIiA6ICJjZGRiZTUyMGQwNDM0YThiYTFjYzlmYzkyZmRlMmJjZiIsCiAgInByb2ZpbGVOYW1lIiA6ICJBbWJlcmljaHUiLAogICJ0ZXh0dXJlcyIgOiB7CiAgICAiU0tJTiIgOiB7CiAgICAgICJ1cmwiIDogImh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTkwNzkwYzU3ZTE4MWVkMTNhZGVkMTRjNDdlZTJmN2M4ZGUzNTMzZTAxN2JhOTU3YWY3YmRmOWRmMWJkZTk0ZiIsCiAgICAgICJtZXRhZGF0YSIgOiB7CiAgICAgICAgIm1vZGVsIiA6ICJzbGltIgogICAgICB9CiAgICB9CiAgfQp9" + ], + "skin_hash": [ + "a90790c57e181ed13aded14c47ee2f7c8de3533e017ba957af7bdf9df1bde94f" + ] + } + } + ``` + + These mappings specify skulls for the `GeyserMC` user, the `Camotoy` user (using UUID `8b8d8e8f-2759-47c6-acb5-5827de8a72b8`), + and [this](http://textures.minecraft.net/texture/a90790c57e181ed13aded14c47ee2f7c8de3533e017ba957af7bdf9df1bde94f) skin (through the base-64 `profile` entry and the `skin_hash` entry). + + + Custom skulls are registered at startup through the `GeyserDefineCustomSkullsEvent`. All skulls are registered + through the `register(String texture, SkullTextureType type)` method, in which the `type` parameter defines the + type of the string registered, which is one of: + + - `SkullTextureType.USERNAME` for usernames. + - `SkullTextureType.UUID` for UUIDs. + - `SkullTextureType.PROFILE` for base-64 encoded `textures` properties of game profiles. + - `SkullTextureType.SKIN_HASH` for skin texture hashes. + + As an example: + + ```java + @Subscribe + public void onDefineCustomSkulls(GeyserDefineCustomSkullsEvent event) { + event.register("GeyserMC", SkullTextureType.USERNAME); + event.register("8b8d8e8f-2759-47c6-acb5-5827de8a72b8", SkullTextureType.UUID); + event.register("ewogICJ0aW1lc3RhbXAiIDogMTY1NzMyMjIzOTgzMywKICAicHJvZmlsZUlkIiA6ICJjZGRiZTUyMGQwNDM0YThiYTFjYzlmYzkyZmRlMmJjZiIsCiAgInByb2ZpbGVOYW1lIiA6ICJBbWJlcmljaHUiLAogICJ0ZXh0dXJlcyIgOiB7CiAgICAiU0tJTiIgOiB7CiAgICAgICJ1cmwiIDogImh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTkwNzkwYzU3ZTE4MWVkMTNhZGVkMTRjNDdlZTJmN2M4ZGUzNTMzZTAxN2JhOTU3YWY3YmRmOWRmMWJkZTk0ZiIsCiAgICAgICJtZXRhZGF0YSIgOiB7CiAgICAgICAgIm1vZGVsIiA6ICJzbGltIgogICAgICB9CiAgICB9CiAgfQp9", SkullTextureType.PROFILE); + event.register("a90790c57e181ed13aded14c47ee2f7c8de3533e017ba957af7bdf9df1bde94f", SkullTextureType.SKIN_HASH); + } + ``` + + This example specifies skulls for the `GeyserMC` user, the `Camotoy` user (using UUID `8b8d8e8f-2759-47c6-acb5-5827de8a72b8`), + and [this](http://textures.minecraft.net/texture/a90790c57e181ed13aded14c47ee2f7c8de3533e017ba957af7bdf9df1bde94f) skin (through the base-64 `PROFILE` entry and the `SKIN_HASH` entry). + + + diff --git a/wiki/geyser/custom-waypoints.mdx b/wiki/geyser/custom-waypoints.mdx index cb27e85..5935723 100644 --- a/wiki/geyser/custom-waypoints.mdx +++ b/wiki/geyser/custom-waypoints.mdx @@ -26,7 +26,7 @@ Java Edition resource packs. :::warning As with custom blocks and items, Geyser does not convert resource packs from Java Edition, and also does not generate -custom waypoint mappings automatically. However, [Rainbow](/wiki/other/rainbow/) is planning +custom waypoint mappings automatically. However, [Rainbow](/wiki/other/rainbow/) has support for these conversions. :::