Players¶

Quick Start: Spice it up with twists.

Live body reads: state, blocks, slots, titles, movement, and inventory. The one-line forms live in the cheatsheet. Twins: every <p*> tag below also ships <r*> (one role) and <g*> (everyone) twins; see Role and global twins.

<plos:player,target,maxdist,maxangle> reads 3D line of sight: true when the target's head point sits within maxdist blocks (default 180), within maxangle degrees of the player's look direction (default 90, clamped to 0..180), and reachable by an unblocked block+player ray from the eye. The head point is feet plus 1.5 blocks (1.35 while sneaking). Angles below 90 calibrate at 8 blocks: the authored angle holds exactly 8 blocks out, and scales nearer and farther so the same lateral offset passes at any range (a 10 degree cone reads about 1 degree at 80 blocks). Angles of 90 and above compare raw. Checks run cheap-first (dimension, distance, angle) with the raycast last. Offline, unknown, or cross-dimension players resolve null silently.

<pstate:player,state> reads the live body: SNEAK, SPRINT, GLIDE, SWIM, or GROUND (any case), true or false. IDLE reads true when the player did not move since this modifier's own last check: the inverted twin of <pismoving>. Both share and advance one baseline per modifier, so a tick should read only one of them (a second movement read in the same tick always sees no movement). Unknown states warn, list the valid names, and yield null; offline or unknown players resolve null silently. <pstandingon:player> reports the upper-case material below the feet (AIR over the void), silent null when offline. <pblock:player,type> reports the lower-case block id (dirt, oak_slab, no namespace) at under (below the feet, air over the void), feet, or head (the eye block); the type is optional and defaults to under. Unknown types warn, list the valid names, and yield null; offline or unknown players resolve null silently. <pisusinghanditem:player,item> reads true while the player holds an item in use (either hand): drawing a bow, loading a crossbow, blocking with a shield, zooming a spyglass, eating, drinking, and kin. The optional item filters to one material (spyglass, crossbow, minecraft:bow); omitted or blank means any item. Instant-use items such as fishing rods, thrown pearls, or placed blocks never hold use state, so they warn as never usable instead of reading true. Unknown materials warn too; offline players resolve null silently. <puuid:player> reports the Mojang id as four ints in NBT int-array order, silent null when offline, so Owner:[I;<list.join:<puuid:Steve>,",">] renders an NBT owner. <pstat:player,exp-level> reads the vanilla experience level.

<ptitle:player,title,subtitle,stay,in,out> sends a center-screen title; the timings are seconds in written order (stay, fade in, fade out: never Paper order), trailing args may be omitted, and defaults are stay 2.0, in 0.4, out 0.4. Seconds convert to ticks through the engine converter (0.05s per tick, minimum one tick). Title and subtitle parse like message text (MiniMessage plus legacy codes); blank parts are allowed. Bad timing warns plus null with nothing sent, as does an offline player; success returns empty.

<pslot:player,slot> gets [MATERIAL, qty], with null for an empty slot or an offline player. <pslot:player,slot,newitem> sets unconditionally and returns empty. Slots name equipment (mainhand, offhand, helmet, chestplate, leggings, boots, any case) or address the raw player inventory by index: 0-8 hotbar, 9-35 main storage, 36-39 armor, 40 offhand. A [material, qty] list sets both, a bare material sets qty 1; materials match case-blind, qty clamps silently to 1 through the max stack, and anything invalid (unknown slot or material, non-integer qty, bad index) warns plus null with no change.

<clearslot:player,slot> empties one slot, using the same slot addresses as <pslot> (equipment names or raw indices 0-40), and yields empty. Blank players, bad slots, and offline players warn plus null with nothing cleared.

<itemtag:player,slot> reads the unprefixed JMH tag behind one slot, using the same slot addresses as <pslot>. Empty slots, offline players, and untagged items read null quietly; only a blank player or a bad slot warns. See JMH item data for writing tags.

<pismoving:player> reads movement since this modifier's own last check: the first check seeds the baseline and reads false, later checks read true when the spot (exact coords or world) changed. Each modifier keeps its own baseline per player, so two modifiers polling at different rates never steal each other's checks; rotation alone never counts, and offline or unknown players resolve null silently. Baselines clear at match end. <pstate:player,IDLE> inverts this same baseline (stillness instead of motion) and advances it too, so one tick reads either <pismoving> or IDLE, never both. Evaluate once per poll and reuse the answer through <lf:>: every evaluation moves the baseline forward:

- '<lf:moved,<pismoving:<p>>>'
- '<if:"<lf:moved> == true","<pf:hold-<id>,0>">'
- '<if:"<lf:moved> == true","exit">'

<premoveitem:player,item,count> removes count of the material from the player's storage (hotbar plus main inventory, the same population <phasitem> counts), all-or-nothing: when fewer are held nothing changes. The count defaults to 1. It yields true when items left the inventory, false when too few are held, the player is offline, or the material is unknown; misuse (blank player or item, a count below 1) warns plus null. Materials match case-blind with an optional minecraft: prefix:

- '<if:"<premoveitem:<p>,GOLD_INGOT,3> == true","say Toll paid!">'

<pdamage:player,amount,by,type> deals amount damage to the player in health points (20 is ten hearts; whole numbers convert implicitly). The attacker is optional: omitted or blank means no attacker, and a name outside the match silently drops to no attacker too, so kills credit only real match players. The type is optional and defaults to arrow; names match case-blind with an optional minecraft: prefix (dragon_breath, minecraft:campfire, and registered datapack namespace:key forms). It yields empty on success; misuse (a blank player, a non-numeric or negative amount, an unknown type) and offline players warn plus null with nothing dealt. Unlike <run:damage ...>, the call never depends on vanilla command syntax:

