Dynamic Properties

Dynamic properties allows developers can save and load their own custom properties within a Minecraft world.

This allows data to be saved directly into disk, specifically world's LevelDB, and these values can be retrived after the server stopped and started again next time.

Dynamic properties are tied to a behavior pack's header UUID. Since behavior packs cannot access other behavior packs' dynamic properties, when behavior pack's header UUID gets changed, the pack can no longer retrieve previous data.

Installation

Requires @minecraft/server@1.7.0 or above.

{
  "module_name": "@minecraft/server",
  "version": "1.7.0"
}

Usage

Set Property (World)

Sets a specified property to a value targeted to world.

Code:

Save a string property value:

import { world } from "@minecraft/server";
world.setDynamicProperty("key", "value");

Save a numeric property value:

import { world } from "@minecraft/server";
world.setDynamicProperty("key", 10);

Save a boolean property value:

import { world } from "@minecraft/server";
world.setDynamicProperty("key", true);

Save a Vector3 property value:

import { world } from "@minecraft/server";
world.setDynamicProperty("key", { x: 10, y: 10, z: 10 });

Preview (Structure):

DynamicProperties
└───<behavior_pack_header_uuid>
       key: value

Details (LevelDB Format):

Key	Value (NBT)
DynamicProperties	{ TAG_Compound("<behavior_pack_header_uuid>") { TAG_String("key"): value } }

Set Property (Entity)

Sets a specified property to a value targeted to a specific entity.

Code:

Get Player instance first:

import { world } from "@minecraft/server";

const player = world.getPlayers()[0];

Save a string property value:

player.setDynamicProperty("key", "value");

Save a numeric property value:

player.setDynamicProperty("key", 10);

Save a boolean property value:

player.setDynamicProperty("key", true);

Save a Vector3 property value:

player.setDynamicProperty("key", { x: 10, y: 10, z: 10 });

Preview (Structure):

Player
└───DynamicProperties
    └───<behavior_pack_header_uuid>
            key: value

Details (LevelDB Format):

Key	Value (NBT)
<Entity>	{ TAG_Compound("DynamicProperties") { TAG_Compound("<behavior_pack_header_uuid>") { TAG_String("key"): "value" } } }

Set Property (Item)

Sets a specified property to a value targeted to a specific item.

Code:

Get ItemStack instance first:

import { world } from "@minecraft/server";

const player = world.getPlayers()[0];
const inventory = player.getComponent("inventory");
const item = inventory.container.getItem(player.selectedSlotIndex);

Save a string property value:

item.setDynamicProperty("key", "value");

Save a numeric property value:

item.setDynamicProperty("key", 10);

Save a boolean property value:

item.setDynamicProperty("key", true);

Save a Vector3 property value:

item.setDynamicProperty("key", { x: 10, y: 10, z: 10 });

Important

Container::getItem() return an ItemStack instance which is not a "reference type". It's a full copy being copied so if you fetch and modify it, you need to "re-apply" it back to the game.

Another way to directly apply changes to the game is to make changes to ContainerSlot class, for example through methods like Container::getSlot() or EntityEquippableComponent::getEquipmentSlot().

Code:

Get ContainerSlot through Container class:

import { world } from "@minecraft/server";

const player = world.getPlayers()[0];
const inventory = player.getComponent("inventory");
const slot = inventory.container.getSlot(player.selectedSlotIndex);

Get ContainerSlot through EntityEquippableComponent class:

import { world, EquipmentSlot } from "@minecraft/server";

const player = world.getPlayers()[0];
const equippable = player.getComponent("equippable");
const slot = equippable.getEquipmentSlot(EquipmentSlot.Mainhand);

Preview: