Code Item Changes

Note

This is a technical article that may not be relevant to a large portion of users.

Code items are the items that represent literal code values, they are found in the Values ingot in dev mode and their format is changing.

Overview

The code item JSON format will receive changes that will be elaborated on in this page.

{
    "id": "num",
   "version": 1,
    "data": {
        "name": 1
    }
}
{
    "id": "snd",
   "version": 1,
   "mappingVersion": 0,
    "data": {
        "pitch": 1.0,
        "vol": 2.0,
       "sound": "player attack (critical)",
       "sound": "minecraft:entity.player.attack.crit",
    }
}

Versioning

Code items have always had the same format, and when new fields were added, backwards compatibility was achieved by making them optional.

This is no longer the case, code items now have a version field that is shared by all code items (i.e. global) which allows us to make changes without introducing internal ambiguity.

Sounds, Potions, and Particles

As part of our long-term effort to make DiamondFire, both internally and in code blocks, less reliant on the display names we give to sounds, potions, and particles these values will now identify their value by their Minecraft IDs.

Actions that take display names are being deprecated. However, these IDs are now easily accessible using auto-completion on /sound, /particle, and /potion get; these actions won’t work for newly added values.

Adding onto that, these values will now store a mappingVersion field, this field helps us update old IDs through proper versioning (e.g. in 1.21.6 entity.leashknot.place was renamed to item.lead.tied)

This, of course, relies on the new version field. Version 0 code items still store the display names of these values, whilst version 1 expects IDs.

Note

Our reasoning for this change is that display names are a fragile way of identifying values, we may make changes to them and code should not need to accomodate for that.

What’s next?

We’re still planning to make additional changes to particles to standardize their internal representation as well as moving the DF_NBT integer on serialized items out of the actual NBT, however these will come at a later date.

Additionally, we’re planning for the action dump to be slightly overhauled to not include empty fields as well as some potential restructuring. This overhaul will also include code-item and mapping version data and potential extra info such as the current DiamondFire patch and maybe even an endpoint? Stay tuned.