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

# Overview

> Modular combat abilities, world events, and party trust mechanics for modern Minecraft servers.

**SentryPremades** is an ability and event engine built to bring custom combat mechanics, projectile spells, and environmental skills to Paper, Purpur, and modern Minecraft servers without scripting headaches.

Rather than wrestling with hundreds of lines of fragile script syntax, SentryPremades provides production-grade abilities out of the box. Each premade comes with physics, particle effects, directional sounds, and damage calculations ready for server networks.

***

## Why SentryPremades?

> **Pre-Built Mechanics**
>
> Access balanced abilities (like fiery projectiles, cryogenic dashes, and toxic sky barrages) crafted for competitive and RPG servers.

> **Ecosystem Ready**
>
> Bind abilities directly to custom items via **ItemsAdder** or **Nexo**, or cast them from bosses using **MythicMobs**.

> **Dynamic Math Engine**
>
> Write clean mathematical expressions anywhere in your configuration files, such as `duration: 3 * 20` for tick conversions.

> **Built-In Trust Protection**
>
> Protect teammates and faction allies from friendly fire with the integrated player trust system.

***

## How It Works in 3 Simple Steps

**1. 1. The Core Engine (SentryPremades)**

Runs silently in the background handling projectile physics, damage calculations, and friendly-fire protection.

**2. 2. The Ability Packs (e.g. Overcharge)**

Provides the actual skills, such as `flaming-shot`, `freezing-dash`, or `poisoning-rain`, complete with particle rings, directional audio, and damage values.

**3. 3. The In-Game Triggers**

You bind those skills directly to custom weapons (e.g. right-click in `itemsadder.yml` or `nexo.yml`) or assign them to dungeon bosses in MythicMobs.

### 1. Abilities

Abilities are active skills tied to an entity or player. When cast, they calculate trajectories, spawn particle animations, play audio cues, and deal damage or status effects.

* **Caster Awareness:** Abilities know who triggered them and apply damage attribution correctly.
* **Trust Checks:** Before damaging a player, abilities query the trust system to prevent harming allies.
* **Preset Customization:** Every ability supports multiple configuration presets (e.g., `default`, `low-damage`, `hardcore`), letting you tune stats per rank or item tier.

### 2. Events

Events are environmental phenomena tied to world locations. Unlike single-target abilities, events affect entire areas regardless of whether a player or an automated system triggered them (e.g., localized meteor strikes or arena hazards).

***

## Mathematical Formula Engine

Tired of having to calculate tick timings or complex multipliers by hand? SentryPremades includes a built-in mathematical expression engine powered by `exp4j`.

Any configuration field that accepts numbers or durations can evaluate standard arithmetic formulas:

```yaml theme={null}
# 3 seconds converted to Minecraft ticks
duration: 3 * 20

# Scaled knockback velocity
push-speed: 1.2 * 1.5

# Custom density calculation
particle-density: 2 / 2
```

This makes configuration files readable, self-documenting, and easy to balance without needing external calculators.

***

## Integrated Trust System

Combat abilities that deal area-of-effect damage can often ruin team play if they hit friends. SentryPremades solves this with a built-in **Trust System**:

* Players can manage their own trusted allies using `/premades trust add <player>`.
* When an ability with area-of-effect damage or status effects detonates, it automatically checks if nearby players are trusted by the attacker.
* If a player is trusted, damage, knockback, and negative status effects are automatically bypassed.
* Trust lists persist across server reboots via your choice of local storage (`yaml:trustlists.yml`) or external databases.

***

## Next Steps

> **[Installation](https://docs.sentrystudios.org/sentry-premades/installation.md)**
>
> Install SentryPremades using the one-click Auto-Installer or manual setup.

> **[Commands & Trust](https://docs.sentrystudios.org/sentry-premades/commands-and-trust.md)**
>
> Master administrative commands, reload modules, and configure trust lists.

> **[Overcharge Addon](https://docs.sentrystudios.org/sentry-premades/addons/overcharge.md)**
>
> Explore the Overcharge Premade suite featuring Flaming Shot, Freezing Dash, and Poisoning Rain.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.