NPCs

An NPC is a player figure standing at a place, facing a way. Like holograms it is packets only: it cannot be hurt, pushed or killed, and it costs nothing when nobody is near.

Creating one

It stands where you stand. With face-creator on (the default) it faces you; off, it looks where you were looking, level. It gets the default-view-distance and default-look of config.yml and a label with its name, or the preset's label (%npc% becomes its name) and actions. A preset's skin wins over the one typed, unless the preset has none.

The shipped presets:

The editor

/npc <name> (or a left-click in the list):

Skin

Pose, size and outline

Equipment

Slots: head, chest, legs, feet, hand, off_hand.

/npc guide equip hand                    # the item in your hand
/npc guide equip hand DIAMOND_SWORD
/npc guide equip head playerhead-Notch
/npc guide equip head basehead-<texture>
/npc guide equip hand air                # empties the slot
/npc guide equip clear                   # empties every slot

The file keeps each slot as an icon string: a material, playerhead-<name>, basehead-<texture>, or a bytes: item for an item from your hand that carries more than a material.

Where it looks

The number is the look range in blocks (default 8). each-viewer is the default for new NPCs (default-look).

With face-clicker on (default), a click that runs its actions also turns it toward the clicker for turn-back (default 4 seconds), then back. That turn is never saved.

Who sees it

• /npc <name> viewdistance <blocks>: how far away it is seen (default 48).
• /npc <name> permission [node]: only players with the node see it, its label included. No node clears it.

An NPC in a world that is not loaded waits and appears when the world loads.

The label

The label is the lines above its head, the name players read. It is a hologram, so every line tag works in it, and clicking it does what clicking the NPC does.

/npc guide label set <size:1.2><shine>{primary}&lGUIDE    # replaces every line with this one
/npc guide label add <opacity:200>{letters_black}Right-click me
/npc guide label remove 2
/npc guide label clear
/npc guide label height 0.4

height-offset is the gap between the top of its head (which follows its pose and scale) and the label's bottom line. Default 0.25. A label with no lines is no label.

A linked hologram

For something more than a name — pages, a click box of its own, per-viewer placeholders — link any hologram of holograms.yml:

/npc guide link guide_board
/npc guide unlink

The NPC moves that hologram above its head (over the label, if it has one) by writing its location in holograms.yml, and does it again every time the NPC moves. The hologram is still edited as a hologram. Linking needs the hologram module on.

Statues

A statue is an NPC frozen in place, wearing whoever holds a spot: the weekly top 3 at spawn, a tournament champion as a trophy.

1. Create it with the statue preset: it faces the way it was placed, has a gold outline and a plaque label.

2. Point its skin at a placeholder that gives a player name, with an account to wear while the spot is empty. It changes skin on its own when somebody else takes the spot:

   /npc top1 skin %ajlb_lb_statistic_player_kills_1_alltime_name% Notch

3. The label is the plaque, and placeholders work in it:

   /npc top1 label set <size:1.3>{highlight}&l#1 {primary}&l%ajlb_lb_statistic_player_kills_1_alltime_name%
   /npc top1 label add {letters_black}▎ {letters}Kills {letters_black}» {info}%ajlb_lb_statistic_player_kills_1_alltime_value%

4. Give it a pose (/npc top1 pose sneaking), something to hold (/npc top1 equip hand), or make it dance whenever somebody is near, with a continuous idle:

   /npc top1 animation idle anim:<a looping clip>
   /npc top1 animation idle-continuous on

Build the pedestal with real blocks and place the statue on top: players can stand on it and walk around it.

Animations

An NPC plays something on four triggers: a left click, a right click, on its own (idle) and to greet a player who walks up (greet, seen only by that player). Each holds either vanilla moves or one performance.

A performance is a whole body that takes the NPC's place for whoever is within perform-range (24 blocks by default): it bows, dances or salutes instead of swinging an arm. Its hitbox stays, so clicks still reach the NPC. One plays at a time, and a sitting NPC never performs.

