# 🧍‍♀️ NPCs

## NPC Creation

An NPC is a figure standing in your lobby that players can click to be sent somewhere or shown a menu. Nothing external is needed to make one, though a few of the [engines](npc-engines/) do hand the rendering over to another plugin.

Create one with `/plobby createNpc <identifier>` while standing where you want it, then open **Editor > Npcs** to configure it.

## The NPC list

Every NPC you have made is listed here, with its display name and its identifier in brackets. Clicking one opens its own page of settings, covered under [Edit an NPC](#edit-an-npc).

Shift-clicking hands you the NPC as an item instead, which you can then place to move it somewhere else without touching its settings.

<figure><img src="../../.gitbook/assets/npcs/npc-entry.png" alt="" width="563"><figcaption><p>Npcs (Example NPC)</p></figcaption></figure>

## Npc Despawn Range

Unlike everything else here, this one is shared by every NPC rather than set per NPC. It is the distance, in blocks, past which NPCs and their effects stop being shown to a player, and it is found in **Editor > Settings**.

Raising it keeps distant NPCs visible from further away, at the cost of sending more to every player. A busy lobby with many NPCs is where a high value starts to hurt.

<figure><img src="../../.gitbook/assets/settings/npc-despawn-range.png" alt="" width="563"><figcaption><p>Settings (Npc Despawn Range)</p></figcaption></figure>

## Edit an NPC

Clicking an NPC in **Editor > Npcs** opens its own settings. Everything here applies to that one NPC.

### Change Identifier

With this option, you can rename the identifier the plugin uses to tell this NPC apart from the others. It is separate from the display name and never shown to players.

<figure><img src="../../.gitbook/assets/edit-npc/change-identifier.png" alt="" width="563"><figcaption><p>Edit NPC (Change Identifier)</p></figcaption></figure>

> **Danger:**
Anything pointing at the old identifier, such as a command or another NPC's actions, stops working when you change it.

### Change Display Name

With this option, you can change the name shown to players, which appears in the hologram above the NPC. Colour codes and [MiniMessage](../../configurations/languages.md#rich-text-minimessage) tags both work here.

<figure><img src="../../.gitbook/assets/edit-npc/change-display-name.png" alt="" width="563"><figcaption><p>Edit NPC (Change Display Name)</p></figcaption></figure>

### NPC Engine

With this option, you can change what the NPC is actually made of. Seven engines are available: Flying Head, Item, Entity, Citizens, Model Engine, Fancy NPCS and Better Model.

Each has its own settings, covered on [NPC Engines](npc-engines/). An engine whose plugin is missing is marked **Not installed** and cannot be picked.

<figure><img src="../../.gitbook/assets/edit-npc/engine.png" alt="" width="563"><figcaption><p>Edit NPC (NPC Engine)</p></figcaption></figure>

### Edit Idle Animation

With this option, you can add a particle effect that plays around the NPC while it is standing there. Thirteen shapes are available, each with its own particle, colour, offset and density, and an NPC can carry several at once. Its own settings are under [NPC Effects](#npc-effects).

<figure><img src="../../.gitbook/assets/edit-npc/edit-idle-animation.png" alt="" width="563"><figcaption><p>Edit NPC (Edit Idle Animation)</p></figcaption></figure>

### Npc Glow

With this option, you can give the NPC a glowing outline and pick its colour, which is the cheapest way to make one stand out against a busy build. Its own settings are under [Glow](#glow).

<figure><img src="../../.gitbook/assets/edit-npc/npc-glow.png" alt="" width="563"><figcaption><p>Edit NPC (Npc Glow)</p></figcaption></figure>

### Change Scale

With this option, you can make the NPC bigger or smaller than a player.

<figure><img src="../../.gitbook/assets/edit-npc/change-scale.png" alt="" width="563"><figcaption><p>Edit NPC (Change Scale)</p></figcaption></figure>

### Proxy Server

With this option, you can link the NPC to a server on your network. It is what `%proxy_online%` counts in the hologram, and it is picked from a list rather than typed.

<figure><img src="../../.gitbook/assets/edit-npc/proxy-server.png" alt="" width="563"><figcaption><p>Edit NPC (Proxy Server)</p></figcaption></figure>

### Actions

With this option, you can edit what happens when a player clicks the NPC. Every [action type](../../plugin-information/action-types.md) is available, so one NPC can send a player to another server, run a command or open a menu.

* **To another server:** `[PROXY] server_name`
* **To another world:** `[COMMAND] /console; mvtp %player% your_world_name`

<figure><img src="../../.gitbook/assets/edit-npc/actions.png" alt="" width="563"><figcaption><p>Edit NPC (Actions)</p></figcaption></figure>

### Hologram

With this option, you can edit the floating text above the NPC. The plugin has its own hologram system, so no external plugin is needed. Its own settings are under [NPC Hologram](#npc-hologram).

<figure><img src="../../.gitbook/assets/edit-npc/hologram.png" alt="" width="563"><figcaption><p>Edit NPC (Hologram)</p></figcaption></figure>

### Toggle State

With this option, you can hide the NPC from the world without deleting it or losing any of its settings.

<figure><img src="../../.gitbook/assets/edit-npc/toggle-state.png" alt="" width="563"><figcaption><p>Edit NPC (Toggle State)</p></figcaption></figure>

## Glow

A glowing outline is the cheapest way to make one NPC stand out against a busy build. It is set per NPC, from **Npc Glow** inside that NPC's settings, and works on every engine.

### Toggle Glow

Whether the outline is drawn at all. Turning it off keeps the colour you picked, so switching it back on does not need setting up again.

<figure><img src="../../.gitbook/assets/edit-npc-glow/toggle-glow.png" alt="" width="563"><figcaption><p>Glow (Toggle Glow)</p></figcaption></figure>

### Glow Color

Left-click to open a menu of the sixteen colours an outline can use, each shown as the dye that matches it, then left-click one to apply it. A colour the plugin does not recognise falls back to white.

> **Info:**
The outline is coloured by the client, so it is always one flat colour out of those sixteen. Hex codes and gradients do not apply here.

## NPC Effects

An effect is a shape drawn in particles around an NPC while it stands there. It is set per NPC, from **Edit Idle Animation** inside that NPC's settings, and works on every [engine](npc-engines/).

### Stacking effects

An NPC holds a list of effects rather than one, and every effect in the list is drawn at the same time. That is how the default NPC gets its look: a red dust ring, a ring of flame above it and a slow smoke star around both.

Left-click in the effects menu to add one, and left-click an existing effect to change it.

### Effect Type

The shape the particles are drawn in. Thirteen are available.

| Effect               | Shape                                                        |
| -------------------- | ------------------------------------------------------------ |
| Default              | A flat ring around the NPC                                   |
| Circle               | A circle drawn point by point                                |
| Square               | A square outline                                             |
| Diamond              | A diamond outline                                            |
| Star                 | A five-pointed star                                          |
| Ninja Star           | A four-pointed star                                          |
| Flower               | A rounded petal shape                                        |
| Quatrefoil           | A four-lobed clover                                          |
| Deltoid              | A three-cusped curve                                         |
| Astroid              | A four-cusped curve, pinched at the corners                  |
| Spiral               | A spiral climbing the NPC                                    |
| Conical Spiral       | A spiral that widens as it climbs, like a cone               |
| Pulse                | A ring that grows outwards and restarts                      |

### Particle

The particle the shape is drawn with, such as `FLAME`, `REDSTONE` or `SMOKE_NORMAL`. A particle your server version does not have simply does not appear.

### Color

Only some particles are coloured by the game. `REDSTONE` and the other dust particles take the colour you set here; the rest ignore it and keep their own look, so a flame stays orange whatever you pick.

### Offset

`offset-x`, `offset-y` and `offset-z` move the effect relative to the NPC. The one used most is offset-y, which lifts the shape up or down — the default NPC uses it to put one ring at its feet and another at its head.

### Spread

How far the particles are scattered from the exact point of the shape. Left at 0 the shape is drawn cleanly; raising it blurs the outline into a cloud.

### Velocity

How fast the particles drift once they appear. At 0 they sit still, which is what keeps a shape readable. On dust particles this value is read as their size instead, so a small number there makes finer dust.

### Amount

How many particles are drawn per step of the shape. Raising it makes the shape denser and heavier on the client, so keep it low on a lobby that holds a lot of NPCs.

> **Info:**
Effects stop being drawn past the **Npc Despawn Range** in **Editor > Settings**, the same distance that hides the NPCs themselves.

<details>

<summary>An effect in the NPC file</summary>

Each NPC has its own file in the **npcs** folder, and its effects are a list under `effects`.

```yaml
effects:
- DEFAULT;{REDSTONE;#ff0000;0.0;0.0;0.0;1.0;0.1;2}
- DEFAULT;{FLAME;#ffffff;0.0;0.0;0.0;2.0;0.1;2}
- STAR;{SMOKE_NORMAL;#ffffff;0.0;0.0;0.0;0.0;0.0;2}
```

The effect type comes first, and the braces hold the rest in order: the particle, the colour, the X, Y and Z offset, the spread, the velocity and the amount.

</details>

## NPC Hologram

The floating text above an NPC. The plugin has its own hologram system, so no external plugin is needed, and the look is set per NPC so every one can have its own style. PhoenixHolograms can draw it instead, see [Hologram Engine](../holograms/#hologram-engine).

This is the hologram attached to an NPC. For text that stands on its own anywhere in the world, see [Holograms](../holograms/).

### Lines

The text itself, one entry per line. `%proxy_online%` shows how many players are on the server picked under **Proxy Server**, vanished staff excluded, and PlaceholderAPI placeholders work too.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/hologram.png" alt="" width="563"><figcaption><p>Hologram (Hologram)</p></figcaption></figure>

### Height Offset

Raises or lowers the whole hologram relative to the NPC.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/height-offset.png" alt="" width="563"><figcaption><p>Hologram (Height Offset)</p></figcaption></figure>

### Line Gap

The space left between two lines.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/line-gap.png" alt="" width="563"><figcaption><p>Hologram (Line Gap)</p></figcaption></figure>

### Billboard

How the text turns to face the player, whether it follows them fully, only horizontally, or stays fixed.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/billboard.png" alt="" width="563"><figcaption><p>Hologram (Billboard)</p></figcaption></figure>

### Hologram Scale

How large the text is drawn.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/hologram-scale.png" alt="" width="563"><figcaption><p>Hologram (Hologram Scale)</p></figcaption></figure>

### Text Opacity

How solid the text is, from barely there to fully opaque.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/text-opacity.png" alt="" width="563"><figcaption><p>Hologram (Text Opacity)</p></figcaption></figure>

### Background Color

The colour of the panel drawn behind the text.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/background-color.png" alt="" width="563"><figcaption><p>Hologram (Background Color)</p></figcaption></figure>

### See Through

Whether the text stays visible through blocks.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/see-through.png" alt="" width="563"><figcaption><p>Hologram (See Through)</p></figcaption></figure>

### Shadow

Whether a shadow is drawn behind the text.

<figure><img src="../../.gitbook/assets/edit-npc-hologram/shadow.png" alt="" width="563"><figcaption><p>Hologram (Shadow)</p></figcaption></figure>

> **Info:**
If the editor is awkward for a long hologram, each NPC is also a file of its own in the **npcs** folder and can be edited there.

Source: https://www.phoenixplugins.com/docs/phoenix-lobby/featues/npcs