When using custom entities, players will need a resource pack containing all important texture, geometry, and entity files. Find out more about resource packs on wiki.bedrock.dev

Custom Entities

On PNX, you can create your own entities. Make sure your resource pack contains all the important texture, geometry, and entity files. For this example, we will use the PNX Example resource pack.

Register a Custom Entity

It is recommended to register your entity while the plugin is loaded but not enabled yet. You can achieve this in the onLoad function.

// Imports
import cn.nukkit.registry.EntityRegistry;
import cn.nukkit.registry.RegisterException;
import cn.nukkit.registry.Registries;
 
@Override
public void onLoad() {
    try {
        // First, we register our custom entity in the EntityRegistry using its identifier from the resource pack.
        // We also specify whether the entity has a spawn egg and if it should be summonable (e.g., via /summon powernukkitx:boar).
        // Then, we link the entity to its corresponding class (MyPig).
        Registries.ENTITY.registerCustomEntity(this, new EntityRegistry.CustomEntityDefinition("powernukkitx:boar", "", false, true), MyPig.class);
        // After registration, we rebuild the NBT tag to include our new entity.
        Registries.ENTITY.rebuildTag();
    } catch (RegisterException e) {
        throw new RuntimeException(e);
    }
}

Defining Your Entity

As we learned above in Register a Custom Entity, every custom entity needs to have a corresponding class, which roughly looks like this:

// Imports
import cn.nukkit.entity.Entity;
import cn.nukkit.entity.custom.CustomEntity;
import cn.nukkit.level.format.IChunk;
import cn.nukkit.nbt.tag.CompoundTag;
import org.jetbrains.annotations.NotNull;
 
public class MyPig extends Entity implements CustomEntity {
 
    public MyPig(IChunk chunk, CompoundTag nbt) {
        super(chunk, nbt);
    }
 
    @Override
    public @NotNull String getIdentifier() {
        return "powernukkitx:boar";
    }
 
    @Override
    public String getOriginalName() {
        return "boar";
    }
}

We can also implement additional features like MarkVariant and Variant, which are useful if you have multiple textures or geometries. You can simply achieve this by adding EntityMarkVariant, EntityVariant after CustomEntity.

Spawning Your Entity

After Registering and Defining our entity, we will be able to spawn it by referencing our entity class (in this example, MyPig) and calling a spawn function such as entity.spawnToAll(); or entity.spawnTo(player);. Here is an example of spawning your entity when a player uses a command:

@Override
public boolean execute(CommandSender sender, String commandLabel, String[] args) {
    if (sender.isPlayer()) {
        Player player = sender.asPlayer();
 
        // Creating a new instance of our MyPig class and providing the required variables IChunk chunk and CompoundTag nbt to the Entity constructor.
        MyPig boar = new MyPig(player.getChunk(), Entity.getDefaultNBT(player));
 
        // After creating our entity, we can spawn it for everyone on the server.
        boar.spawnToAll();
 
        // Or just spawn it for our CommandSender, which is currently our 'player'.
        boar.spawnTo(player);
 
        return true;
    } else {
        return false;
    }
}

Need Help?

If you need help, check out our Example plugin or join our Discord server and ask for help.

Custom Items