- '<pdamage:Alex,6,Steve>'

<kill:Steve,Alex> kills Steve through the engine damage path, so stats, teams, and killstreaks credit Alex exactly like a natural kill. The killer is optional (omitted kills read environmental), and the force flag is optional too, default false: without it one lethal hit lands and totems save, with it (<kill:Steve,Alex,true>) the hits repeat past totem pops. Offline victims warn plus null; an offline killer degrades to environmental with a warning.

<give:Steve,[diamond, 3]> delivers three diamonds to one online player and yields empty. The payload is one [material, qty] pair or a nested list of pairs, safer than vanilla give (no command syntax to quote); unknown materials warn and skip. Stacks that do not fit drop naturally at the player's feet. Offline players warn plus null with nothing delivered, and the tag names its player, so it works in any list, console included:

- '<give:<p>,[[iron_sword, 1], [bread, 16]]>'

<pghost.enter:Steve,drone,[0, 64, 0, world]> detaches Steve into a ghost: a mannequin decoy with their skin stays at their exact spot and rotation (crouching players leave a crouching decoy with no nameplate, everyone else leaves a standing decoy named in the role color), wearing copies of their armor and holding copies of their hand items, while Steve rides a cinematic anchor at the loc as its passenger. The anchor entity sits one eye height below the loc, so the ridden view lands exactly on it. There are no body teleports: the rider follows the anchor exactly, so look packets flow and pose reads (<ploc>, <pdir>, line of sight, and the rest) track the drone with a live look, and the anchor copies that look every tick. Sneak descends without dismounting, clicks never glue the camera to an entity, spectator-menu teleports are rejected, and WASD never fights the drone (a ridden anchor ignores movement input). <pghost.control:drone,[0, 0, 1],0.3> steers the anchor toward that blocks-per-tick velocity in look-relative space (forward follows the gaze, strafe stays level, lift stays vertical; smoothness 0 answers instantly, 1 glides the slowest, eased in world space so turns keep their momentum). An optional fourth enter arg picks the lift axis: WORLD (default) keeps lift vertical, CAMERA lifts along the gaze tilt, so vertical input steers with the look the way the other axes already do. The ghost exits instantly on block collisions and living or projectile hits (projectiles scan the roomier ghost-touch box, so arrows and thrown shots can down a drone the small collider would let through), and two ghosts whose bounds touch exit together. Spectators and lobby idlers never break a ghost: their bodies and their shots pass through, and damage they cause to the decoy is swallowed without mirroring. Any other damage to the decoy mirrors onto the player in full (armor-piercing, same attacker) and exits too, as do quits, leaves, and teleports. While ghosted, hunter compasses track your frozen last-seen spot with the away reason instead of the live drone. <pghost.exit:drone> closes the ghost by id: the decoy vanishes, the body comes home to the decoy spot (the anchor when the decoy is already gone) keeping its look, the gamemode restores, and ON_PGHOST_EXIT fires with the player, the id, the damage taken, the exit reason, its detail, the shooter name, and the colliding entity's location (match-end exits stay silent; see event args for the reason values). Entering while a cinematic camera holds the player is unsupported: the two systems fight over the same body. While ghosted, the rider is exempt from GrimAC checks when GrimAC is installed (a session-scoped grim.exempt grant, lifted on every exit); without GrimAC nothing changes.

- '<pghost.enter:<p>,drone,[<px:<p>>,100,<pz:<p>>,<pworld:<p>>]>'
- '<pghost.control:drone,<vec.mult:<args:2>,2>,0.3>'

<pshapeshift.mob:Steve> prompts Steve to become their pending mob: the last living mob they killed, stored per player on every ON_MOB_KILLED (that trigger's <args:0> carries the same name, so custom prompts can read it too). The engine message names the mob and opens the sneak-jump window (10 seconds by default; the optional third arg retunes it per call, clamped to 1..60 seconds). Sneaking with the jump key held inside the window starts the hold (3 seconds by default; the optional fourth arg retunes it per call, same clamp); a hold started inside the window always completes, even past the window end. Landing cloaks the body (endless iconless invisibility plus hiding from every viewer, damage unaffected) and spawns a view-mob that follows the player's spot and look every tick, across dimensions, with no AI awareness. Non-living types and the ender dragon refuse with one console warning per match per type, as do unknown mob types (which shift with no abilities); no pending mob, a ghosted player, or an already shifted player warns and no-ops instead. An optional true second arg lands without per-mob abilities. While shifted, damage to the view-mob cancels, routes onto the player with its source, and echoes onto the mob for feedback (near-infinite mob health, so the echo never kills it), and knockback to the mob lands on the player instead. The mob mirrors sneak, swim, glide, and sneak-driven sitting where the platform allows (sprinting and walking have no mob API); invisibility bonuses apply to the mob, every other effect applies to the player, all with no particles and no icon, on cycles and loot intervals that reset on every shift (see shapeshift/abilities.yml). Mundane mobs (pig, cow, chicken) shift with empty kits and no warning. <pshapeshift.exit:Steve> exits the shift now, firing ON_SHAPESHIFT_EXIT with the player, the mob, and the reason (MANUAL for the tag, COMBO for the exit hold, DEATH, QUIT, or MOB_LOST); unshifted players exit silently. Shifted players can also sneak with the jump key held (no prompt needed) to start the exit hold (same duration), and death, quit, or mob loss exits the same way (the mob drops silently and lootlessly while the player drops theirs). Match-end exits stay silent.

- '<pshapeshift.mob:<p>>'
- '<pshapeshift.exit:<p>>'

Next Steps¶

• Tag Cheatsheet
• Effects
• Flags