-
Notifications
You must be signed in to change notification settings - Fork 0
Entity API Reference
The public surface of
PlayerMobEntity
(games.brennan.playermob.entity), plus the stateless policy classes any mob
can reuse. This documents the v0.15.0 API; pre-1.0, treat it as evolving.
public class PlayerMobEntity extends Monster
implements CrossbowAttackMob, InventoryCarrierBeing a Monster, it's an Enemy; CrossbowAttackMob extends RangedAttackMob;
InventoryCarrier gives it a backpack.
| Member | Signature | Notes |
|---|---|---|
| Entity id | playermob:player_mob |
PlayerMobRegistry.PLAYER_MOB_ID. |
| Type | PlayerMobRegistry.PLAYER_MOB |
EntityType<PlayerMobEntity> (back-filled per loader — see Architecture Overview). |
| Attributes | static AttributeSupplier.Builder createAttributes() |
Defaults below. |
| Hitbox | 0.6 × 1.95 |
Matches the vanilla player hitbox (set in entityTypeBuilder()). |
Default attributes: Max Health 20.0, Movement Speed 0.30, Attack Damage
3.0, Follow Range 32.0. (Lower HP than a Pillager's 24 because it spawns
unarmoured.)
Always-on traits: never despawns naturally (requiresCustomPersistence()),
picks up loot, paths through & opens wooden doors, drops everything on death
like a player (backpack + every equipped slot, guaranteed), and uses player sounds /
player-style death messages (getSoundSource() == PLAYERS).
These are synced server→client and exposed through getters/setters (the raw
EntityDataAccessors are private):
| State | Accessors | Notes |
|---|---|---|
| Skin index |
int getSkinIndex() / setSkinIndex(int)
|
Clamped to [0, SKIN_COUNT). |
| Skin URL |
String getSkinTextureUrl() / setSkinTextureUrl(String)
|
"" ⇒ use bundled index. null coerced to "". |
| Slim flag |
boolean isSkinSlim() / setSkinSlim(boolean)
|
Renders wide in v0.15.0 regardless. |
| Charging crossbow |
boolean isChargingCrossbow() / setChargingCrossbow(boolean)
|
Drives the charge pose. |
public static final int SKIN_COUNT = 9 — the count of bundled vanilla skins.
Defined on the entity (not the client-only renderer) so the server can roll a skin
without classloading client code. See Custom Skins for the skin systems.
| Method | Returns | Notes |
|---|---|---|
personalityToward(LivingEntity) |
Personality / null
|
Disposition toward a live entity. |
nearestWithPersonality(Personality, double range) |
LivingEntity / null
|
Nearest entity the mob feels this way about. |
isArmed() |
boolean |
Main hand holds a recognised weapon (sword/axe/trident/bow/crossbow/mace). |
Full model and the (NBT-based) write path: Personality System.
| Method | Notes |
|---|---|
SimpleContainer getInventory() |
The 8-slot backpack. |
Container/armor-stand raiding helpers (used by the raid goals, public so you can drive them too):
| Method | Notes |
|---|---|
tryTakeFromContainer(Container, int slot) |
Take food (copied) or an equipment upgrade from a container slot. |
tryReplaceFromArmorStand(ArmorStand, EquipmentSlot) |
Swap an upgrade off an armor stand. |
wouldTakeFromContainer(…) / wouldReplaceFromArmorStand(…)
|
Side-effect-free "would it take this?" pre-checks. |
tryPickUpFloorItem(ItemEntity) |
Run the full floor-pickup policy on a ground item. |
boolean wantsToPickUp(ItemStack) |
Want-filter (override) shared by the goal scan + vanilla pickup. |
Equipment upgrades route through the enchantment-aware EquipmentEvaluator
(below), so an enchanted iron sword can beat a plain diamond one.
The mob keeps a "best of each category" toolkit and switches by range in combat.
| Method | Notes |
|---|---|
equipBestMeleeInHand() |
Put the best melee weapon in hand (idle / post-combat). |
equipBestWeaponForTarget(LivingEntity) |
Combat switch: ranged when far, melee when close (with hysteresis). |
drawWeaponFromBackpack() |
Skeptical "ready a weapon": move first backpack weapon to an empty hand. |
raiseShieldIfHeld() / lowerShield()
|
Skeptical shield raise/lower. |
Ranged firing is handled via performRangedAttack(LivingEntity, float) (bows) and
performCrossbowAttack (CrossbowAttackMob). See AI Goals for the composite
attack goal that calls these.
| Method | Returns | Notes |
|---|---|---|
findBestFoodSlot() |
int |
Backpack slot of highest-nutrition food, or -1. |
wantsFood() |
boolean |
Health-scaled hunger drive (delegates to ForagePolicy). |
hasImmediateFoodSource() |
boolean |
True if food is underfoot or the mob is carrying food while hurt. |
spawnEatingParticles(ItemStack) |
void |
Server-broadcast eating puff. |
| Method | Notes |
|---|---|
setCrouching(boolean) |
Crouch pose (Friendly greet / Shy hide) — drives the synced sneak pose. |
faceBodyToward(LivingEntity) |
Snap body+head to face a target (shield blocking needs facing). |
giveItemTo(LivingEntity) |
Toss a gift (looted item, or a small default) arcing toward the target. |
| Method | Notes |
|---|---|
closesDoors() |
This mob's tidiness habit (rolled at spawn, persisted). |
canRaid() |
Whether griefing (and thus chest raiding) is allowed here (mobGriefing). |
hasRaidableContainerNearby(int radius) |
Unraided chest/barrel within radius. |
openContainer(BlockPos) / closeOpenedContainer()
|
Animate a chest/barrel/shulker open/closed. |
isBlockExplored(BlockPos, long now) / markBlockExplored(BlockPos)
|
"Recently raided" cooldown (per-block). |
isEntityExplored(UUID, long now) / markEntityExplored(UUID)
|
Same, for armor stands. |
finalizeSpawn (rolls skin + unset personalities + door habit), hurt
(provocation flip — see Personality System), die (force-closes containers,
broadcasts a player-style death message), requiresCustomPersistence (→ true).
NBT round-trips through the public addAdditionalSaveData /
readAdditionalSaveData (the supported external write path for personality/skin
state).
These are stateless, Mob-agnostic, fully unit-tested static helpers — usable
by any entity, not just PlayerMob. If you're writing a mob that loots or forages,
borrow these instead of re-deriving them.
"What's worth picking up, and which of two items is better."
public enum WeaponCategory { SWORD, AXE, PICKAXE, RANGED }| Method | Purpose |
|---|---|
weaponCategory(ItemStack) |
Classify a weapon/tool, or null. |
compareQuality(ItemStack a, ItemStack b) |
Order two items of the same category (tier + enchantments). |
meleeAttackDamage(ItemStack) / enchantmentScore(ItemStack)
|
Building blocks of the comparison. |
isArmorOrShield · isAmmo · isConsumable · isValuable · isBuildingBlock
|
Category predicates. |
countBuildingBlocks · smallestBuildingBlockSlot · wantsBuildingBlock
|
Building-block hoarding (cap BUILDING_BLOCK_CAP = 64). |
Enchantment-aware equipment decisions (vanilla's comparator only sees base damage).
| Method | Purpose |
|---|---|
shouldReplace(ItemStack candidate, ItemStack current) |
Is the candidate a strict upgrade? |
canCollectFood / tryCollectFood(Container src, int slot, Container dst)
|
Move food between containers. |
addToContainer(Container, ItemStack) |
Insert, returning the leftover. |
"When does a mob want food, and what counts as food."
| Method | Purpose |
|---|---|
wantsFood(boolean hasFood, int carriedNutrition, float health, float maxHealth) |
Pure hunger decision (HEAL_BUFFER_NUTRITION = 12). |
isEdible(ItemStack) |
Has a FOOD component. |
isRipeFoodCrop(BlockState) |
A fully-grown carrot/potato/beetroot. |
isHuntableFoodAnimal(Entity) |
A non-baby cow/pig/chicken/sheep/rabbit. |
Source:
ItemPickupPolicy ·
EquipmentEvaluator ·
ForagePolicy
Getting started
No-code (datapacks)
Java API
Patterns