> For the complete documentation index, see [llms.txt](https://donkolia.gitbook.io/minesantum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://donkolia.gitbook.io/minesantum/santumnpc.md).

# SantumNPC

{% embed url="<https://youtu.be/MwLyW4VV08E>" %}

{% embed url="<https://youtu.be/qpno434w3s4>" %}

A powerful plugin designed to intercept Citizens2 NPCs and add advanced logic with conditions, actions, and custom visibility.\
This plugin works perfectly on Paper and requires PlaceholderAPI and Citizens2.

## Required Dependencies

* **Citizens-2.0.41-b4138** (Core for NPC creation and management)
* **bettermodel-3.1.0-paper** (Engine for rendering Blockbench 3D models natively on Paper servers)
* **PlaceholderAPI** (Core for math operations and dynamic conditions)

## Features

* **Infinite Subfolders**\
  You can organize your configuration files into unlimited subdirectories inside the configs folder
* **Real-Time Visibility System**\
  Updates NPC visibility instantly without requiring players to reconnect
* **Action Execution**\
  Execute multiple types of actions when a player interacts with an NPC
* **Dynamic Viewer List**\
  Save players safely using their exact UUID
* **Precise Centered Messages**\
  Calculates exact pixel width for perfect text centering in chat
* **3D Model Integration**\
  Allows you to seamlessly assign `.bbmodel` files from Blockbench directly to any NPC using the BetterModel engine
* **Internal HTTP Resource Pack Server**\
  SantumNPC has a built-in, lightweight HTTP server that automatically hosts the `build.zip` generated by BetterModel and safely delivers it to the clients without requiring external web servers

## Commands and Permissions

Permission for all commands: `santumnpc.admin`

* `/santumnpc reload`\
  Reloads all configuration files and messages
* `/santumnpc viewer set <config_name> <player|@p>`\
  Adds a player to the whitelist of a specific NPC configuration
* `/santumnpc viewer unset <config_name> <player|@p>`\
  Removes a player from the whitelist
* `/santumnpc status <config_name> <true/false>`\
  Enables or disables an NPC configuration in real-time
* `/santumnpc loadresourcepack [player|@p]`\
  Calculates the SHA-1 hash of the BetterModel `build.zip`, generates a unique secure token, and forces the resource pack prompt on the player's screen automatically

All commands feature an intelligent tab-completer that suggests loaded config names and active players

## Configuration Example

* You need create a NPC with Citizens and /npc type ARMOR\_STAND
* Next you must put /citizens save and check the <mark style="background-color:$success;">plugins/Citizens/saves.yml</mark>
* Put "bodyYaw" in 0.0
* Finally /citizens save and confirm

<pre class="language-yaml"><code class="lang-yaml">npc:
  '1':
  ...
      location:
        worldid: c8c5f9ba-5505-4c8a-b449-0b7858de6709
        x: -32.5
        y: 108.0
        z: 259.5
        bodyYaw: 0.0
        pitch: 0.0
        <a data-footnote-ref href="#user-content-fn-1">yaw: 0.0</a>
      type: ARMOR_STAND
  ...
</code></pre>

### Configuration in SantumNPC/configs/example.yml

```yaml
"example_npc":
  enabled: true
  npc_id: 2
  bbmodel_path: "example_model.bbmodel"
  bbmodel_scale: 8.2
  bbmodel_rotation:
    Y: 0
  bbmodel_hitbox: true
  pos1:
    x: -27.5
    y: 123
    z: 258.5
  pos2:
    x: -36.5
    y: 109
    z: 258.5
  visible_conditions:
    - "%player_world% == spawn"
    - "%player_level%+2 != 2"
  actions:
    - "as_console: warp %player_name% Survival"
    - "as_player: warp %player_name% Survival"
    - "as_op: warp %player_name% Survival"
    - "message: &aSending you to Survival"
    - "centered_message: &eYou clicked the NPC"
  actions_conditions:
    - "%player_world% == spawn"
    - "%player_level%+2 != 2"
  actions_conditions_reject:
    - "as_console: say %player_name% failed the requirements"
    - "message: &cYou don't meet the requirements"
  viewer_none_mode: "global_invisible" # Options: global_visible, global_invisible
  viewer_list: none
```

[^1]: Put 0.0


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://donkolia.gitbook.io/minesantum/santumnpc.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.