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

# SantumScript

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

## Overview

SantumScript is a powerful custom scripting plugin for Paper 1.21.\
It allows you to write custom code logic inside `yml` files located in the plugin folder and its subfolders\
The plugin reads these files and translates them into executable actions in your server.\
With full PlaceholderAPI support and mathematical evaluations it gives you total control over what happens when a script is called

## Commands and Permissions

### `/santumscript call <script_name> [args...]`

Triggers a specific script from your scripts folder.\
You can pass unlimited arguments separated by spaces.\
Inside the script these arguments can be used as `%arg_1%` `%arg_2%` and so on

### `/santumscript reload`

Reloads all scripts into memory\
Requires `santumscript admin` permission

## Variables and Placeholders

The system fully supports PlaceholderAPI\
You can use variables like `%player_level%` or `%player_name%` anywhere in your conditions or actions\
You can also use mathematical expressions inside conditions\
The engine will calculate math operations before comparing values

Additionally SantumScript comes with custom dynamic placeholders built-in:

### `%random_min_max%`

Selects a random number between `min` and `max`.\
For example `%random_1_10%` will be replaced by a random number between 1 and 10.

### `%in_radius_<x>_<y>_<z>_<world>_<radius>%`

Checks if the player executing the script is near certain coordinates in a specific world.\
It returns `true` or `false` making it perfect for `if` conditions.\
For example `%in_radius_100_64_100_world_10% == true`

## Logical Operators

When creating conditions you can use the following comparison operators:

* `==` or `=` for equality
* `!=` for inequality
* `>` `<` `>=` `<=` for numeric comparisons

You can combine multiple conditions using logical operators:

* `&&` (AND) means both conditions must be true
* `||` (OR) means at least one condition must be true

## Scripting Syntax

### If ElseIf and Else

You can control the flow using standard conditional blocks

```yaml
if (%player_level% != 1 || %player_world% != mundo && %player_name% == DonKolia){

    "as_op: &6hello %player_name%"
    "message: &6hello %player_name%"

}
elseif (%player_level% >= 1 && %player_name% == DonKolia) {

    "as_console: &6hello %player_name%"

} else {

    "centered_message: &6hello %player_name%"

}
```

### Switch Statements

You can evaluate a single expression and execute blocks based on matching cases.\
You can also use PlaceholderAPI variables inside the `case` strings.

```yaml
switch (%arg_1%) 
{
    case "%player_name%":
        "message: &6hello %player_name%"
        break;
    case "cualquiera":
        "message: &6hello %player_name%"
        break;
    else:
        "message: &6hello %player_name%"
        break;
}
```

## Available Actions

Every line of execution inside your blocks must be surrounded by double quotes.\
The following action prefixes are supported:

* `as_op: <command>` Executes a command granting temporary operator permissions to the player
* `as_console: <command>` Executes a command through the server console
* `as_player: <command>` Forces the player to execute a command
* `message: <text>` Sends a color-formatted message to the player
* `centered_message: <text>` Sends a message mathematically centered in the player chat


---

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