Skip to content

Add custom skull JSON mappings and deprecate custom-skulls.yml file#6481

Open
eclipseisoffline wants to merge 3 commits into
GeyserMC:masterfrom
eclipseisoffline:custom-skull-mappings
Open

Add custom skull JSON mappings and deprecate custom-skulls.yml file#6481
eclipseisoffline wants to merge 3 commits into
GeyserMC:masterfrom
eclipseisoffline:custom-skull-mappings

Conversation

@eclipseisoffline

@eclipseisoffline eclipseisoffline commented Jun 26, 2026

Copy link
Copy Markdown
Member

This PR adds a new JSON custom mappings type, skulls, which functions exactly like the custom-skulls.yml file, but in JSON mappings form, which makes it easier for converters like Rainbow to automatically generate custom skull mappings without conflicting with each other.

Custom skull mappings look like this:

{
  "format_version": 1,
  "skulls": {
    "username": [
      "Steve"
    ],
    "uuid": [
      "f84c6a79-0a4e-45e0-879b-cd49ebd4c4e2"
    ],
    "profile": [
      "ewogICJ0aW1lc3RhbXAiIDogMTc4MjQ2MjA4MzQ2NiwKICAicHJvZmlsZUlkIiA6ICI4NTNjODBlZjNjMzc0OWZkYWE0OTkzOGI2NzRhZGFlNiIsCiAgInByb2ZpbGVOYW1lIiA6ICJqZWJfIiwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzdmZDliYTQyYTdjODFlZWVhMjJmMTUyNDI3MWFlODVhOGUwNDVjZTBhZjVhNmFlMTZjNjQwNmFlOTE3ZTY4YjUiCiAgICB9LAogICAgIkNBUEUiIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzllNTA3YWZjNTYzNTk5NzhhM2ViM2UzMjM2NzA0MmI4NTNjZGRkMDk5NWQxN2QwZGE5OTU2NjI5MTNmYjAwZjciCiAgICB9CiAgfQp9"
    ],
    "skin_hash": [
      "50c410fad8d9d8825ad56b0e443e2777a6b46bfa20dacd1d2f55edc71fbeb06d"
    ]
  }
}

Texture strings may not be empty. When an unknown texture type is read, an appropriate error is thrown:

While reading key "base64_skin_png" in skull mappings: unknown element in enum SkullTextureType, must be one of [username, uuid, profile, skin_hash] (node was "base64_skin_png")

The custom-skulls.yml config file has turned legacy and is deprecated. Geyser will automatically attempt to migrate it to a JSON skull mappings file upon boot.

@eclipseisoffline eclipseisoffline changed the title Add custom skull JSON mappings Add custom skull JSON mappings and deprecate custom-skulls.yml file Jun 26, 2026
return paths
.filter(child -> child.toString().endsWith(".json"))
.toArray(Path[]::new);
} catch (IOException e) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably worth logging a message here if one exists?


Gson gson = new GsonBuilder().setPrettyPrinting().create();
MappingsConfigReader.getCustomMappingsDirectoryAndEnsureItExists().ifPresentOrElse(mappingsDirectory -> {
Path destination = mappingsDirectory.resolve("migrated-custom-skulls.yml.json");

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

errrrrrr this looks a bit funny; why not drop the .yml?

@onebeastchris onebeastchris added the PR: Feature When a PR implements a new feature label Jul 10, 2026
@onebeastchris
onebeastchris deleted the branch GeyserMC:master July 12, 2026 12:40
@onebeastchris onebeastchris reopened this Jul 12, 2026
@onebeastchris
onebeastchris changed the base branch from feature/26.2 to master July 12, 2026 12:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

PR: Feature When a PR implements a new feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants