> ## Documentation Index
> Fetch the complete documentation index at: https://simplecloud.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# NPCs

> Use SimpleCloud's NPC plugin for interactive server navigation and holograms

## Overview

The SimpleCloud NPC plugin adds SimpleCloud actions, holograms, and feedback options to NPCs created by supported NPC plugins. You create the NPC in your NPC system, then use `/scnpc apply <id>` to let SimpleCloud manage interactions for that NPC.

<Warning>
  This plugin requires one supported NPC plugin on the server. The standalone
  namespace module exists in the repository, but the current Paper plugin loads
  third-party namespaces only.
</Warning>

## Supported Software

| Server Type   | Plugin Support |
| ------------- | -------------- |
| Paper & Forks | Yes            |
| Spigot        | No             |

## Supported NPC Plugins

| Plugin                                                | Status    | Notes                             |
| ----------------------------------------------------- | --------- | --------------------------------- |
| [Citizens](https://citizensnpcs.co)                   | Supported | Left and right click interactions |
| [FancyNpcs](https://fancyplugins.de/FancyNpcs)        | Supported | Uses FancyNpcs NPC names as IDs   |
| [MythicMobs](https://www.spigotmc.org/resources/5702) | Supported | Right click interactions          |
| PlayerNPC                                             | Supported | Uses PlayerNPC IDs                |

## Quick Setup

1. Download the SimpleCloud NPC plugin from [GitHub](https://github.com/simplecloudapp/npc-plugin/releases).
2. Install one supported NPC plugin.
3. Make sure the `simplecloud-api` plugin is installed on the server.
4. Place the plugins in your server template's `plugins/` folder.
5. Start the server.
6. Create an NPC with your NPC plugin.
7. Run `/scnpc apply <id>` to create a SimpleCloud NPC config for it.

## Commands

The command is available as `/simplecloudnpc`, `/scnpc`, and `/cloudnpc`.

| Command                                                      | Description                                     |
| ------------------------------------------------------------ | ----------------------------------------------- |
| `/scnpc`                                                     | Show help                                       |
| `/scnpc apply <id>`                                          | Create a SimpleCloud config for an existing NPC |
| `/scnpc <id>`                                                | Show help for one NPC                           |
| `/scnpc <id> setHologramGroup <name>`                        | Set the group used for hologram placeholders    |
| `/scnpc <id> setOption <key> <value>`                        | Set a global player feedback option             |
| `/scnpc <id> getOption <key>`                                | Show a global option value                      |
| `/scnpc <id> removeOption <key>`                             | Remove a global option                          |
| `/scnpc openInventory <name>`                                | Open a configured SimpleCloud NPC inventory     |
| `/scnpc createInventory <name> <groupName>`                  | Create an inventory for a group                 |
| `/scnpc <id> interact <interaction>`                         | Show interaction details                        |
| `/scnpc <id> interact <interaction> setAction <action>`      | Set the action for an interaction               |
| `/scnpc <id> interact <interaction> setOption <key> <value>` | Set an interaction option                       |
| `/scnpc <id> interact <interaction> getOption <key>`         | Show an interaction option                      |
| `/scnpc <id> interact <interaction> removeOption <key>`      | Remove an interaction option                    |

## Permissions

| Permission                | Description          |
| ------------------------- | -------------------- |
| `simplecloud.command.npc` | Use all NPC commands |

## Interactions

The default interaction names are:

* `RIGHT_CLICK`
* `LEFT_CLICK`

<Note>
  A namespace can expose fewer interactions. MythicMobs currently supports
  `RIGHT_CLICK` only.
</Note>

## Actions

| Action                | Required Options           | Description                                          |
| --------------------- | -------------------------- | ---------------------------------------------------- |
| `RUN_COMMAND`         | `command.name`             | Runs a command as the player                         |
| `RUN_CONSOLE_COMMAND` | `command.name`             | Runs a command as console                            |
| `CONNECT_TO_SERVER`   | `server.name`              | Sends the player to a proxy-registered server        |
| `TRANSFER_TO_SERVER`  | `server.ip`, `server.port` | Transfers the player to an external server           |
| `QUICK_JOIN`          | `group.name`               | Finds a server in a group and sends the player there |
| `OPEN_INVENTORY`      | `inventory.name`           | Opens a configured inventory                         |

`RUN_COMMAND` and `RUN_CONSOLE_COMMAND` support `<playername>` and `<playeruuid>` replacements in `command.name`.

### Quick Join Options

| Option                         | Default                       | Description                              |
| ------------------------------ | ----------------------------- | ---------------------------------------- |
| `group.name`                   | Required                      | Group to search                          |
| `server.name.pattern`          | `<group_name>-<numerical_id>` | Server name passed to the proxy          |
| `filter.player.count`          | `LEAST`                       | `LEAST` or `MOST` player count selection |
| `filter.server.state`          | `AVAILABLE`                   | Required server state                    |
| `message.failed.server.finder` | Empty                         | Optional message when no server matches  |

## Feedback Options

Feedback options can be set globally on the NPC or on a specific interaction. They run in addition to the interaction action.

| Option           | Description                    |
| ---------------- | ------------------------------ |
| `send.message`   | Send a chat message            |
| `send.actionbar` | Send an action bar message     |
| `send.title`     | Show a title                   |
| `send.subtitle`  | Show a subtitle                |
| `play.sound`     | Play an Adventure sound key    |
| `sound.volume`   | Sound volume, default `3F`     |
| `sound.pitch`    | Sound pitch, default `2F`      |
| `sound.source`   | Sound source, default `master` |

## NPC Configuration

The generated NPC config stores holograms, interactions, and global options.

```yaml theme={null}
version: "3"
id: "0"

hologramConfiguration:
  placeholderGroupName: "lobby"
  holograms:
    - startHeight: 2.073
      joinState: ""
      lores:
        - text: "<#38bdf8><bold><group_name>"
          billboard: CENTER
          alignment: CENTER
        - text: "waiting for <#a3a3a3><group_player_count:available> players"
          billboard: CENTER
          alignment: CENTER

actions:
  - playerInteraction: LEFT_CLICK
    action: QUICK_JOIN
    options:
      group.name: lobby
      filter.player.count: LEAST
      filter.server.state: AVAILABLE
      server.name.pattern: "<group_name>-<numerical_id>"

  - playerInteraction: RIGHT_CLICK
    action: TRANSFER_TO_SERVER
    options:
      server.ip: demo-server.com
      server.port: "25565"

options:
  send.message: "<#38bdf8>Choose a server"
  play.sound: block.chest.open
  sound.pitch: "2F"
  sound.volume: "3F"
  sound.source: master
```

## Hologram Placeholders

`placeholderGroupName` references the group used for hologram placeholders.

Examples:

* Group placeholder: `<group_name>`
* Group player count placeholder: `<group_player_count:available>`

<Frame>
  <img src="https://github.com/simplecloudapp/branding/blob/main/media/plugin/npcs/npc.png?raw=true" alt="SimpleCloud NPC example with hologram" />
</Frame>