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

# NPCs

> Learn about SimpleCloud's NPCs plugin for interactive server navigation and management

## Overview

The SimpleCloud NPCs plugin allows you to create interactive NPCs on your server that enable players to access other subservers and perform various actions.

<Warning>
  This plugin requires a supported third-party NPC plugin such as Citizens or
  FancyNpcs to function. The SimpleCloud NPCs plugin adds SimpleCloud
  functionality to NPCs created by these third-party plugins.
</Warning>

## Supported Software

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

## Quick Setup

1. Download the SimpleCloud NPCs plugin from [GitHub](https://github.com/simplecloudapp/npc-plugin/releases)
2. Download and install one of the supported NPC plugins (e.g., Citizens)
3. Place both plugins in your server's plugins folder
4. Start your server
5. Create an NPC using the third-party plugin's commands
6. Use the SimpleCloud NPCs commands to add SimpleCloud functionality to the created NPC

## Required NPC Plugins

You must install one of the following NPC plugins for the SimpleCloud NPCs plugin to work:

| Plugin                                                | Supported Versions | Status |
| ----------------------------------------------------- | ------------------ | ------ |
| [Citizens](https://citizensnpcs.co)                   | 1.19+              | ✅ Yes  |
| [FancyNpcs](https://fancyplugins.de/FancyNpcs)        | 1.19.4+            | ✅ Yes  |
| [MythicMobs](https://www.spigotmc.org/resources/5702) | 1.19+              | ✅ Yes  |
| [PlayerNPC](https://www.spigotmc.org/resources/93625) | 1.17.1 - 1.20.1    | ❌ No   |

<Note>
  Want to add support for another NPC plugin? Submit an issue on
  [GitHub](https://github.com/simplecloudapp/npc-plugin/pulls)!
</Note>

## Actions

Available NPC actions and their options:

| Action                | Option                                                                    | Description                     |
| --------------------- | ------------------------------------------------------------------------- | ------------------------------- |
| `open_inventory`      | inventory.name                                                            | Open server selection inventory |
| `run_command`         | command.name                                                              | Execute player command          |
| `run_console_command` | command.name                                                              | Execute console command         |
| `connect_to_server`   | server.name                                                               | Send player to server           |
| `transfer_to_server`  | server.ip, server.port                                                    | Send to external server         |
| `quick_join`          | group.name, server.name.pattern, filter.player.count, filter.server.state | Random server join              |

## NPC Configuration

Example configuration:

```yaml theme={null}
version: "3"
id: "0"
npc-type: GROUP

hologram-configuration:
  placeholder-name: lobby
  holograms:
    - start-height: 2.073
      join-state: ""
      lores:
        - text: "<#38bdf8><bold><group_name>"
          billboard: CENTER
          alignment: CENTER
        - text: "waiting for <#a3a3a3><group_player_count:available> players"
          billboard: CENTER
          alignment: CENTER

actions:
  - player-interaction: LEFT_CLICK
    action: OPEN_INVENTORY
    options:
      inventory.name: lobby
      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

options:
  send.message: "<rainbow>Some cool text here"
  send.title: "title"
  send.subtitle: "some cool subtitle"
```

### Feedback Options

| Option           | Description        |
| ---------------- | ------------------ |
| `send.message`   | Chat message       |
| `send.actionbar` | Action bar message |
| `send.title`     | Title message      |
| `send.subtitle`  | Subtitle message   |
| `play.sound`     | Sound effect       |

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

## Inventory Configuration

Example inventory for server selection:

```yaml theme={null}
version: "3"
id: lobby
npc-type: GROUP
title: "<#ffffff>Lobbys"
rows: 6

pagination:
  listed-group-name: lobby
  listed-persistent-servers: []
  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"
    lores: []

  - id: previous_pagination_item
    material: LIME_STAINED_GLASS_PANE
    display-name: "<green>Previous Page"
    lores: []

  - id: red_next_pagination_item
    material: RED_STAINED_GLASS_PANE
    display-name: "<red>Next Page"
    lores: []

  - id: red_previous_pagination_item
    material: RED_STAINED_GLASS_PANE
    display-name: "<red>Previous Page"
    lores: []

  - id: starting_pagination_item
    material: ORANGE_BANNER
    display-name: "<group_name> <numerical_id>"
    lores: []

  - id: available_pagination_item
    material: LIME_BANNER
    display-name: "<group_name> <numerical_id>"
    lores:
      - "<gray>Players: <#38bdf8><online_players><dark_gray>/<#38bdf8><max_players>"

  - id: ingame_pagination_item
    material: BROWN_BANNER
    display-name: "<group_name> <numerical_id>"
    lores: []
```

<Frame>
  <img src="https://github.com/simplecloudapp/branding/blob/main/media/plugin/npcs/inventory.png?raw=true" alt="Inventory Example" />
</Frame>

## Commands

| Command                                                            | Description                                        |
| ------------------------------------------------------------------ | -------------------------------------------------- |
| `/scnpc apply <id>`                                                | Apply NPC functions to an existing NPC             |
| `/scnpc <id> setType <type>`                                       | Set the NPC type                                   |
| `/scnpc <id> setHologram <name>`                                   | Set the NPC hologram                               |
| `/scnpc <id> setOption <key> <value>`                              | Set a global NPC option                            |
| `/scnpc <id> getOption <key>`                                      | Get a global NPC option                            |
| `/scnpc <id> removeOption <key>`                                   | Remove a global NPC option                         |
| `/scnpc <id> interact <playerInteraction>`                         | Show interaction configuration                     |
| `/scnpc <id> interact <playerInteraction> setAction <action>`      | Set an interaction action                          |
| `/scnpc <id> interact <playerInteraction> setOption <key> <value>` | Set an interaction option                          |
| `/scnpc <id> interact <playerInteraction> getOption <key>`         | Get an interaction option                          |
| `/scnpc <id> interact <playerInteraction> removeOption <key>`      | Remove an interaction option                       |
| `/scnpc openInventory <name>`                                      | Open an NPC inventory                              |
| `/scnpc createInventory <name> group <group>`                      | Create an inventory for a group                    |
| `/scnpc createInventory <name> persistent <server>`                | Create an inventory for persistent servers         |
| `/scnpc addInventoryPersistentServer <name> <server>`              | Add a persistent server to an persistent inventory |

## Permissions

| Permission                | Description        |
| ------------------------- | ------------------ |
| `simplecloud.command.npc` | Access to `/scnpc` |