[Tutorial] Metadata - What it is and how to use it

Not many people on the Bukkit Forums, especially in PD where I spend the majority of my time on, are aware of metadata in the Bukkit API. This thread will cover what it is and various uses of it.

So what is Metadata?

Metadata is basically a concept related to several classes in the Bukkit API whose sole purpose is to provide plugin-specific data to Minecraft-related concepts. So, you can apply metadata values, which are like tags, on various Minecraft concepts that you can check for anywhere else in your plugin. That's very neat and organized and is a lot more efficient than other approaches to various tasks.

Is everything Metadatable?


No, not everything can be attached with a metadata tag. Because we're talking about Minecraft concepts here, players, blocks, and other entities are usually what we see as being metadatable (can be applied with metadata).

How is Metadata used?

Let's say we want to spawn an entity and set it's owner to a player. I do not want to use any of that NMS or Reflection crap (I'm not saying it's bad to use it, but it is complicated), so I'm stuck. Right? Wrong. You can add metadata to the entity and then check for it later to see if that entity is owned by a player. For this code example, I'm going to use a zombie.

Code:java

package com.valygard.aohruthless.metadatatutorial;
 
import org.bukkit.Bukkit;
import org.bukkit.entity.EntityType;
import org.bukkit.entity.Player;
import org.bukkit.entity.Zombie;
import org.bukkit.metadata.FixedMetadataValue;
 
/**
* To put some context into it, I use metadata in relation to zombies in my King
* of the Hill plugin. This has saved me lots of time and code from using NMS /
* Reflection where it was unnecessary.
*
* @author Anand
*
*/
public class MetadataTutorial {
 
    /**
    * This static method will spawn a zombie on the player and add metadata.
    * Note: Adding metadata does not make the zombie stop attacking the player,
    * you will need to listen for that in an EntityTargetEvent.
    *
    * @param plugin
    *            this is your main class. Replace "MainClass" with the class
    *            that extends JavaPlugin.
    * @param p
    *            this is the player we want to make the owner of the zombie.
    */
    public static void spawnZombie(MainClass plugin, Player p) {
        Zombie z = (Zombie) p.getWorld().spawnEntity(p.getLocation(),
                EntityType.ZOMBIE);
 
        /*
        * Setting the metadata.
        *
        * LivingEntity#setMetadata(String s, MetadataValue mv); The string is
        * the metadata tag that we will use to get the zombie anywhere else in
        * the plugin.
        *
        * There are two types of metadata: LazyMetadataValues, and
        * FixedMetadataValues which extend lazy ones. We will be working with
        * FixedMetadataValues.
        *
        * A FixedMetadataValue is, well, fixed. It is unchanging and therefore
        * very reliable.
        *
        * You will need to call a new FixedMetadataValue, which requires a
        * plugin argument and an arbitrary string. This string does not matter
        * and you can name it whatever you want. I recommend that your plugin
        * directly points your main class but Plugin, and JavaPlugin variable
        * types also work.
        */
        z.setMetadata(p.getName(), new FixedMetadataValue(plugin, "yes!"));
    }
 
    /**
    * Metadata is useless unless we can check if the zombie has metadata to
    * begin with.
    *
    * @param z
    *            the zombie to check
    * @return the player, or null if none was found online.
    */
    public static Player getPlayerWithZombie(Zombie z) {
        for (Player p : Bukkit.getOnlinePlayers()) {
            /*
            * Remember how we set metadata. We had a string argument, and a
            * metadata value. If the zombie has a metadata cache with this
            * string value, we have a match.
            *
            * So right away with a few lines of code we are able to retrieve a
            * player who the zombie belongs to.
            */
            if (z.hasMetadata(p.getName())) {
                return p;
            }
        }
        return null;
    }
 
    /**
    * Maybe we want to remove the player as a zombie owner. We can do that
    * because the Metadata API allows us to remove metadata with just one line
    * of code.
    *
    * @param z
    *            the zombie who has the metadata to be removed.
    * @param owner
    *            the player whose name is the metadata.
    * @param plugin
    *            we need a plugin argument to remove metadata.
    */
    public static void setOwnerless(Zombie z, Player owner, MainClass plugin) {
        if (z.hasMetadata(owner.getName())) {
            /*
            * Remember that string argument? We remove a zombie's metadata
            * based on this string argument, so we don't accidentally avoid all
            * metadata tags from other plugins or even elsewhere in this
            * plugin. (Yes! The plot thickens: You can have multiple metadata
            * tags)
            *
            * We also need the plugin argument from which we set metadata.
            */
            z.removeMetadata(owner.getName(), plugin);
        }
    }
 
}
 

This page is still a work in progress as I get time to finish it to it's fullest!

Reserved for further use.

EDIT by Moderator: merged posts, please use the edit button instead of double posting.

 

AoH_Ruthless
Suggestion: Include a tutorial for grabbing the Object you've put into the FixedMetadataValue. While Metadata is nice to work with this way, its much more powerful with this. Say, you could have your FixedMetadataValue's key (first arguement in LivingEntity#setMetadata()) as the Player's name, but what if you had it as a constant key defined by your plugin (like Owner), then you could attach more then just a Player name and access this without having to loop through the Players to check for that key. This allows for much more, such as making the Zombies owner something other then a Player (like, another Entity that can represent an opposing "Boss Entity")

For example, in my plugin MetadataTP, it attaches a TeleportRequest to a Player, it uses a constant key (while I may have not defined this in the best way, it gets a point across), allowing me to freely grab/set the Metadata for later use without the need for a 'Player name', and it also allows me to store more then one thing within that Metadata.

PS: If you haven't noticed, I love the Metadata API and wish everyone knew about it and used it.

Edit: My plugin's source doesn't show a 'safe' way of actually getting this Object, I use unchecked casting and grab the MetadataValue from its Collection without actually checking its owning plugin, I expect the OP to show a safe way of getting it

 

xTigerRebornx
I will be sure to incorporate this. In fact, I actually made this tutorial both at my chagrin at the lack of Metadata tutorials and "stalking" your MetadataTP plugin page, in which your vision is that more people are aware of the cool things that can be done with Metadata. So I took it upon myself to make this tutorial

 

AoH_Ruthless Good to hear you'll add it, be sure to read the edit I added to that post, it gives a brief explanation of the correct way to get the Object, as my way was just for ease-of-access (since I didn't design this plugin for a production server and I doubt that there will be a plugin other then mine that uses the key that is hardcoded into my plugin)
If you ever need help, or would like me to contribute, feel free to ask, as I'd love to contribute to this

EDIT: I may just create my own 'tutorial' for this, and explain other things and cover more ground