NPCs

Supported software

Server software	Support
Paper and forks	Yes
Spigot	No

Supported NPC providers

Provider	Create with `/scnpcs create`	Link an existing NPC
Citizens	Yes	Yes
FancyNpcs	Yes	Yes
ZNPCsPlus	Yes	Yes
MythicMobs	No	Yes

Use /scnpcs create for a new NPC. Use /scnpcs link when the NPC already exists in Citizens, FancyNpcs, MythicMobs, or ZNPCsPlus. You need at least one supported provider. The NPCs plugin disables itself if it cannot find one during startup.

NPC definitions, provider data, and world entities must stay together. A persistent hub is the simplest place to run this plugin.To prepare a temporary group server, configure the NPCs on a persistent staging server, stop it cleanly, and then copy the world, plugins/simplecloud-npc/, and the provider’s data into the group template. Do not copy a live world into the template.

Install the plugin

Install the plugins

Download the NPCs plugin from GitHub and install one supported NPC provider. Place both JARs in the Paper server template’s plugins/ folder. Standard SimpleCloud templates already include simplecloud-api; add it through the target’s Plugins setting or the CLI if you use a custom template.

Create an NPC for a target

Start the server, stand where the NPC should appear, and choose a unique ID and an existing SimpleCloud group or persistent-server name. For a group named Lobby, run:

/scnpcs create lobby-selector Lobby

If more than one installed provider can create NPCs, add the provider name:

/scnpcs create lobby-selector Lobby citizens

Verify the result

Run /scnpcs info lobby-selector. Its status should be complete, and the NPC should have a two-line hologram. Right-click it to join the available Lobby server with the fewest players.

Link an existing NPC

Use the provider’s native reference when an NPC already exists:

/scnpcs link lobby-selector citizens 12 Lobby

This creates the SimpleCloud ID lobby-selector, links Citizens NPC 12, and targets Lobby. Provider references differ by plugin, so use command suggestions to select the installed provider and NPC. Linked NPCs remain owned by their provider. /scnpcs unlink lobby-selector removes only the SimpleCloud configuration and hologram.

Default behavior

A newly created or linked NPC starts with:

A default hologram that shows the target name and player count
A maintenance hologram that shows the target as unavailable
A right-click action that joins the target in the default state
A right-click message in the maintenance state

For a group target, the join action selects an AVAILABLE server with the fewest players. For a persistent-server target, it uses that persistent server’s proxy registration name.

Commands

The root command is available as /simplecloudnpcs, /scnpcs, and /scnpc.

Command	Description
`/scnpcs help [topic]`	Show the main help or the `create`, `link`, `edit`, `target`, `hologram`, `action`, `pushback`, or `admin` page
`/scnpcs create <id> <target> [provider]`	Create a provider NPC at your position and configure it
`/scnpcs link <id> <provider> <reference> <target>`	Link an existing provider NPC
`/scnpcs list`	List configured NPCs
`/scnpcs info <id>`	Show provider, target, hologram, action count, and configuration status
`/scnpcs edit <id>`	Show the editable sections
`/scnpcs unlink <id>`	Remove the SimpleCloud configuration but keep the provider NPC
`/scnpcs delete <id>`	Delete the configuration and, for a managed NPC, its provider NPC
`/scnpcs placeholders`	List target placeholders
`/scnpcs reload`	Reload NPC definitions and `messages.yml`

/scnpcs delete also deletes the provider NPC when SimpleCloud created it. Use /scnpcs unlink when you want to keep that NPC in the provider.

Change targets

An NPC can try more than one target. It checks them in their configured order and uses the first target with an available destination.

/scnpcs edit lobby-selector target list
/scnpcs edit lobby-selector target add BackupLobby
/scnpcs edit lobby-selector target remove Lobby

An NPC must keep at least one target. Group and persistent-server names are matched without case sensitivity, but a name is rejected if it identifies both resource types.

Edit the hologram

Hologram layouts are selected by join state. Use default for normal operation and maintenance for a target whose joinstate property is maintenance.

/scnpcs edit lobby-selector hologram line set default 1 <#38bdf8><bold><target_name>
/scnpcs edit lobby-selector hologram line add maintenance <#dc2626>Come back later
/scnpcs edit lobby-selector hologram height 2.5

Line numbers start at 1. Run /scnpcs help hologram for the enable, disable, add, set, and remove forms.

Target placeholders

Placeholder	Description
`<target_name>`	Group or persistent-server name
`<target_type>`	Target resource type
`<target_online_players>`	Current player count
`<target_max_players>`	Maximum player count
`<target_min_memory>`	Minimum memory in MB
`<target_max_memory>`	Maximum memory in MB
`<target_property:key>`	Custom target property named `key`
`<target_id>`	Persistent-server ID
`<target_pretty_name>`	Persistent-server display name
`<target_motd>`	Persistent-server MOTD

Configure click actions

Actions are scoped to an interaction and join state. Supported interactions are RIGHT_CLICK, LEFT_CLICK, SHIFT_RIGHT_CLICK, and SHIFT_LEFT_CLICK. For example, these commands keep the default join action and add feedback when a player clicks:

/scnpcs edit lobby-selector action join-target RIGHT_CLICK default true
/scnpcs edit lobby-selector action play-sound RIGHT_CLICK default block.note_block.pling
/scnpcs edit lobby-selector action send-message RIGHT_CLICK maintenance <#dc2626>The lobby is under maintenance.

The plugin can also execute a player command, teleport the player, show a title, send the player to a proxy-registered server, or transfer the player to an external address. Run /scnpcs help action for the exact command forms. execute-command supports <playername> and <playeruuid> in the configured command.

Permissions

Permission	Description
`simplecloud.npcs.command`	Use all NPC management commands; granted to operators by default

Troubleshooting

The NPCs plugin disables itself during startup

Install and enable Citizens, FancyNpcs, MythicMobs, or ZNPCsPlus on the same Paper server. Then restart the server and check the console for the list of available providers.

Create asks for a provider

More than one installed provider supports NPC creation. Add citizens, fancynpcs, or znpcsplus to the end of the create command.

The target is missing or ambiguous

Confirm that the group or persistent server exists. If both resource types use the same name, rename one of them before creating or linking the NPC.

The NPC exists but does not join a server

Run /scnpcs info <id> and resolve any incomplete status. For a group target, confirm that at least one server is in the AVAILABLE state. For a persistent server, confirm that it is active and registered on the proxy.

SimpleCloud NPC with a two-line target status hologram

Introduction

Setup

Configuration

Plugins

Supported software

Supported NPC providers

Install the plugin

Link an existing NPC

Default behavior

Commands

Change targets

Edit the hologram

Target placeholders

Configure click actions

Permissions

Troubleshooting

​Supported software

​Supported NPC providers

​Install the plugin

​Link an existing NPC

​Default behavior

​Commands

​Change targets

​Edit the hologram

​Target placeholders

​Configure click actions

​Permissions

​Troubleshooting

Supported software

Supported NPC providers

Install the plugin

Link an existing NPC

Default behavior

Commands

Change targets

Edit the hologram

Target placeholders

Configure click actions

Permissions

Troubleshooting