Minestom Entity Tags and Custom Data

Store and retrieve custom data on entities using the Tags system

java (17+) 2025-11-03 minestom entities tags nbt data

Description

Minestom’s Tags system allows you to attach custom data to entities, items, and blocks using NBT (Named Binary Tag) format. Tags are type-safe and efficient for storing custom properties and state.

Key Features

  • Type-safe: Strongly typed tag storage
  • Persistent: Data survives server restarts (if configured)
  • Efficient: Uses NBT format for serialization
  • Multiple types: String, Integer, Double, Boolean, Compound, etc.
  • Entity-specific: Tags are attached to specific entities

Common Use Cases

  • Storing custom entity properties
  • Tracking entity state
  • Persisting entity data
  • Custom metadata
  • Plugin-specific data storage

Code

RAW 
import net.minestom.server.entity.Entity;import net.minestom.server.tag.Tag;import net.minestom.server.tag.TagReadable;import net.minestom.server.tag.TagWritable;public class EntityTagUtils {        // String tag    private static final Tag<String> STRING_TAG = Tag.String("custom_string");        // Integer tag    private static final Tag<Integer> INT_TAG = Tag.Integer("custom_int");        // Double tag    private static final Tag<Double> DOUBLE_TAG = Tag.Double("custom_double");        // Boolean tag    private static final Tag<Boolean> BOOLEAN_TAG = Tag.Boolean("custom_boolean");        // Set string tag on entity    public static void setStringData(Entity entity, String value) {        if (entity instanceof TagWritable writable) {            writable.setTag(STRING_TAG, value);        }    }        // Get string tag from entity    public static String getStringData(Entity entity) {        if (entity instanceof TagReadable readable) {            return readable.getTag(STRING_TAG);        }        return null;    }        // Set integer tag    public static void setIntData(Entity entity, Integer value) {        if (entity instanceof TagWritable writable) {            writable.setTag(INT_TAG, value);        }    }        // Get integer tag    public static Integer getIntData(Entity entity) {        if (entity instanceof TagReadable readable) {            return readable.getTag(INT_TAG);        }        return null;    }        // Set double tag    public static void setDoubleData(Entity entity, Double value) {        if (entity instanceof TagWritable writable) {            writable.setTag(DOUBLE_TAG, value);        }    }        // Get double tag    public static Double getDoubleData(Entity entity) {        if (entity instanceof TagReadable readable) {            return readable.getTag(DOUBLE_TAG);        }        return null;    }        // Set boolean tag    public static void setBooleanData(Entity entity, Boolean value) {        if (entity instanceof TagWritable writable) {            writable.setTag(BOOLEAN_TAG, value);        }    }        // Get boolean tag    public static Boolean getBooleanData(Entity entity) {        if (entity instanceof TagReadable readable) {            return readable.getTag(BOOLEAN_TAG);        }        return null;    }        // Set multiple tags at once    public static void setEntityData(Entity entity, String stringValue, Integer intValue, Double doubleValue) {        if (entity instanceof TagWritable writable) {            writable.setTag(STRING_TAG, stringValue);            writable.setTag(INT_TAG, intValue);            writable.setTag(DOUBLE_TAG, doubleValue);        }    }        // Check if entity has tag    public static boolean hasTag(Entity entity, Tag<?> tag) {        if (entity instanceof TagReadable readable) {            return readable.hasTag(tag);        }        return false;    }        // Remove tag    public static void removeTag(Entity entity, Tag<?> tag) {        if (entity instanceof TagWritable writable) {            writable.removeTag(tag);        }    }}
RAW 
// Create tagsTag<String> playerNameTag = Tag.String("custom_player_name");Tag<Integer> levelTag = Tag.Integer("player_level");Tag<Double> balanceTag = Tag.Double("player_balance");Tag<Boolean> isVipTag = Tag.Boolean("is_vip");// Set tags on playerPlayer player = // ... get playerif (player instanceof TagWritable writable) {    writable.setTag(playerNameTag, "CustomName");    writable.setTag(levelTag, 50);    writable.setTag(balanceTag, 1000.0);    writable.setTag(isVipTag, true);}// Read tags from playerif (player instanceof TagReadable readable) {    String name = readable.getTag(playerNameTag);    Integer level = readable.getTag(levelTag);    Double balance = readable.getTag(balanceTag);    Boolean isVip = readable.getTag(isVipTag);        System.out.println("Player: " + name + ", Level: " + level + ", Balance: " + balance);}// Check if tag existsif (player instanceof TagReadable readable) {    if (readable.hasTag(levelTag)) {        System.out.println("Player has level tag");    }}// Remove tagif (player instanceof TagWritable writable) {    writable.removeTag(levelTag);}// Using with custom entity classpublic class CustomEntity extends EntityLiving {    private static final Tag<Integer> CUSTOM_DATA_TAG = Tag.Integer("custom_data");        public void setCustomData(int value) {        setTag(CUSTOM_DATA_TAG, value);    }        public int getCustomData() {        return getTag(CUSTOM_DATA_TAG);    }}

Comments

No comments yet. Be the first to comment!