NPCs Plugin

Create NPCs on your server that allow your players to access other subservers through the NPCs. Perform various actions such as sending messages, titles, action bars, or sounds, or customize inventories with your items. Use your favourite NPC system or use the plugin as a standalone with its own NPC integration. The all new NPC plugin opens up limitless creative possibilities.

Download

Supported Server Softwares

The following table shows all currently supported server implementations:

Server type	This Plugin
Paper & Forks	Yes
Spigot & Forks	Yes
Other	No

Quick Setup

Download the plugin
Optional: Download a supported NPC software from here
Place it in your server's plugins folder
Start your server

Usage of other NPC plugins

You don't want to use our own NPC implementation? No problem! Thanks to the new structure, you can also use other NPC plugins such as Citizens. This allows you to use all the features of your NPC plugin together with the functions of SimpleCloud. The following NPC plugins are supported:

Plugin	Supported Versions	This Plugin
FancyNpcs	1.19.4 - latest version	Yes
Citizens	1.19 - latest version	Yes
MythicMobs	1.19 - latest version	Yes
PlayerNPC	1.17.1 - 1.20.1	Yes

If you would like to add support for a missing npc plugin, feel free to submit a issue on GitHub.

As you have installed one of the supported NPC plugins on your server, the system automatically takes over the appropriate implementation. You don't have to do anything else!

Understanding Actions

Actions allow you to interact with NPCs and set the trigger of an action individually. Each action has its own option with which you can customise it. Exactly as required for your NPC. Here you will find all available actions and their options:

Action	Option	Description
`open_inventory`	inventory.name	Open an inventory to select a server
`run_command`	command.name	Execute a command via the player
`run_console_command`	command.name	Execute a command via the console
`connect_to_server`	server.name	Send a player to a server
`transfer_to_server`	server.ip, server.port	Send a player to an external server with the transfer method
`quick_join`	group.name, server.name.pattern, filter.player.count, filter.server.state	Send a player to an random server

Creating a NPC

First, make sure that the NPC plugin is installed on your server, and if you want to use a supported NPC system, ensure that it is also installed on the server.

The first step is to create an NPC. If you're using a supported NPC system, refer to the documentation of the respective plugins.

If you have created an NPC with one of the supported plugins, you only need to execute the command /scnpc apply <id> to use the functions of SimpleCloud.

NPC Configuration

When you create an NPC using our plugin or another plugin, a separate configuration for each new NPC will be generated in the plugin folder.

version: '1.0'
id: bedwars
holograms:
  - start-height: 2.073
    lores:
      - text: <group_name> - <property:server-software>
        billboard: CENTER
        alignment: CENTER
      - text: waiting for <player_count:available> players
        billboard: CENTER
        alignment: CENTER
      - text: "<server_count:ingame> Servers ingame"
actions:
  - player-interaction: LEFT_CLICK
    action: OPEN_INVENTORY
    options:
      inventory.name: bedwars
      play.sound: block.chest.open
      sound.pitch: 3
      sound.volume: 2
  - player-interaction: RIGHT_CLICK
    action: TRANSFER_TO_SERVER
    options:
      server.ip: demo-server.com
      server.port: 25565
      send.actionbar: abda
options:
  hologram.placeholder.group: lobby
  send.message: <rainbow>Some cool text here
  send.title: title
  send.subtitle: some cool subtitle

Configure the NPC either in the NPC configuration file or through commands. The configuration will be automatically reloaded if any changes are made to the file. If you want to configure the NPC using commands, use either /scnpc <id> interact <type> setAction <action> or /scnpc <id> interact <type> setOption <key> <value>.

Options are sent as feedback when an action is performed. You can set the following options:

Option key	Description
`send.message`	Sends a message
`send.actionbar`	Sends a message as an actionbar
`send.title`	Sends a title
`send.subtitle`	Sends a subtitle
`play.sound`	Plays a sound

Configure Inventories

If you specify the action OPEN_INVENTORY, you need to reference an inventory from the plugin folder under inventories/. Configure inventories in the configuration file as follows:

