Personas – NPC Emoting Plugin

Description

| LuckPerms or another permission plugin | Recommended | Used to grant personas.admin without making staff server operators. |
| Internet access | Optional | Needed only when resolving usernames/MineSkin URLs into signed skin textures. |

Install order for a normal server:

1. PacketEvents.jar
2. Animotions.jar
3. Personas.jar

Personas must load after Animotions. The plugin metadata handles this, but the files still need to be present in the server plugins/ folder.

Installation

1. Stop the server.
2. Put PacketEvents.jar in plugins/.
3. Put Animotions.jar in plugins/.
4. Put Personas.jar in plugins/.
5. Start the server once.
6. Confirm the console says Personas enabled and created its data folder.
7. Stop the server if you need to edit plugins/Personas/config.yml.
8. Grant personas.admin to staff who should manage NPCs.
9. Start the server again.

Generated Files

On first startup Personas creates:

plugins/Personas/
  config.yml
  personas.db
  personas/
  templates/
    example-persona.yml

personas.db is the SQLite database. It stores NPC definitions, skins, and action lists.

personas/ contains one mirrored YAML file per NPC. These files are editable and are synced back into SQLite when Personas notices they changed.

templates/ contains reusable NPC templates. Admins can spawn templates with /personas template <name>.

Permissions

Personas currently has one management permission:

Permission	Default	Purpose
personas.admin	OP	Allows every /personas management command and tab completion.

All /personas commands are admin commands. The command object is registered programmatically and calls setPermission("personas.admin"). The command executor also checks sender.hasPermission("personas.admin") before doing any work.

The command is also player-only. Console senders receive:

Only players can use /personas.

This is intentional because create, select-by-looking, movehere, skin, action editing, and template spawn commands depend on an in-world player location or selected NPC state.

LuckPerms Examples

Grant full Personas management to an admin group:

/lp group admin permission set personas.admin true

Grant it to one staff member:

/lp user <player> permission set personas.admin true

Make sure regular players do not have the permission:

/lp group default permission set personas.admin false

Avoid granting personas.admin broadly. It allows creation, deletion, reloads, and action configuration. Because actions can include console_command, anyone with this permission can configure NPCs that execute server-console commands when triggered.

Configuration

Default plugins/Personas/config.yml:

debugging: false

database:
  file: personas.db

storage:
  personas-directory: personas

templates:
  directory: templates

debug:
  enabled: false

npc-runtime:
  mode: auto

idle:
  interval-ticks: 200

tracking:
  interval-ticks: 10

debugging

Top-level debug switch. When present, this value wins over debug.enabled.

When enabled, Personas sends more feedback for routine commands and action execution results, including Animotions bridge results.

debug.enabled

Legacy nested debug switch. Used only when top-level debugging is not set.

database.file

SQLite database file under plugins/Personas/.

Default:

database:
  file: personas.db

Keep the default unless you have a migration reason. If you change it, Personas creates or opens that database on next startup.

storage.personas-directory

Directory for mirrored persona YAML files.

Default:

storage:
  personas-directory: personas

The path is relative to plugins/Personas/.

templates.directory

Directory for template YAML files.

Default:

templates:
  directory: templates

The path is relative to plugins/Personas/.

npc-runtime.mode

Controls how NPCs are rendered.

Value	Meaning
auto	Use packet fake-player mode when PacketEvents is available, otherwise armor-stand fallback.
packet	Request packet fake-player mode. Falls back to armor stands if PacketEvents is unavailable.
fake_player	Alias for packet.
packet_fake_player	Alias for packet.
armor_stand	Force armor-stand fallback mode.
armorstand	Alias for armor_stand.
stand	Alias for armor_stand.

Default:

npc-runtime:
  mode: auto

idle.interval-ticks

How often idle actions run for each enabled persona.

Default:

idle:
  interval-ticks: 200

200 ticks is 10 seconds. Personas enforces a minimum of 20 ticks.

tracking.interval-ticks

How often Personas evaluates:

• look-at-player rotation
• player_near
• player_enter_range
• player_leave_range

Default:

tracking:
  interval-ticks: 10

10 ticks is 0.5 seconds. Personas enforces a minimum of 5 ticks.

Lower values feel more responsive but run more often.

First NPC

Stand where you want the NPC and run:

/personas create guide
/personas skin Notch
/personas name set Guard Captain
/personas look 8
/personas emote add click wave
/personas action add right_click console_command give %p stick 1
/personas action add left_click player_command me greets %npc%
/personas trigger test click

What this does:

• Creates guide at your current location and selects it.
• Resolves the Notch skin.
• Sets the visible display name to Guard Captain.
• Makes the NPC face the nearest player inside 8 blocks.
• Adds an NPC emote on generic click.
• Gives the clicking player a stick on right click.
• Makes the clicking player run /me greets guide on left click.