> 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/santumconversations.md).

# SantumConversations

{% embed url="<https://youtu.be/lM1D5-uHaFg?si=ldn1YdO77Q-QCgpP>" %}

A customizable YAML-based conversation system for Paper 1.21.8, designed to replace and enhance standard NPC interactions

Author: DonKolia

## Features

* **Custom YAML Configuration**: Define conversations in easy-to-read YAML files
* **Recursive Loading**: Organize your conversations in subfolders within `plugins/SantumConversations/conversations/`
* **Advanced Conditions**: Support for all standard comparison operators (`==`, `!=`, `>=`, `<=`, `>`, `<`) for both numbers and strings
* **PlaceholderAPI Support**: Fully integrated with PlaceholderAPI for dynamic text and conditions
* **Math Operations**: You can use math directly in placeholders, for example `%player_level%+2 == 50` or `%variable%/5`, and the plugin will calculate it automatically anywhere
* **Interactive Chat**: Clickable responses for players in the chat
* **Menu Interceptor**: Immersive conversation mode
  * **W / S**: Scroll through options
  * **Shift (Sneak)**: Select the highlighted option
  * **Space (Jump)**: Exit the conversation
* **Native UI Dialogs**: Set `mode: "ui"` to use the new Native Paper 1.21.8 Dialog menus It displays the text clearly and adds buttons for each response, respecting condition visibility
  * **ESC Key Support**: Players can simply press the ESC key to exit the dialog UI flawlessly
* **Subfolder System**: Create subfolders to organize your conversations
* **Action System**: Execute commands when a player selects a response
  * `[as_op] <command>`: Execute as OP
  * `[as_player] <command>`: Execute as the player
  * `[as_console] <command>`: Execute from the console

<figure><img src="/files/tKbCkrPK7s7YByUtGjuE" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/FvYBUxUxjL8KqAzDF1X0" alt=""><figcaption></figcaption></figure>

## Installation

{% stepper %}
{% step %}
Download the `SantumConversations.jar` file
{% endstep %}

{% step %}
Place it in your server's `plugins` folder
{% endstep %}

{% step %}
Ensure you have [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) installed
{% endstep %}

{% step %}
**IMPORTANT**: You must have `packetevents-spigot-2.9.3.jar` installed on your server
{% endstep %}

{% step %}
Restart your server
{% endstep %}
{% endstepper %}

## Configuration

Conversations are located in `plugins/SantumConversations/conversations/` You can create any folder structure you desire

### Conversation Example (`simplename.yml`)

```yaml
simplename:
  quester: "NPC Name"
  first: "Welcome" # Optional: Explicitly define the starting option
  mode: "ui" # You can use "ui" for Native Dialogs or "chat" for regular text
  NPC_options:
    "Welcome":
      ask: "How are you today %player_name% %player_level%+2?"
      ask_conditions:
        - "%player_name% == DonKolia"
        - "%player_level%+2 == 50"
      no_requirements_message: "You cannot talk to me &b%player_name%+4"
      answers:
        - text: "I'm doing great, thanks %player_name% %player_level%+2"
          next_ask: "Where are you?"
          answer_conditions:
            - "%player_level% >= 50"
        - text: "Give me experience"
          actions:
            - "[as_op] xp set %player_name% 50 levels"
          next_ask: null
    "Where are you?":
      ask: "Where are you? I can't find you"
      answers:
        - text: "I'm in the castle"
          answer_conditions:
            - "%player_level% >= 50"
          actions:
            - "[as_console] say %player_name% is in the castle"
          next_ask: "Okay"
    "Okay":
      ask: "Understood"
      answers:
        - text: "Goodbye"
          next_ask: null
```

## Commands

| Command                                           | Description                                             | Permission                   |
| ------------------------------------------------- | ------------------------------------------------------- | ---------------------------- |
| `/santumconversations reload`                     | Reloads all conversations and configuration             | `santumconversations.reload` |
| `/santumconversations reload <name>`              | Reloads a specific conversation (currently reloads all) | `santumconversations.reload` |
| `/santumconversation set <conversation> <player>` | Starts a conversation for a player                      | `santumconversations.set`    |

## Permissions

* `santumconversations.reload`: Allows reloading the plugin
* `santumconversations.set`: Allows starting conversations for players


---

# 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/santumconversations.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.