version: '1.0'
id: quickjoin.bedwars
title: <#ffffff>Bedwars
rows: 6
pagination:
  listed-group-name: bedwars
  server-name-pattern: <group_name>-<numerical_id>
  state-items:
    PREPARING: starting_pagination_item
    STARTING: starting_pagination_item
    AVAILABLE: available_pagination_item
    INGAME: ingame_pagination_item
  from-slot:
    row: 1
    column: 1
  to-slot:
    row: 3
    column: 7
  excluded-slots:
    - row: 1
      column: 8
    - row: 2
      column: 0
    - row: 2
      column: 8
    - row: 3
      column: 0
  next-page-item:
    item: next_pagination_item
    slot:
      row: 4
      column: 0
    increments:
      LEFT: 1
  previous-page-item:
    item: previous_pagination_item
    slot:
      row: 4
      column: 0
    increments:
      LEFT: -1
static-slots:
  - item: red_previous_pagination_item
    slots:
      - row: 5
        column: 0
  - item: red_next_pagination_item
    slots:
      - row: 5
        column: 8
items:
  - id: next_pagination_item
    material: LIME_STAINED_GLASS_PANE
    display-name: <green>Next Page
  - id: previous_pagination_item
    material: LIME_STAINED_GLASS_PANE
    display-name: <green>Previous Page
  - id: red_next_pagination_item
    material: RED_STAINED_GLASS_PANE
    display-name: <red>Next Page
  - id: red_previous_pagination_item
    material: RED_STAINED_GLASS_PANE
    display-name: <red>Previous Page
  - id: starting_pagination_item
    material: ORANGE_BANNER
    display-name: <group_name> <numerical_id>
  - id: available_pagination_item
    material: LIME_BANNER
    display-name: <group_name> <numerical_id>
    lores:
      - "<gray>Players: <#38bdf8><online_players><dark_gray><dark_gray>/<#38bdf8><max_players>"
      - ""
      - "<gray>Version: <#a3a3a3><property:server-software> <property:minecraft-version>"
      - "<gray>Template: <#a3a3a3><property:template-id>"
  - id: ingame_pagination_item
    material: BROWN_BANNER
    display-name: <group_name> <numerical_id>

Commands

Command	Description
`/scnpc apply <name>`	Adds the support of simplecloud functions
`/scnpc <id> interact <type> setAction <action>`	Set Actions, type can be `right_click` or `left_click`
`/scnpc <id> interact <type> setOption <key> <value>`	Set options, type can be `right_click` or `left_click`
`/scnpc <id> interact <type> removeOption <key> <value>`	Remove options, type can be `right_click` or `left_click`
`/scnpc <id> setOption <key> <value>`	Set global options
`/scnpc <id> removeOption <key> <value>`	Remove global options
`/scnpc <id> setHologramGroup <groupName>`	Set the Group for the Hologram Placeholders
`/scnpc createInventory <name> <groupName>`	Create a new Inventory Configuration

Permissions

Permission	Description
`simplecloud.command.npc`	For `/scnps` Command

Available Placeholders

You can use the parameters of the current server and the group to which the server belongs as placeholders.

Hologram Placeholders

Placeholder	Description
`<group_name>`	Name of the group
`<group_type>`	Server type (UNKNOWN_SERVER, SERVER, PROXY)
`<group_start_port>`	Start port of the Group
`<group_min_memory>`	Minimum RAM allocation in MB
`<group_max_memory>`	Maximum RAM allocation in MB
`<group_max_players>`	Maximum players per server
`<group_online_count>`	Current players count
`<group_min_online_count>`	Minimum online server count
`<group_max_online_count>`	Maximum online server count
`<group_property:NAME>`	Shows the property value
`<group_player_count:STATE>`	Shows the amount of player count by an Server state
`<group_server_count:STATE>`	Shows the amount of server count by an Server state

Inventory Placeholders

Placeholder	Description
`<id>`	Unique identifier (e.g., "0f0c2d1a-d7d5-4c7f-b7a9-c0e8e9b5a6b8")
`<group_name>`	Name of the group
`<numerical_id>`	Numerical ID within group
`<type>`	Server type (UNKNOWN_SERVER, SERVER, PROXY)
`<state>`	Server state (UNKNOWN_STATE, PREPARING, STARTING, AVAILABLE, INGAME, STOPPING)
`<min_memory>`	Minimum RAM allocation in MB
`<max_memory>`	Maximum RAM allocation in MB
`<ip>`	Server IP address
`<port>`	Server port
`<max_players>`	Maximum players per server
`<online_players>`	Current players count
`<min_online_count>`	Minimum online server count
`<max_online_count>`	Maximum online server count
`<property:NAME>`	Shows the property value
`<player_count:STATE>`	Shows the amount of player count by an Server state
`<server_count:STATE>`	Shows the amount of server count by an Server state

What's Next?

Placeholder Plugin