Modifying an Entity

Sure, spawning a regular-old entity is nice and all, but there has to be something more interesting than that? This is where DataManipulators come into play. An Entity is a DataHolder, which means that our Entity can hold data. More on DataHolders can be found in the data documentation.

DataManipulators that apply to Entitys are things such as FoodData or HealthData. A list of applicable DataManipulators can be found at org.spongepowered.api.data.manipulator.mutable and org.spongepowered.api.data.manipulator.mutable.entity. Note that not all DataManipulators found there may apply to all entities.

Entity Type

Before we can jump behind the wheel with our Entity, we should check what type of Entity it is, as we may receive an Entity we didn’t create and thus, do not know its type. Doing this is a simple equality check. Here is an example of checking if our Entity is a creeper:

import org.spongepowered.api.entity.Entity;
import org.spongepowered.api.entity.EntityTypes;

public boolean isCreeper(Entity entity) {
    return entity.getType().equals(EntityTypes.CREEPER);
}

Entity Data Manipulators

Now that we are certain that our Entity is a creeper, we can apply creeper specific DataManipulators to it. For example, ExplosionRadiusData is a DataManipulator that creepers can have, but not all Entitys. An example of changing an Entitys explosive radius to 50 can be seen below:

import org.spongepowered.api.data.manipulator.mutable.entity.ExplosiveRadiusData;

public void explosionRadius50(Entity creeper) {
    ExplosionRadiusData radiusData = creeper.get(ExplosionRadiusData.class).get();
    creeper.offer(radiusData.explosionRadius().setTo(50));
}

This will get the ExplosiveRadiusData of our Entity for our use. We then use that data to set the explosive radius of our creeper to 50. We then have to offer the data back to the creeper, as the data we received from our Entity is only a copy of the live data.

Perhaps we want to give our Entity a name to customize it a bit! This would be done by using DisplayNameData. An example of this in action can be seen below:

import org.spongepowered.api.data.manipulator.mutable.DisplayNameData;
import org.spongepowered.api.text.Text;
import org.spongepowered.api.text.format.TextColors;

public void setDisplayName(Entity creeper) {
    DisplayNameData displayData = creeper.get(DisplayNameData.class).get();
    creeper.offer(displayData.displayName().set(Text.of(TextColors.DARK_AQUA,
                                                          "Inscrutable")));
}

Another, shorter way to do this is by just using Keys on our Entity instead of using DataManipulators. This would be done like so:

import org.spongepowered.api.data.key.Keys;

public void explosionRadius50(Entity creeper) {
    creeper.offer(Keys.EXPLOSION_RADIUS, Optional.of(50));
    creeper.offer(Keys.DISPLAY_NAME, Text.of(TextColors.DARK_AQUA, "Inscrutable"));
}

This would neaten our code and is easier to perform. See the data documentation on the specific benefits of using either DataManipulators or just Keys.