API - MarkusBordihn/BOs-Easy-NPC GitHub Wiki

Easy NPC API 🧩

Easy NPC exposes a public API for mods that want to create their own NPC types, control existing NPCs, or reuse the rendering pipeline. Everything below lives under de.markusbordihn.easynpc.api.

The API is still evolving. Breaking changes can happen in minor versions until it is declared stable; if a source file and this page disagree, the source code is the current truth.

What You Can Do

Goal Start at
Create your own NPC entity type api.npc raw classes, see below
Query, spawn, or despawn NPCs from code api.handler.EasyNPCEntityHandler
Set poses programmatically api.pose.ModelPoseAPI
Give an entity variant-based textures api.skin, see API-Variant-System
Add or replace model geometry api.model, see API-Custom-Models

Custom NPC Types

Extend one of the raw NPC classes in de.markusbordihn.easynpc.api.npc.raw. They already contain the Easy NPC data, sync, and configuration handling:

public class MyCustomHorse extends HorseRaw {

  public MyCustomHorse(EntityType<? extends Horse> entityType, Level level) {
    super(entityType, level);
  }
}

Then register the entity type with your mod loader (Forge, Fabric, or NeoForge) as usual.

Raw classes are available for most vanilla mob families - humanoid, zombie, skeleton, villager, illager, piglin, horse, spider, slime, ghast, wolf, cat, fox, pig, chicken, allay, vex, creeper, enderman, iron golem, and witch. PathfinderMobRaw is the generic base.

Override getConfigurationData() from api.npc.BaseEasyNPC to control which configuration screens your NPC offers.

Managing NPCs from Code

EasyNPCEntityHandler works on the server-side NPC index, including NPCs that are currently despawned:

Collection<SavedNPCEntityEntry> all = EasyNPCEntityHandler.getAll();
Collection<SavedNPCEntityEntry> mine = EasyNPCEntityHandler.getByOwner(ownerUUID);
Collection<SavedNPCEntityEntry> here = EasyNPCEntityHandler.getByDimension("minecraft:overworld");

EasyNPCEntityHandler.spawn(uuid, serverLevel);
EasyNPCEntityHandler.spawn(uuid, serverLevel, position);
EasyNPCEntityHandler.despawn(uuid, serverLevel, NPCRemovalReason.DESPAWNED);

Lookups are also available by entity type and by custom identifier.

Poses

ModelPoseAPI is the supported way to change a pose without touching internal data classes:

ModelPoseAPI.setPose(npc, new ResourceLocation("easy_npc", "pose/humanoid/sitting"));
ModelPoseAPI.setPose(npc, "sitting");
ModelPoseAPI.setVanillaPose(npc, Pose.CROUCHING);
ModelPoseAPI.resetPose(npc);

String currentPose = ModelPoseAPI.getCurrentPoseName(npc);
ModelPose mode = ModelPoseAPI.getCurrentPoseMode(npc);
Set<ResourceLocation> available = ModelPoseAPI.getAvailablePoses(skinModel);

setPose(npc, "sitting") resolves the pose against the NPC's own skin model, which is the easier call when you do not want to build the ResourceLocation yourself.

setVanillaPose(...) clears custom rotation and position data, so it is also the way back to plain vanilla behavior.

Entity Data

Per-NPC data is reached through the getEasyNPC…Data() accessors on EasyNPC<?>, for example:

SkinDataCapable<?> skinData = npc.getEasyNPCSkinData();
ModelDataCapable<?> modelData = npc.getEasyNPCModelData();
ProgressionDataCapable<?> progression = npc.getEasyNPCProgressionData();

These interfaces live in de.markusbordihn.easynpc.entity.easynpc.data. They are stable enough to build on, but they are not part of the api package - not every internal class is meant to be an extension point.

Related Pages