-
Notifications
You must be signed in to change notification settings - Fork 1
EntityBuilder example
Selena Rose Hammond edited this page Aug 22, 2025
·
6 revisions
The EntityBuilder class is used to make creating custom entities more streamline. The EntityBuilder class can be serialized and deserialized using the ConfigLoader meaning if you have it stored in a config class it will be saved to the config and loaded correctly.
Simple example usage
EntityBuilder entityBuilder = new EntityBuilder(EntityType.DROWNED)
.setDisplayName("<GRADIENT:FFFFFF>Custom Drowned</GRADIENT:000000>")
.setMovementSpeed(5);// Creates a new instance with an entity type set
EntityBuilder testEntity = new EntityBuilder(EntityType.DROWNED)
// Sets the display name of the entity supports both MiniMessage and IridiumColorApi colors
.setDisplayName("<red>Test</red> <SOLID:32a852>Entity")
// Add potion effects, can add multiple with addPotionEffect(PotionEffect ... effects)
.addPotionEffect(new PotionEffect(PotionEffectType.GLOWING, 120, 1))
// Set the potion effects List (Will create a new instance of the list)
.setPotionEffects(List.of(new PotionEffect(PotionEffectType.GLOWING, 120, 1)))
// Set the helmet for the entity, Can take ItemStack or ItemBuilder (stored as ItemBuilder)
.setHelmet(new ItemStack(Material.PLAYER_HEAD))
// Set the chestplate for the entity, Can take ItemStack or ItemBuilder (stored as ItemBuilder)
.setChestplate(new ItemStack(Material.DIAMOND_CHESTPLATE))
// Set the leggings for the entity, Can take ItemStack or ItemBuilder (stored as ItemBuilder)
.setLeggings(new ItemStack(Material.DIAMOND_LEGGINGS))
// Set the boots for the entity, Can take ItemStack or ItemBuilder (stored as ItemBuilder)
.setBoots(new ItemStack(Material.LEATHER_BOOTS))
// Set the main hand item for the entity, Can take ItemStack or ItemBuilder (stored as ItemBuilder)
.setMainHandItem(new ItemStack(Material.DIAMOND_SWORD))
// Set the off hand item for the entity, Can take ItemStack or ItemBuilder (stored as ItemBuilder)
.setOffHandItem(new ItemStack(Material.SHIELD))
// Set the Armor bonus attribute for the entity
.setArmorBonus(2)
// Set the Armor toughness bonus attribute for the entity
.setArmorToughnessBonus(2)
// Set the Attack damage bonus attribute for the entity
.setAttackDamageBonus(2)
// Set the Burning timer attribute for the entity
.setBurningTimer(2)
// Set the Camera distance attribute for the entity
// (Currently does nothing but, is there for future support)
.setCameraDistance(10)
// Set the explosion knockback resistance attribute for the entity
.setExplosionKnockbackResistance(10)
// Set the fall damage multiplier attribute for the entity
.setFallDamageMultiplier(2)
// Set the gravity attribute for the entity
.setGravity(0.01f)
// Set the probability of spawning reinforcements for the entity
.setSpawnReinforcements(1)
// Sets the movement efficiency for the entity
.setMovementEfficiency(0.5f)
// Sets the oxygen bonus attribute for the entity
.setOxygenBonus(10)
// Sets the safe fall distance for the entity
.setSafeFallDistance(10)
// Sets the tempt range for the entity
.setTemptRange(100)
// Sets the water movement efficiency for the entity
.setWaterMovementEfficiency(0.1f)
// Sets the waypoint receive range for the entity
// (Currently does nothing, but is there for future support)
.setWaypointReceiveRange(10)
// Sets the waypoint transmit range for the entity
// (Currently does nothing. but is there for future support)
.setWaypointTransmitRange(10)
// Sets the flying speed for the entity
.setFlyingSpeed(0.1f)
// Sets the follow range for the entity
.setFollowRange(1000)
// Sets the knockback resistance for the entity
.setKnockBackResistance(10)
// Sets the max absorption for the entity
.setMaxAbsorption(100)
// Sets the max health for the entity
.setMaxHealth(100)
// Sets the movement speed of the entity
.setMovementSpeed(2)
// Sets the jump strength of the entity
.setJumpStrength(10)
// Sets the entity scale (size) of the entity
.setEntityScale(2)
// Sets the step height of the entity
.setStepHeight(2)
// Removes the default pathfinder goals from the entity
.setRemoveDefaultGoals(true)
// Adds a custom pathfinder goal to the entity at priority 0
.addCustomPathfinderGoal(0, new TestPathfinder(100, 1f))
// Adds custom metadata to the entity
.addMetaDataValue("test_key", new FixedMetadataValue(LuaCore.getPlugin(), "test_value"))
// Adds a custom drop item to the entity (Drops are handled with RandomCollection<ItemBuilder>)
// Can take ItemStack, ItemBuilder, or you can call addDrops(Map<ItemBuilder, Double> drops) to add multiple drops at once
.addDrop(1, new ItemBuilder(Material.DIAMOND).setAmount(1))
// Disables vanilla drops for the entity
.setVanillaDrops(false)
// Set the entities AI
.setAi(true)
// Sets if the entity is silent (no sound effects)
.setSilent(true)
// Sets custom NBT data for the entity using TypedObject
// (TypeObject is simply a wrapper for any object with a type for serialization)
// Note: This data is stored under [PluginName].[KeyName]
.addCustomNBTData("test_nbt_key", new TypedObject("test_nbt_value"));
// Spawns the entity in the world at the location
// Alternatively, you can use .spawn(Location)
testEntity.spawn(location, world); {
"testEntity": {
"attributes": {
"knockBackResistance": 10.0,
"fallDamageMultiplier": 2.0,
"explosionKnockbackResistance": 10.0,
"spawnReinforcements": 1.0,
"cameraDistance": 10.0,
"movementSpeed": 2.0,
"burningTimer": 2.0,
"entityScale": 2.0,
"maxAbsorption": 100.0,
"maxHealth": 100.0,
"armorToughnessBonus": 2.0,
"waterMovementEfficiency": 0.1,
"waypointTransmitRange": 10.0,
"safeFallDistance": 10.0,
"followRange": 1000.0,
"jumpStrength": 10.0,
"gravity": 0.01,
"oxygenBonus": 10.0,
"attackDamageBonus": 2.0,
"temptRange": 100.0,
"movementEfficiency": 0.5,
"flyingSpeed": 0.1,
"stepHeight": 2.0,
"waypointReceiveRange": 10.0,
"armorBonus": 2.0
},
"entityType": "DROWNED",
"displayName": "<red>Test</red> <SOLID:32a852>Entity",
"potionEffects": [
{
"effect": "minecraft:glowing",
"duration": 120,
"amplifier": 1,
"ambient": true,
"has-particles": true,
"has-icon": true
}
],
"helmet": {
"DataVersion": 4325,
"id": "minecraft:player_head",
"count": 1,
"schema_version": 1
},
"chestplate": {
"DataVersion": 4325,
"id": "minecraft:diamond_chestplate",
"count": 1,
"schema_version": 1
},
"boots": {
"DataVersion": 4325,
"id": "minecraft:leather_boots",
"count": 1,
"schema_version": 1
},
"leggings": {
"DataVersion": 4325,
"id": "minecraft:diamond_leggings",
"count": 1,
"schema_version": 1
},
"mainHandItem": {
"DataVersion": 4325,
"id": "minecraft:diamond_sword",
"count": 1,
"schema_version": 1
},
"offHandItem": {
"DataVersion": 4325,
"id": "minecraft:shield",
"count": 1,
"schema_version": 1
},
"drops": [
{
"element": {
"type": "DIAMOND",
"amount": 1,
"stackable": true,
"usable": true,
"glowing": false,
"maxStackSize": -1
},
"weight": 1.0
}
],
"metadataValues": {
"test_key": {
"class": "org.bukkit.metadata.FixedMetadataValue",
"value": "test_value",
"plugin": "CelestialLumberYard"
}
},
"customNBTData": {
"test_nbt_key": {
"value": "test_nbt_value"
}
},
"customPathfinderGoal": {
"0": {
"distance": 100.0,
"chance": 1.0,
"class": "dev.selena.examples.ExampleCustomGoal"
}
},
"hasAi": true,
"silent": true,
"vanillaDrops": false,
"removeDefaultGoals": true
}
}As of version 1.2.1, The EntityBuilder supports custom pathfinder goals. You can add your own pathfinder goals very easily with simply 1 extra class! (Note you still need to use NMS for it)
For the custom pathfinder goals you just need three easy steps
Add something like PaperSpigots userdev
plugins
{
// other plugins
id("io.papermc.paperweight.userdev") version "2.0.0-beta.18"
}
dependencies
{
// .. Other dependencies
// Or any supported version
paperweight.paperDevBundle("1.21.5-R0.1-SNAPSHOT")
}
First step is creating the custom goal. To do this you need to create a class that implements the ICustomGoalWrapper interface.
import dev.selena.luacore.nms.ICustomGoalWrapper;
import net.minecraft.world.entity.PathfinderMob;
import net.minecraft.world.entity.ai.goal.LookAtPlayerGoal;
import net.minecraft.world.entity.player.Player;
public class ExampleCustomGoal implements ICustomGoalWrapper {
private final float distance;
private final float chance;
public ExampleCustomGoal(float distance, float chance) {
this.distance = distance;
this.chance = chance;
}
@Override
public Object createHandle(Object nmsEntity) {
PathfinderMob mob = (PathfinderMob) nmsEntity;
return new LookAtPlayerGoal(mob, Player.class, distance, chance);
}
}Now finally all you need to do is add the custom goal
testEntity.addCustomPathfinderGoal(0, new TestPathfinder(100, 1));
// Optional: If you want the new entity to only have your custom goal do the following:
testEntity.setRemoveDefaultGoals(true);{
"testEntity": {
"entityType": "DROWNED",
"potionEffects": [],
"drops": [],
"metadataValues": {},
"customNBTData": {},
"customPathfinderGoal": {
"0": {
"distance": 100.0,
"chance": 1.0,
"class": "dev.selena.celestial.utils.ExampleCustomGoal"
}
},
"hasAi": true,
"silent": false,
"vanillaDrops": true,
"removeDefaultGoals": true
}
}