npcs:
  guide:
    animations:
      left-click: flinch
      right-click: anim:wave
      idle: anim:sway
      idle-every: 20s           # how often the idle plays; 0 never
      idle-continuous: false    # true: the idle loops while anyone is near
      idle-group: ''            # NPCs of one group keep their idles in step
      greet: bow
      greet-range: 4.0
      greet-cooldown: 30s
      perform-range: 24.0

Set them with /npc <name> animation <trigger> <value> (none clears one), or from ANIMATIONS in the editor. /npc <name> play <value> tries one now and says when it was skipped. The performance picker (shift-left-click ANIMATIONS) lists every emote and clip: left-click one to put it on a trigger, right-click to try it.

The skin

The body wears the NPC's own skin, an account or a texture. With @mirror a greeting (seen by one player) wears that player's skin, and anything everybody sees wears the default one, since one body is shared. It is drawn from real skin pieces (Exylia Skins), so nothing is uploaded to MineSkin and no resource pack is needed.

Continuous idle

With idle-continuous: true the idle performance plays without end for as long as anybody is within perform-range, and nobody near means no body and no cost:

/npc dancer animation idle anim:sway
/npc dancer animation idle-continuous on

• A click, a greeting or /npc <name> play plays over it at once, and the idle comes back after.
• Write the idle as a loop (a clip set to loop in Blockbench, or loop:true;anim:<clip>). A clip that does not loop plays to its end and starts again with a short flash.
• Somebody who walks up mid-loop sees the plain NPC until the end of the current cycle, then joins in.
• It only applies to performances; vanilla idle moves keep idle-every.

Groups

A group is a set of NPCs that move as one: a choir, a line of dancers, the three statues of a podium.

/npc left group stage
/npc middle group stage
/npc right group stage
/npcadmin group play stage anim:dance

• /npc <name> group <key|none> puts it in a group. The group is the NPC's idle-group, the same key as /npc <name> animation idle-group: one setting, two names.
• Continuous idles of one group share one clock: an NPC that starts later, or comes back after a click, waits for the next cycle and plays in the same pose as the others. Give a group one idle clip.
• /npcadmin group play <group> <animation> starts it on every member at the same instant and tempo, and says how many started and how many were skipped (already performing, not in the world, or nobody near).
• /npcadmin group stop <group>, /npcadmin group pause <group> and /npcadmin group resume <group> act on every member. /npcadmin group list shows each group with its members.

Pause and stop

Paused is not saved: a restart resumes every NPC. /npc <name> info, the ANIMATIONS card and the PLAYBACK button of the performance picker show the state; the button pauses or resumes (left) and stops (right).

Blockbench

anim: reads Blockbench projects directly. Save the .bbmodel into plugins/ExyliaDisplays/animations and its clips play at once: no export step, no reload, and a project saved again plays its new frames.

1. On start the plugin writes two templates there, each only if it is missing:

   File	Rig
   player_classic.bbmodel	4-pixel arms (Steve)
   player_slim.bbmodel	3-pixel arms (Alex)

   Both have the bones anim: reads (body, torso, head, right_arm, left_arm, right_leg, left_leg, each limb with a _bend bone for the elbow or knee) and one example clip, wave.

2. Open one in Blockbench, add clips under Animate, and save. A copy under another name works too.

3. /npcadmin animations lists every file with its clips, whether each loops and how long it is. /npcadmin animations <file> shows one file. Click a clip to copy its anim: name.

4. Play it: /npc <name> play anim:<clip>, or put it on a trigger.

A clip is called by its name. A file with one clip also answers to the file's name. Drag a skin onto the model in Blockbench to see it; in game the body wears the NPC's skin.

Commands at a glance

See Commands for the full list. /npc competes with Citizens' /npc when both are installed; use /npcs <name> or /exylianpc <name> then. /npcadmin never clashes.