Home

PlayerMob — Modder Documentation

PlayerMob registers a custom Minecraft entity (playermob:player_mob) that looks like a player and fights like a pillager — weapon-aware ranged/melee AI, per-category personalities, datapack-extensible skins, inventory raiding, and an optional soft-dependency integration seam.

This wiki is for modders, datapack authors, and map makers who want to build on top of PlayerMob — not for end users installing the mod. If you just want to play with it, grab a release and read the README.

Heads up — license. PlayerMob is released under PolyForm Shield 1.0.0, a source-available, non-compete license. You may read, learn from, and build alongside it, but there are restrictions on shipping something that competes with it. Read LICENSE before redistributing code derived from this repo.

---

Compatibility

Minecraft	1.21.1
Java	21 (toolchain-pinned)
Loaders	Fabric · Forge · NeoForge
Fabric Loader / API	0.16.5 / 0.103.0+1.21.1
Forge	1.21.1-52.1.14
NeoForge	21.1.228
Build	Architectury Loom 1.13-SNAPSHOT, architectury-plugin 3.4-SNAPSHOT
Mod id	playermob
Maven group	games.brennan.playermob
Latest version	0.15.0

These values live in gradle.properties — always treat that file as the source of truth.

---

Three ways to build on PlayerMob

Pick the tier that matches how deep you want to go. Everything in tier 1 works without writing or compiling any code.

1 · No-code (datapacks, commands, map-making)

• Order Command — /playermob order <name> <action> …: direct a PlayerMob to walk, punch, attack, gift, greet, steal, use an item, or place a block against a player, another PlayerMob, a mob type, or coordinates.
• Skin Sources — where PlayerMob skins come from (bundled / online / your own local folder) and how to turn each source on or off.
• Custom Skins — add real-player / custom skins by dropping JSON into a datapack, or your own PNGs into config/playermob/skins. No Java, no rebuild.
• Spawning and NBT — /summon and spawn-egg reference: configure personality, skin, equipment, and door behaviour via NBT.
• Natural Spawning — opt-in wild spawning: a PlayerMob spawns alongside wild mobs (off by default), tuned via config/playermob.properties and the /playermob naturalspawn commands.
• Ranged Combat and Ammo — bows/crossbows use inventory ammo (arrows; plus fireworks for crossbows), with the ranged↔melee range switch, the /playermob unlimitedammo toggle, and engage-distance config.

2 · Java API (mods that depend on PlayerMob)

• Developer Setup — clone, build, and declare a dependency on PlayerMob.
• Personality System — read and set per-category dispositions in code.
• Entity API Reference — the public PlayerMobEntity surface plus the reusable, stateless policy classes any mob can borrow.

3 · Architecture & integration patterns

• Architecture Overview — the Architectury common+loader split and the registration model you must follow to add registered content.
• AI Goals — how the brain is wired and how to extend behaviour.
• Soft-Dependency Integrations — the TrainEnvironment seam: add an optional cross-mod integration that loads with or without the other mod present.

---

Quick links

• Source: https://github.com/bh679/playermob-mc
• Issues / feature requests: https://github.com/bh679/playermob-mc/issues
• License: PolyForm Shield 1.0.0

Versioning. This wiki documents v0.15.0 (MC 1.21.1). PlayerMob is pre-1.0 and still evolving — APIs marked plumbed for a future version may change. NBT keys and Personality ordinals are treated as a save-compatible contract (see Spawning and NBT).