# Configuration
Source: https://wiki.lorenzo0111.me/configsync/configuration

Learn how to configure the plugin

## Scheduler

The scheduler is a task that is automatically scheduled to sync every file every 5 minutes. You can enable and disable it from the configuration file on line 13, the option is named `scheduler`.

## MySQL

The mysql section contains all the data of the database storage. As explained in the configuration, the main server is the one where the files are copied from.

<Note>
  Don't include the port with your host address, you need to adjust it with the port option.
</Note>

Default values are:

```yaml theme={null}
mysql:
  # The main server is the server from the configs are copied
  main: true
  # Database information
  ip: localhost
  port: 3306
  username: "root" #CHANGE THIS TO YOUR DATABASE USER!
  password: "" #CHANGE THIS TO YOUR PASSWORD!
  database: "configsync"
```

## Files

The file section is a list of files to sync. It requires the following schema:

```yaml theme={null}
files:
  Plugin:
    - "file.yml"
```

Replace `Plugin` with the name of the plugin that contains the file that you want to sync.

### Example

For example, if you want to sync the `config.yml` of a plugin called `BedwarsX`:

```yaml theme={null}
files:
  BedwarsX:
    - "config.yml"
```

### Syncing All Files

Add as many files as you want. Instead of the file name you can just put `*` to sync all the files of a plugin.

```yaml theme={null}
files:
  BedwarsX:
    - "*"
```


# Getting Started
Source: https://wiki.lorenzo0111.me/configsync/getting-started

Learn how to install and set up ConfigSync

## Buying the plugin

The first thing to do is buying the plugin. You can purchase it on:

* [SpigotMC](https://www.spigotmc.org/resources/103552/)
* [BuiltByBit](https://builtbybit.com/resources/configsync.24276/)

## Installing the plugin

The plugin doesn't require any other plugin, you only need to put it into your `/plugins/` folder and fill in your MySQL details.

<Warning>
  Remember to read our [Terms of Service](/configsync/tos).
</Warning>

## Next Steps

After installing the plugin, you'll need to:

1. Configure your MySQL database connection
2. Set up the files you want to sync
3. Configure the scheduler settings

Check out the [Configuration](/configsync/configuration) guide for detailed instructions.


# Terms Of Service
Source: https://wiki.lorenzo0111.me/configsync/tos

Terms of Service for ConfigSync

By purchasing ConfigSync, you agree to the following Terms of Service:

* You have authorization to use the debt/credit card and/or paypal account
* You will not chargeback, dispute, or reverse any payments
* You will not decompile or modify the resource
* You will not redistribute the resource or any of its contents
* I may revoke your access to the resource if you violate any of the terms above
* The plugin may stop working if you violate the terms above
* I reserve the right to change these terms at any time and you agree to abide by the most recent version of the terms
* You agree to everything listed above and below

***

<Warning>
  **NO REFUNDS WILL BE GRANTED**
</Warning>


# Commands
Source: https://wiki.lorenzo0111.me/electionsplus/commands

All available commands in ElectionsPlus

## Available Commands

Here's a complete list of all commands available in ElectionsPlus.

### Create Election

```bash theme={null}
/elections create <name>
```

Create a new election with an interactive menu that makes setup easy.

**Permission:** `elections.create`

***

### Disband Party

```bash theme={null}
/elections disband <name>
```

Delete a political party.

<Note>
  This is an admin command and should only be given to trusted staff members.
</Note>

**Permission:** `elections.disband`

***

### List Elections

```bash theme={null}
/elections list
```

Display a list of all elections on the server.

**Permission:** `elections.list`

**Sub-Permissions:**

* `elections.edit` - Allows editing an election

***

### Parties

```bash theme={null}
/elections parties
```

Display a list of all political parties on the server.

**Permission:** `elections.parties`

**Sub-Permissions:**

* `elections.party.create` - Allows creating a new party
* `elections.party.icon` - Allows setting a base64 image as party icon

***

### Reload

```bash theme={null}
/elections reload
```

Reload the plugin configuration and data.

**Permission:** `elections.reload`

***

### Vote

```bash theme={null}
/elections vote [name]
```

Vote for a party using an interactive GUI.

If you specify a `[name]`, you will vote in that specific election. If no name is provided, you'll see all available elections.

**Permission:** Not specified (available to all players by default)

## Permission Summary

| Permission               | Description      | Default |
| ------------------------ | ---------------- | ------- |
| `elections.create`       | Create elections | OP      |
| `elections.disband`      | Disband parties  | OP      |
| `elections.list`         | List elections   | All     |
| `elections.edit`         | Edit elections   | OP      |
| `elections.parties`      | View parties     | All     |
| `elections.party.create` | Create parties   | All     |
| `elections.party.icon`   | Set party icon   | All     |
| `elections.reload`       | Reload plugin    | OP      |


# Configuration
Source: https://wiki.lorenzo0111.me/electionsplus/configuration

Configure ElectionsPlus to suit your server's needs

## How to Configure ElectionsPlus

ElectionsPlus can be configured through the main configuration file. Below are the available options:

## Database

The database is where the plugin stores all information about elections, parties, and votes.

### Type

The type of database to use. You can choose between:

* `SQLITE` - Local file-based database (default, easiest to set up)
* `MYSQL` - MySQL database server
* `REDIS` - Redis database

<Warning>
  REDIS is currently not ready and cannot be used at this time.
</Warning>

## Join Notification

Enable or disable notifications for players when they join the server and an election is open.

You can customize the notification message in `messages.yml` using the `join` key.

## Escape Word

When creating an election or a party, the plugin will ask for information via chat. If you want to cancel the current prompt, you can type the escape word in chat.

Configure this word in the config file to match your preference.

## Cache Duration

The cache duration controls how often the plugin refreshes its cached data from the database.

For example, if set to `5`, every 5 minutes the plugin will clear and recreate the cache with all database values.

<Info>
  The cache doesn't significantly affect server performance, so you can adjust it based on your needs.
</Info>

### How Cache Affects PlaceholderAPI

The [PlaceholderAPI](/electionsplus/placeholderapi) expansion uses the plugin's cache. The longer the cache duration, the more outdated the data in placeholders might be.

**Default value:** 5 minutes

<Warning>
  The plugin automatically adds 1 minute to your configured duration. If you set `5`, the actual duration will be `6` minutes.
</Warning>

## MiniMessage Support

ElectionsPlus supports MiniMessage formatting for all messages. Learn more about MiniMessage syntax in the [official documentation](https://docs.adventure.kyori.net/minimessage.html#format).


# Getting Started
Source: https://wiki.lorenzo0111.me/electionsplus/getting-started

Welcome to the official ElectionsPlus documentation

<img alt="ElectionsPlus Logo" />

## Welcome to ElectionsPlus

ElectionsPlus is a plugin that adds democracy to your Minecraft server. Create elections, manage political parties, and let your players vote!

## Quick Links

<CardGroup>
  <Card title="Installation" icon="download" href="/electionsplus/installation">
    Get started with installing ElectionsPlus
  </Card>

  <Card title="Configuration" icon="gear" href="/electionsplus/configuration">
    Configure the plugin to your needs
  </Card>

  <Card title="Commands" icon="terminal" href="/electionsplus/commands">
    Learn about available commands
  </Card>

  <Card title="PlaceholderAPI" icon="code" href="/electionsplus/placeholderapi">
    Integrate with PlaceholderAPI
  </Card>
</CardGroup>

## Support

If you need help or have questions, join our [Discord server](https://to.lorenzo0111.me/discord).


# Installation
Source: https://wiki.lorenzo0111.me/electionsplus/installation

Learn how to install ElectionsPlus on your server

## \[1] Download the Plugin

To get started, you will need to [download](https://www.spigotmc.org/resources/electionsplus-add-democracy-to-your-server.93463/) the plugin from the SpigotMC homepage.

<Steps>
  <Step title="Download the plugin">
    Visit the [SpigotMC page](https://www.spigotmc.org/resources/electionsplus-add-democracy-to-your-server.93463/) and download the latest version of ElectionsPlus.
  </Step>

  <Step title="Place in plugins folder">
    Simply drag and drop the downloaded JAR file into your server's `plugins` folder.

    <Info>
      If you're using a server hosting website, the process should be similar except you should be navigating through an FTP client.
    </Info>
  </Step>

  <Step title="Start / Restart Your Server">
    Simply initiate a restart or boot up your server for the plugin to be installed and loaded.
  </Step>
</Steps>

## Next Steps

After installation, you should:

* Configure the plugin according to your needs - see [Configuration](/electionsplus/configuration)
* Learn about available commands - see [Commands](/electionsplus/commands)
* Set up PlaceholderAPI integration - see [PlaceholderAPI](/electionsplus/placeholderapi)


# PlaceholderAPI
Source: https://wiki.lorenzo0111.me/electionsplus/placeholderapi

Integrate ElectionsPlus with PlaceholderAPI

## Installation

To use ElectionsPlus placeholders, you need to install the PlaceholderAPI expansion.

<Steps>
  <Step title="Install PlaceholderAPI">
    Make sure you have [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) installed on your server.
  </Step>

  <Step title="Download the expansion">
    Run the following command in your server console or as an operator:

    ```bash theme={null}
    /papi ecloud download electionsplus
    ```
  </Step>

  <Step title="Load the expansion">
    After downloading, reload PlaceholderAPI or restart your server to load the expansion.
  </Step>
</Steps>

## Available Placeholders

Use these placeholders in any plugin that supports PlaceholderAPI:

### General Placeholders

| Placeholder         | Description                                     | Example Output    |
| ------------------- | ----------------------------------------------- | ----------------- |
| `%elections_open%`  | The number of elections that are currently open | `3`               |
| `%election_isopen%` | Whether there is at least one election open     | `true` or `false` |

### Election-Specific Placeholders

| Placeholder                    | Description                                                                  | Example Output    |
| ------------------------------ | ---------------------------------------------------------------------------- | ----------------- |
| `%elections_isopen_<name>%`    | Whether a specific election is open. Replace `<name>` with the election name | `true` or `false` |
| `%elections_voted_<election>%` | Whether the player has voted in a specific election                          | `true` or `false` |

## Usage Examples

<CodeGroup>
  ```yaml Scoreboard (DeluxeMenus) theme={null}
  menu_title: 'Elections'
  rows: 3
  items:
    status:
      material: PAPER
      slot: 13
      display_name: '&aElection Status'
      lore:
        - '&7Open Elections: &e%elections_open%'
        - '&7Presidential Open: &e%elections_isopen_presidential%'
        - '&7You voted: &e%elections_voted_presidential%'
  ```

  ```yaml Chat (EssentialsX) theme={null}
  format: '{DISPLAYNAME} &8[&e{elections_voted_presidential}&8]&r: {MESSAGE}'
  ```

  ```yaml Tab List theme={null}
  header:
    - '&6&lElection Server'
    - '&7Open Elections: &e%elections_open%'
  footer:
    - '&7Vote now using /elections vote'
  ```
</CodeGroup>

## Cache Notice

<Info>
  PlaceholderAPI expansions use the plugin's cache system. The cache duration can be configured in the main config file. See [Configuration](/electionsplus/configuration#cache-duration) for more details.
</Info>


# Using Addons
Source: https://wiki.lorenzo0111.me/farms/addons

Learn how to configure and use optional addons with Farms

## WorldGuard

```yaml theme={null}
worldguard:
  enabled: true
```

## Vault

With this settings you can edit the price of a farm and of a Level Up.

```yaml theme={null}
vault:
  enabled: true
  price: 1
  # The math expression will be newLevel * levelUp
  # For example if you set to 100 the levelUp price to level 5 will be 500
  levelUp: 100
```


# Configuration
Source: https://wiki.lorenzo0111.me/farms/configuration

Learn how to configure the plugin

## Setting materials

Minecraft has different ids for placeable and placed material, you'll have to tell to the plugin the mutation schema of your items.

For example the id of the placeable carrot is "CARROT", the id of the palced is "CARROTS".

If you need help you can join our [discord](https://discord.io/RocketPlugins) server and our moderators will help you setting up the schema.

If you don't put an item in the `items` list it won't work.

## Editing levels

You can edit levels with the levels configuration.

```yaml theme={null}
# Percent for each level of how many blocks should it break
# You can't add or remove levels
# Example: There are 7 blocks to mine, it will mine only the 15% of them at level 1
levels:
  1: 15.0
  2: 20.0
  3: 35.0
  4: 40.0
  5: 50.0
```

## Editing tasks

Tasks are the main function of the plugin, they are used to make the minions work.
Default values are very good but you can increase/decrease them.

<Warning>
  Decreasing tasks duration may cause lag.
</Warning>

```yaml theme={null}
tasks:
  grow: 5
  collect: 10
```

### Grow Task

The grow task is used to increase crops growing speed, if you use it for blocks it won't be used.

### Collect Task

The collect task is used to break and collect items.


# Installation
Source: https://wiki.lorenzo0111.me/farms/installation

Learn how to install Farms and its optional addons

## Buying the plugin

The first thing to do is buying the plugin. You can do this just hitting the buy plugin on SpigotMC.

## Installing the plugin

The plugin doesn't require any other plugin, so the only thing to do is to drag the plugin jar in your plugins folder.

## Installing the *optional* addons

### WorldGuard

If you install worldguard and you [enable](/farms/addons) it, farms will use it to check if player can build in a zone.

### Vault

If you install vault and you [enable](/farms/addons) it, farms will use it to manage economy, you will also need an economy provider, for example [EssentialsX](https://essentialsx.net/downloads.html).

<Warning>
  Remember to read our [Terms of Service](/farms/tos).
</Warning>


# Permissions
Source: https://wiki.lorenzo0111.me/farms/permissions

All available permissions for the Farms plugin

## All Permissions

* `farms.admin` - Gives you access to all the admin functions.
* `farms.create` - Allows you to create a farm.
* `farms.list` - Allows you to list all the farm types.
* `farms.gui` - Allows you to open a GUI with all the farms.
* `farms.remove.all` - Allows you to remove all the existing farms.
* `farms.reload` - Gives you access to the reload command.
* `farms.give` - Allows you to give the farm item to a player.


# Terms of Service
Source: https://wiki.lorenzo0111.me/farms/tos

Terms of Service for the Farms plugin

By buying this plugin you accept the following terms.

* The plugin collects anonymous data for [bStats](https://bstats.org).
* You are not allowed to distribute the product. This applies both to the binaries or any sources.
* Trying to decompile the product is not allowed.
* The product can be used from a maximum of 2 ip address, unless express authorization is given by the author.
* Refunds will not be given unless under special circumstances determined by the author.


# Configuration
Source: https://wiki.lorenzo0111.me/multilang/configuration

Complete guide to configuring MultiLang, including storage options, languages, and translation strings

# Configuration

This guide covers all configuration options available in MultiLang.

## Configuration File

The main configuration file is located at `plugins/MultiLang/config.yml`.

## Configuration Options

Every title in the config represents a config option. Here's what each option does:

### prefix

The plugin prefix shown in all messages. All messages have this prefix at their start.

**Example:**

```yaml theme={null}
prefix: "&9MultiLang &8»&r"
```

### storage

The storage type for player language preferences.

**Options:**

* `MYSQL` - Store languages in MySQL database (synchronizes across servers)
* `FILE` - Store languages in local files

**Example:**

```yaml theme={null}
storage: MYSQL
```

<Info>
  If you don't have a MySQL server, you can use FILE storage. If you choose MySQL, you can synchronize player languages across multiple servers.
</Info>

### mysql

MySQL database settings. Only required if `storage: MYSQL`.

**Configuration:**

```yaml theme={null}
mysql:
  host: "localhost"
  port: 3306
  database: "multilang"
  username: "root"
  password: "yourpassword"
```

<Info>
  If you choose FILE storage, you don't need to configure MySQL settings.
</Info>

### default

The default language for players who haven't selected a language yet.

**Example:**

```yaml theme={null}
default: "english"
```

### default-base

Default language base64 for the GUI. See the [GUI guide](/multilang/gui) for more information.

**Example:**

```yaml theme={null}
default-base: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
```

### languages

List of all languages that players can select.

**Example:**

```yaml theme={null}
languages:
  english: "en_us"
  italiano: "it_it"
  español: "es_es"
  français: "fr_fr"
  deutsch: "de_de"
```

#### How does autodetect work?

You need to put the Locale code of that language. You can view a list of Minecraft locale codes [here](https://minecraft.fandom.com/wiki/Language#Languages).

**How it works:**

* When a player joins, MultiLang checks their client language
* If their language matches one in the `languages` list, it's automatically selected
* Players can still manually change their language using `/lang`

**Example:**

```yaml theme={null}
languages:
  english: "en_us"      # English (US)
  italiano: "it_it"     # Italian
  español: "es_es"      # Spanish (Spain)
  français: "fr_fr"     # French
  deutsch: "de_de"      # German
```

### strings

All translated strings that can be used in placeholders.

**Structure:**

```yaml theme={null}
strings:
  1:
    identifier: "example"        # Placeholder identifier (%multilang_example%)
    default: "Hello world"       # Default string if language not selected or not translated
    locales:
      italiano: "Ciao mondo"     # Italian translation
      español: "Hola mundo"       # Spanish translation
      français: "Bonjour le monde" # French translation
```

**Example:**

```yaml theme={null}
strings:
  1:
    identifier: "welcome"
    default: "Welcome to our server!"
    locales:
      italiano: "Benvenuto sul nostro server!"
      español: "¡Bienvenido a nuestro servidor!"
      français: "Bienvenue sur notre serveur!"
  
  2:
    identifier: "goodbye"
    default: "Goodbye!"
    locales:
      italiano: "Arrivederci!"
      español: "¡Adiós!"
      français: "Au revoir!"
```

**How to use:**

* The placeholder will be `%multilang_example%` (PlaceholderAPI) or `{multilang_example}` (MVdWPlaceholderAPI)
* If a player's language is translated, they see the translated text
* If not translated or language not selected, they see the `default` text

## Complete Example Configuration

```yaml theme={null}
prefix: "&9MultiLang &8»&r"

storage: FILE  # or MYSQL

mysql:
  host: "localhost"
  port: 3306
  database: "multilang"
  username: "root"
  password: ""

default: "english"
default-base: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="

languages:
  english: "en_us"
  italiano: "it_it"
  español: "es_es"
  français: "fr_fr"

strings:
  1:
    identifier: "welcome"
    default: "Welcome to our server!"
    locales:
      italiano: "Benvenuto sul nostro server!"
      español: "¡Bienvenido a nuestro servidor!"
      français: "Bienvenue sur notre serveur!"
  
  2:
    identifier: "goodbye"
    default: "Goodbye!"
    locales:
      italiano: "Arrivederci!"
      español: "¡Adiós!"
      français: "Au revoir!"
```

## Best Practices

1. **Use descriptive identifiers** - Choose clear names for your translation strings (e.g., `welcome`, `server_name`, `player_count`)

2. **Always provide defaults** - Always include a `default` value for each string

3. **Organize by category** - Group related translations together

4. **Test translations** - Always test your translations with players who speak those languages

5. **Keep it simple** - Use the identifier system - it's simple and easy to use!

## Related Guides

* [Translating](/multilang/translating) - Learn how to translate entities and plugin messages
* [Messages](/multilang/messages) - Configure plugin messages
* [GUI](/multilang/gui) - Customize the language selection GUI
* [RealTime](/multilang/realtime) - Set up real-time translation

## Still Confused?

<Info>
  Need help configuring MultiLang? Join our [Discord server](https://discord.io/RocketPlugins) - we'll help you configure the plugin!
</Info>


# Getting Started
Source: https://wiki.lorenzo0111.me/multilang/getting-started

Learn how to install and set up MultiLang, the best free multilocalization plugin for Minecraft servers

# Getting Started

MultiLang is a powerful, free multilocalization plugin that allows you to add multilocalization strings with simple placeholders. It's the best free multi-localization plugin available for Minecraft servers.

## Why MultiLang?

MultiLang offers several advantages:

* **Free and Open Source** - Completely free with active development
* **Easy to Use** - Simple placeholder system for translations
* **Active Maintenance** - Regularly updated and maintained
* **Community Support** - Active community and Discord support

<Info>
  MultiLang is open source and you can contribute by visiting the [GitHub repository](https://github.com/lorenzo0111/multilang).
</Info>

## Installation

Follow these steps to install MultiLang:

### Step 1: Install PlaceholderAPI

MultiLang requires **[PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)**. Download and install PlaceholderAPI first.

### Step 2: Install RocketPlaceholders

MultiLang also requires **[RocketPlaceholders](https://www.spigotmc.org/resources/rocketplaceholders-custom-placeholders.82678/)**. Install RocketPlaceholders before proceeding.

<Info>
  RocketPlaceholders is used by MultiLang to provide the translation placeholders. Make sure it's installed and enabled.
</Info>

### Step 3: Install MultiLang

1. Download MultiLang from the [official release page](https://github.com/Lorenzo0111/MultiLang/releases/latest)
2. Place the `.jar` file in your server's `plugins` folder
3. Restart your server

### Step 4: Verify Installation

After installation, MultiLang will create configuration files in `plugins/MultiLang/`. You should see:

* `config.yml` - Main configuration file
* `messages.yml` - Plugin messages
* `gui.yml` - GUI configuration (optional)

## Quick Start

Once installed, MultiLang is ready to use! Players can change their language using:

* `/lang` - Open the language selection GUI
* `/lang set <language>` - Set a specific language

## What's Next?

Now that you've installed MultiLang, check out these guides:

* [Configuration](/multilang/configuration) - Learn how to configure MultiLang
* [Translating](/multilang/translating) - Learn how to translate entities and messages
* [Messages](/multilang/messages) - Configure plugin messages
* [GUI](/multilang/gui) - Customize the language selection GUI
* [RealTime](/multilang/realtime) - Set up real-time translation

## Support

Need help? Join our [Discord server](https://discord.io/RocketPlugins) for support!


# GUI Configuration
Source: https://wiki.lorenzo0111.me/multilang/gui

Learn how to configure the language selection GUI, including base64 textures for language icons

# GUI Configuration

MultiLang provides a GUI (Graphical User Interface) for players to select their language. This guide covers how to configure and customize the GUI.

## Overview

The GUI configuration file is located at `plugins/MultiLang/gui.yml`. In this file, you can add base64 textures for every language that will appear in the GUI.

## What is Base64?

In simple terms, base64 is a string containing the texture of a player head (skin). It's used to display custom icons in the language selection GUI.

## How to Create a Base64

You can generate a base64 from a player head using [MineSkin](https://mineskin.org):

1. Go to [MineSkin.org](https://mineskin.org)
2. Upload a skin or select a head
3. Pick the **Texture Signature** value (this is your base64)

<Info>
  You can also use existing heads from
  [Minecraft-Heads](https://minecraft-heads.com/). In that case, pick the
  `value` field instead of the Texture Signature.
</Info>

### Visual Guide

Here's a simple guide showing how to get the base64:

<img alt="Base64 Guide" />

## Adding Base64 to a Language

To add a base64 texture to a new language, add it to the `gui.yml` file:

```yaml theme={null}
base:
  # Existing bases...
  "your-awesome-lang": "your awesome base64"
```

### Example

```yaml theme={null}
base:
  english: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
  italiano: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
  español: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
  "your-awesome-lang": "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
```

<Warning>
  Make sure that you have already created the language in the
  [`languages`](/multilang/configuration#languages) section of your `config.yml`
  before adding it to the GUI.
</Warning>

## Language Name Matching

The language name in `gui.yml` must match exactly with the language name in your `config.yml` `languages` section.

**Example:**

**config.yml:**

```yaml theme={null}
languages:
  english: "en_us"
  italiano: "it_it"
  español: "es_es"
```

**gui.yml:**

```yaml theme={null}
base:
  english: "base64_here"
  italiano: "base64_here"
  español: "base64_here"
```

## Complete Example

Here's a complete example of a GUI configuration:

```yaml theme={null}
base:
  english: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
  italiano: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
  español: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
  français: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
  deutsch: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
```

## Default Base

You can also set a default base64 in your `config.yml`:

```yaml theme={null}
default-base: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
```

This will be used for languages that don't have a specific base64 defined in `gui.yml`.

## Best Practices

1. **Use appropriate icons** - Choose icons that represent the language (e.g., flag icons, country symbols)

2. **Keep it consistent** - Use a consistent style for all language icons

3. **Test the GUI** - Always test the GUI in-game to make sure icons display correctly

4. **Match language names** - Ensure language names match exactly between `config.yml` and `gui.yml`

## Troubleshooting

**Q: Icons aren't showing up**\
A: Make sure:

* The base64 string is correct and complete
* The language name matches exactly between `config.yml` and `gui.yml`
* You've restarted the server after making changes

**Q: Some languages don't have icons**\
A: Languages without a base64 in `gui.yml` will use the `default-base` from `config.yml`, or show a default head if no default is set.

**Q: Base64 is invalid**\
A: Make sure:

* You copied the complete base64 string
* You're using the Texture Signature from MineSkin (not the Texture Value)
* The base64 is properly formatted

## Related Guides

* [Configuration](/multilang/configuration) - General configuration guide
* [Getting Started](/multilang/getting-started) - Initial setup


# Messages
Source: https://wiki.lorenzo0111.me/multilang/messages

Learn how to configure and customize MultiLang plugin messages

# Messages

MultiLang has customizable messages that can be translated. This guide covers all available message keys and how to configure them.

## Message File

Plugin messages are stored in `plugins/MultiLang/messages.yml`.

## Default Messages

You can view the default message values in the [GitHub repository](https://github.com/Lorenzo0111/MultiLang/blob/master/src/main/resources/messages.yml).

## Available Message Keys

| Key                     | Description                                                                   |
| :---------------------- | :---------------------------------------------------------------------------- |
| `console`               | Sent when you try to execute a command that can be executed from players only |
| `subcommands.not-found` | When a subcommand does not exist                                              |
| `subcommands.edit`      | When you use an invalid `/lang edit` syntax                                   |
| `already`               | When you have already chosen a language as primary language                   |
| `current`               | Current locale message                                                        |
| `current-other`         | Current locale of another player                                              |
| `not-found`             | When a player does not exist                                                  |
| `lang-not-found`        | When a language does not exist                                                |
| `changed`               | When you change your language                                                 |
| `gui.title`             | GUI title                                                                     |
| `gui.current`           | `Current language` item name                                                  |

## Message Examples

### Console Message

**Key:** `console`

**Default:**

```yaml theme={null}
console: "This command can only be executed by players!"
```

**Usage:** Shown when a console tries to execute a player-only command.

### Subcommand Not Found

**Key:** `subcommands.not-found`

**Default:**

```yaml theme={null}
subcommands.not-found: "Subcommand not found!"
```

**Usage:** Shown when a subcommand doesn't exist.

### Subcommand Edit Error

**Key:** `subcommands.edit`

**Default:**

```yaml theme={null}
subcommands.edit: "Invalid syntax! Use: /lang edit <identifier> <locale> <text>"
```

**Usage:** Shown when `/lang edit` syntax is incorrect.

### Already Selected Language

**Key:** `already`

**Default:**

```yaml theme={null}
already: "You have already selected this language as your primary language!"
```

**Usage:** Shown when a player tries to select a language they've already selected.

### Current Language

**Key:** `current`

**Default:**

```yaml theme={null}
current: "Your current language is: {language}"
```

**Usage:** Shows the player's current language. `{language}` is replaced with the language name.

### Current Language (Other Player)

**Key:** `current-other`

**Default:**

```yaml theme={null}
current-other: "{player}'s current language is: {language}"
```

**Usage:** Shows another player's current language. `{player}` and `{language}` are replaced with actual values.

### Player Not Found

**Key:** `not-found`

**Default:**

```yaml theme={null}
not-found: "Player not found!"
```

**Usage:** Shown when a specified player doesn't exist or isn't online.

### Language Not Found

**Key:** `lang-not-found`

**Default:**

```yaml theme={null}
lang-not-found: "Language not found!"
```

**Usage:** Shown when a specified language doesn't exist in the configuration.

### Language Changed

**Key:** `changed`

**Default:**

```yaml theme={null}
changed: "Language changed to {language}!"
```

**Usage:** Shown when a player successfully changes their language. `{language}` is replaced with the language name.

### GUI Title

**Key:** `gui.title`

**Default:**

```yaml theme={null}
gui.title: "Select Language"
```

**Usage:** The title shown in the language selection GUI.

### GUI Current Language Item

**Key:** `gui.current`

**Default:**

```yaml theme={null}
gui.current: "Current Language"
```

**Usage:** The name of the item that shows the current language in the GUI.

## Customizing Messages

You can customize any message by editing `messages.yml`:

```yaml theme={null}
console: "&cThis command can only be executed by players!"
changed: "&aLanguage changed to {language}!"
gui.title: "&9&lSelect Your Language"
```

<Info>
  All messages support Minecraft color codes (e.g., `&a` for green, `&c` for
  red, `&l` for bold).
</Info>

## Placeholders

Some messages support placeholders:

* `{language}` - The language name
* `{player}` - The player name

**Example:**

```yaml theme={null}
changed: "&aYour language has been changed to &e{language}&a!"
current-other: "&7{player}'s current language is: &e{language}"
```

## Complete Example

Here's a complete example of customized messages:

```yaml theme={null}
console: "&cThis command can only be executed by players!"
subcommands.not-found: "&cSubcommand not found!"
subcommands.edit: "&cInvalid syntax! Use: /lang edit <identifier> <locale> <text>"
already: "&eYou have already selected this language!"
current: "&7Your current language is: &e{language}"
current-other: "&7{player}'s current language is: &e{language}"
not-found: "&cPlayer not found!"
lang-not-found: "&cLanguage not found!"
changed: "&aLanguage changed to &e{language}&a!"
gui.title: "&9&lSelect Your Language"
gui.current: "&7Current Language"
```

## Best Practices

1. **Keep messages clear** - Use clear, concise language
2. **Use color codes** - Make important messages stand out
3. **Test messages** - Make sure messages display correctly in-game
4. **Be consistent** - Use consistent color schemes and formatting

## Related Guides

* [Configuration](/multilang/configuration) - General configuration guide
* [GUI](/multilang/gui) - Customize the language selection GUI


# RealTime Translation
Source: https://wiki.lorenzo0111.me/multilang/realtime

Learn how to configure real-time translation using Google or Bing translation APIs

# RealTime Translation

MultiLang supports real-time translation using external translation APIs. This allows you to automatically translate text that hasn't been manually translated yet.

## Overview

RealTime translation uses external APIs to translate text on-the-fly. This is useful for:

* Translating plugin messages that haven't been manually translated
* Providing translations for new content automatically
* Supporting languages you haven't manually added translations for

## Choosing an API

You have two API options:

1. **Google Translate API** - Free but may not always work reliably
2. **Bing Microsoft Translator API** - More reliable, requires a free API key

<Info>
  We personally suggest using Bing because Google may not work reliably.
  However, both options are available.
</Info>

If you know another good translation API, feel free to suggest it on our [Discord server](https://discord.io/RocketPlugins).

## Creating an API Key (Bing)

You only need an API key if you're using Bing. Google doesn't require an API key (but may be less reliable).

### Step 1: Subscribe to the API

Subscribe for a free API key at [RapidAPI - Microsoft Translator](https://rapidapi.com/microsoft-azure-org-microsoft-cognitive-services/api/microsoft-translator-text/pricing).

### Step 2: Retrieve Your Key

After subscribing, retrieve your API key at [RapidAPI Developer Dashboard](https://rapidapi.com/developer/new).

### Visual Guide

Here's a simple guide showing how to retrieve your API key:

![API Key Guide](https://i.imgur.com/CGHcV4T.gif)

## Configuration

Once you have your API key (if using Bing), configure it in your `config.yml`:

```yaml theme={null}
realtime:
  enabled: true
  api: "bing" # or "google"
  api-key: "your-api-key-here" # Only needed for Bing
  cache: true
```

### Configuration Options

**`enabled`** - Enable or disable real-time translation

**`api`** - Choose between `"google"` or `"bing"`

**`api-key`** - Your API key (only required for Bing)

**`cache`** - Enable or disable caching (highly recommended)

## Should I Use Cache?

<Info>
  **Yes, absolutely!** Caching will significantly reduce delay and API usage. It
  stores translated text so it doesn't need to be translated again.
</Info>

**Benefits of caching:**

* Faster translation (instant for cached text)
* Reduced API usage
* Lower costs (if using paid API)
* Better performance

**How it works:**

* First time a text is translated: API call is made, result is cached
* Subsequent times: Translation is retrieved from cache instantly

## Database Size Management

### My database size is too big. What should I do?

If your cache database becomes too large, you can clear it using:

```
/multilangadmin clearCache
```

This command clears all cached translations. New translations will be cached again as they're requested.

<Info>
  Regularly clearing the cache can help manage database size, but remember that
  cleared translations will need to be translated again (using API calls).
</Info>

## Performance

### Will it cause lag?

No, all translation tasks are executed asynchronously. This means they don't block the main server thread.

**However:**

* There may be a slight delay before your message is sent (while translation is happening)
* If you use cache, this delay only happens the first time a text is translated
* Subsequent translations of the same text are instant (from cache)

## API Quota Limits

### What will happen when I reach my quota limit?

When you reach your API quota limit:

* RealTime translation will be automatically disabled
* Manual translations will still work
* You'll need to wait for quota reset or upgrade your API plan

<Info>
  If you find an API without quota limits, please suggest it on our [Discord
  server](https://discord.io/RocketPlugins)!
</Info>

## Best Practices

1. **Use caching** - Always enable cache to improve performance and reduce API usage

2. **Monitor API usage** - Keep an eye on your API usage to avoid hitting limits

3. **Combine with manual translations** - Use real-time translation as a fallback, but manually translate common messages for better performance

4. **Clear cache periodically** - If your database grows too large, clear the cache occasionally

5. **Use Bing for reliability** - If possible, use Bing API for more reliable translations

## Troubleshooting

**Q: Translations aren't working**\
A: Make sure:

* RealTime is enabled in config
* API is set correctly ("google" or "bing")
* If using Bing, API key is correct
* You haven't exceeded your API quota

**Q: Translations are slow**\
A: Enable caching! The first translation may be slow, but cached translations are instant.

**Q: Database is too large**\
A: Use `/multilangadmin clearCache` to clear the cache database.

**Q: API quota exceeded**\
A: Wait for quota reset, upgrade your API plan, or switch to manual translations.

## Example Configuration

Here's a complete example configuration:

```yaml theme={null}
realtime:
  enabled: true
  api: "bing"
  api-key: "your-bing-api-key-here"
  cache: true
```

## Related Guides

* [Configuration](/multilang/configuration) - General configuration guide
* [Translating](/multilang/translating) - Manual translation guide

## Need Help?

<Info>
  Still need help? Join our [Discord server](https://discord.io/RocketPlugins)
  for support!
</Info>


# Translating
Source: https://wiki.lorenzo0111.me/multilang/translating

Learn how to translate entities, inventories, and plugin messages using MultiLang's translation system

# Translating

MultiLang makes it easy to translate entities, inventories, and plugin messages. This guide will show you how to use the translation system.

## Overview

With MultiLang, you can translate:

* Entity names (mobs, items, etc.)
* Inventory titles and item names
* Plugin messages
* Any text sent to players

<Info>
  Remember to install
  [ProtocolLib](https://www.spigotmc.org/resources/protocollib.1997/) or the
  translations won't work. ProtocolLib is required for packet manipulation.
</Info>

## How It Works

MultiLang handles all packets that the server sends to the client and translates them automatically. This means you can translate:

* Chat messages
* Inventory titles
* Entity names
* Item names
* And more!

## Using the Translation Pattern

To translate text, you need to use a special pattern: `<lang>identifier</lang>`

Replace `identifier` with the identifier of your translation string (defined in `config.yml`).

### Basic Example

If you have a translation string with identifier `welcome`:

```yaml theme={null}
strings:
  1:
    identifier: "welcome"
    default: "Welcome to our server!"
    locales:
      italiano: "Benvenuto sul nostro server!"
      español: "¡Bienvenido a nuestro servidor!"
```

You can use it in your plugin messages or configs:

```
<lang>welcome</lang>
```

When a player sees this, they'll see the text in their selected language!

## Real-World Examples

### Translating Menu Titles

If you're using a menu plugin like [DeluxeMenus](https://www.spigotmc.org/resources/deluxemenus.11734/), you can translate menu titles:

**Menu Config:**

```yaml theme={null}
menu_title: "<lang>menu_title</lang>"
```

**MultiLang Config:**

```yaml theme={null}
strings:
  1:
    identifier: "menu_title"
    default: "Main Menu"
    locales:
      italiano: "Menu Principale"
      español: "Menú Principal"
      français: "Menu Principal"
```

### Translating Plugin Messages

You can translate plugin messages. For example, with Essentials:

**Essentials Config:**

```yaml theme={null}
gamemode-change: "<lang>gamemode</lang> {0} <lang>for</lang> {1}."
```

**MultiLang Config:**

```yaml theme={null}
strings:
  1:
    identifier: "gamemode"
    default: "Gamemode changed to"
    locales:
      italiano: "Modalità di gioco cambiata in"
      español: "Modo de juego cambiado a"

  2:
    identifier: "for"
    default: "for"
    locales:
      italiano: "per"
      español: "para"
```

### Multiple Translations in One Message

You can use multiple translations in a single message:

```
<lang>gamemode</lang> {0} <lang>for</lang> {1}.
```

This example uses two translation strings:

* `gamemode` - "Gamemode changed to"
* `for` - "for"

The `{0}` and `{1}` are placeholders that will be replaced with actual values (e.g., player name, gamemode name).

## Advanced Examples

### Custom Plugin Messages

Here's an example for creating custom plugin messages:

**Plugin Message:**

```
<lang>player_joined</lang> <lang>the_server</lang>!
```

**MultiLang Config:**

```yaml theme={null}
strings:
  1:
    identifier: "player_joined"
    default: "{player} joined"
    locales:
      italiano: "{player} si è unito"
      español: "{player} se unió"

  2:
    identifier: "the_server"
    default: "the server"
    locales:
      italiano: "al server"
      español: "al servidor"
```

### Entity Names

You can translate entity names in the game:

**Entity Config:**

```yaml theme={null}
entity_name: "<lang>zombie</lang>"
```

**MultiLang Config:**

```yaml theme={null}
strings:
  1:
    identifier: "zombie"
    default: "Zombie"
    locales:
      italiano: "Zombie"
      español: "Zombi"
      français: "Zombie"
```

## Best Practices

1. **Use descriptive identifiers** - Choose clear names (e.g., `welcome`, `menu_title`, `player_joined`)

2. **Break down complex messages** - Split long messages into multiple translation strings for better flexibility

3. **Test with different languages** - Always test your translations with players who speak those languages

4. **Keep placeholders** - Use `{0}`, `{1}`, etc., for dynamic values that shouldn't be translated

5. **Document your translations** - Keep a list of all translation identifiers and their purposes

## Troubleshooting

**Q: Translations aren't showing up**\
A: Make sure:

* ProtocolLib is installed and enabled
* The translation identifier exists in your `config.yml`
* The `<lang>identifier</lang>` pattern is correct
* Players have selected a language (or autodetect is working)

**Q: Some text isn't translating**\
A: Check:

* The text uses the `<lang>identifier</lang>` pattern
* The identifier is defined in your strings
* ProtocolLib is properly installed

**Q: Placeholders aren't working**\
A: Make sure:

* Placeholders like `{0}`, `{1}` are used correctly
* The plugin sending the message supports placeholders
* MultiLang is processing the packets correctly

## Related Guides

* [Configuration](/multilang/configuration) - Learn how to configure translation strings
* [Messages](/multilang/messages) - Configure plugin messages
* [RealTime](/multilang/realtime) - Set up real-time translation

## Need Help?

<Info>
  Not sure about something? Join our [Discord
  server](https://discord.io/RocketPlugins) - we'll help you set up
  translations!
</Info>


# Main Configuration
Source: https://wiki.lorenzo0111.me/qualityarmory/config/main

Complete reference for all config.yml options in QualityArmory

# Main Configuration

This is the documentation of the main configuration, also known as config.yml.
Below you can find a list of all the options that you can configure and their explanation.

* **ENABLE-DEBUG**: `false` - Toggles detailed debug messages in the console. Useful for troubleshooting.
* **language**: `en` - Sets the language file used for plugin messages (e.g., `en` for English).
* **FriendlyFireEnabled**: `false` - If `true`, allows players on the same team or party to damage each other with guns.
* **KickPlayerIfDeniedResourcepack**: `false` - If `true`, players who decline the server resource pack prompt will be kicked.
* **useDefaultResourcepack**: `true` - If `true`, the plugin uses its built-in default resource pack URLs. If `false`, it uses the URLs specified in `DefaultResourcepackOverride`.
* **EnableWeaponDurability**: `false` - If `true`, QualityArmory weapons will lose durability when used.
* **BulletDetection.step**: `0.1` - Controls the distance interval (in blocks) for checking bullet collisions. Smaller values are more accurate but may use more server resources.
* **BlockBullets.door**: `false` - If `true`, bullets will be stopped by door blocks.
* **BlockBullets.halfslabs**: `false` - If `true`, bullets will be stopped by half-slab blocks.
* **BlockBullets.leaves**: `false` - If `true`, bullets will be stopped by leaf blocks.
* **BlockBullets.water**: `false` - If `true`, bullets will be stopped upon entering water blocks.
* **BlockBullets.glass**: `false` - If `true`, bullets will be stopped by glass blocks.
* **enableInteract.Chests**: `false` - If `true`, allows players to open chests while holding a QualityArmory weapon.
* **overrideAnvil**: `false` - If `true`, replaces the standard anvil interface with the QualityArmory crafting bench when interacting with an anvil.
* **showPossibleCrashHelpMessage**: `true` - If `true`, displays a message suggesting `/qa getResourcepack` if a player might be experiencing client crashes due to the resource pack.
* **anticheatFix**: `false` - Enables specific adjustments intended to improve compatibility with some anti-cheat plugins.
* **verboseItemLogging**: `false` - If `true`, prints detailed information to the console during the loading of guns, ammo, and other items.
* **enable\_permssionsToShoot**: `false` - If `true`, players require the permission `qualityarmory.shoot.<gun_name>` to fire specific guns.
* **enable\_permssionsToCraft**: `false` - If `true`, players require the permission `qualityarmory.craftgun.<gun_name>` to craft specific guns.
* **enable\_permssionsToBuy**: `false` - If `true`, players require the permission `qualityarmory.shopgun.<gun_name>` to buy specific guns.
* **sendOnJoin**: `true` - If `true`, automatically prompts players to download the resource pack when they join the server.
* **sendTitleOnJoin**: `false` - If `true`, displays a title message related to the resource pack when players join.
* **resourcepackInvincibility**: `false` - If `true`, players are invulnerable for a short time after joining while the resource pack is being applied.
* **SecondsTillRPIsSent**: `5.0` - The delay in seconds after a player joins before the resource pack prompt is sent (if `sendOnJoin` is true).
* **enableBulletTrails**: `true` - If `true`, displays particle trails following bullets.
* **BulletTrailsSpacing**: `0.5` - The distance (in blocks) between particles in a bullet trail.
* **enableIgnoreArmorProtection**: `false` - If `true`, bullets ignore the protection value of armor worn by the target.
* **enableIgnoreUnbreakingChecks**: `false` - If `true`, the Unbreaking enchantment on items is ignored when calculating durability loss (if `EnableWeaponDurability` is true).
* **enableIgnoreSkipForBasegameItems**: `false` - A legacy or internal setting likely related to how the plugin handles interactions with vanilla Minecraft items.
* **Items.enable\_Unbreaking**: `true` - If `true`, makes QualityArmory items inherently unbreakable, regardless of the `EnableWeaponDurability` setting.
* **enableReloadingOnDrop**: `false` - If `true`, allows players to reload by pressing their drop key (default 'Q') while holding a gun.
* **enableReloadingWhenSwapToOffhand**: `true` - If `true`, allows players to reload by pressing their swap-to-offhand key (default 'F') while holding a gun.
* **enableReloadOnlyWhenSwapToOffhand**: `false` - If `true`, reloading is *only* possible using the swap-to-offhand key ('F'), disabling other methods like right-click (if applicable).
* **allowGunHitEntities**: `true` - If `true`, allows guns to register melee damage when hitting entities directly.
* **preventHiddenPlayers**: `true` - If `true`, players hidden with the hidePlayer api method will not be able to be hit by bullets.
* **preventGunsInHoppers**: `true` - If `true`, guns cannot be moved with hoppers, this feature prevents some exploits related to item duplication.
* **showOutOfAmmoOnTitle**: `false` - If `true`, displays a large title message on the screen when the player tries to shoot with an empty gun.
* **showReloadingTitle**: `false` - If `true`, displays a large title message on the screen while the player is reloading.
* **showAmmoInXPBar**: `false` - If `true`, displays the current gun's ammo count in the player's experience bar.
* **perWeaponPermission**: `false` - If `true`, requires players to have individual permissions (`qualityarmory.use.<item_name>`) to use each specific gun, ammo, or misc item.
* **perWeaponCraftPermission**: `false` - If `true`, requires players to have individual permissions (`qualityarmory.craftgun.<item_name>`) to craft each specific gun, ammo, or misc item.
* **perWeaponBuyPermission**: `false` - If `true`, requires players to have individual permissions (`qualityarmory.shopgun.<item_name>`) to buy each specific gun, ammo, or misc item.
* **useMoveForRecoil**: `true` - If `true`, recoil is simulated by directly moving the player's camera view. If `false`, other methods might be used.
* **enableExplosionDamage**: `false` - If `true`, explosions caused by QualityArmory projectiles can destroy blocks.
* **enableExplosionDamageDrop**: `false` - If `true` and `enableExplosionDamage` is true, blocks destroyed by explosions will drop their corresponding items.
* **enablePrimaryWeaponLimiter**: `false` - If `true`, enforces limits on the number of primary and secondary weapons a player can carry simultaneously.
* **weaponlimiter\_primaries**: `2` - The maximum number of items classified as 'primary' weapons a player can carry if the limiter is enabled.
* **weaponlimiter\_secondaries**: `2` - The maximum number of items classified as 'secondary' weapons a player can carry if the limiter is enabled.
* **enableCrafting**: `true` - Enables the `/qa craft` command and the crafting system for QualityArmory items.
* **enableShop**: `true` - Enables the `/qa shop` command and the GUI shop for buying QualityArmory items.
* **AUTO-UPDATE**: `true` - If `true`, the plugin will attempt to automatically download and install updates on server start.
* **Swap-Reload-and-Shooting-Controls**: `false` - If `true`, swaps the default mouse button actions (e.g., makes right-click shoot and left-click aim/reload).
* **Order-Shop-By-Price**: `false` - If `true`, items listed in the `/qa shop` GUI will be sorted by their configured price.
* **enable\_lore\_gun-info\_messages**: `true` - If `true`, displays weapon statistics like damage, ammo type, etc., in the item's lore text.
* **enable\_lore\_control-help\_messages**: `true` - If `true`, displays basic control instructions (e.g., "\[LMB] Shoot") in the item's lore text.
* **Enable\_Headshot\_Instantkill**: `true` - If `true`, landing a headshot on a player or mob results in an instant kill.
* **Enable\_Headshot\_Notification\_Sound**: `true` - If `true`, plays a sound effect to the shooter when they successfully land a headshot.
* **Headshot\_Notification\_Sound**: `entity.experience_orb.pickup` - The specific sound event name to play for a headshot notification.
* **Enable\_Headshot\_Sounds**: `true` - If `true`, enables additional sounds related to headshots (e.g., impact/gore sounds).
* **Headshot\_Blacklist**: `[]` - A list of entity types (e.g., `ZOMBIE`, `PLAYER`) that are immune to the special effects of headshots (like instant kill).
* **Enable\_Hit\_Sound**: `true` - If `true`, plays a sound effect to the shooter when they successfully hit an entity with a bullet.
* **Hit\_Notification\_Sound**: `entity.experience_orb.pickup` - The specific sound event name to play for a hit notification.
* **Enable\_AutoArm\_Grenades**: `false` - If `true`, grenades are automatically armed when thrown, bypassing the need to manually "pull the pin" first.
* **gravityConstantForDropoffCalculations**: `0.05` - The value representing gravity's effect used in calculating bullet trajectory and drop-off.
* **allowGunReload**: `true` - A master switch to enable or disable all gun reloading mechanics.
* **Auto-Detect-Resourcepack**: `true` - If `true`, the plugin attempts to automatically select the correct resource pack version based on the detected Minecraft server version.
* **ManuallyOverrideTo\_1\_8\_systems**: `false` - If `true`, forces the plugin to use item models and mechanics designed for Minecraft `1.8`, overriding auto-detection.
* **ManuallyOverrideTo\_1\_13\_systems**: `false` - If `true`, forces the plugin to use item models and mechanics designed for Minecraft `1.9-1.13`, overriding auto-detection.
* **ManuallyOverrideTo\_1\_14\_systems**: `false` - If `true`, forces the plugin to use item models (like Crossbow) and mechanics designed for Minecraft `1.14+`, overriding auto-detection.
* **unknownTranslationKeyFixer**: `false` - If `true`, attempts to apply fixes for potential issues related to missing or incorrect translation keys in item names or lore.
* **Enable\_Creation\_Of\_Default\_Files**: `true` - If `true`, the plugin will automatically generate default configuration files (like for guns, ammo, etc.) in its folder if they are missing.
* **EnableGlowEffects**: `false` - If `true`, enables glowing effects on certain items or potentially entities under specific conditions.
* **Break-Block-Texture-If-Shot**: `true` - If `true`, displays block breaking particle effects when a block is hit by a bullet.
* **enableRecoil**: `true` - Enables or disables the visual recoil effect when firing weapons.
* **experimental.BulletWounds.InitialBloodLevel**: `1500.0` - The starting value for the internal "blood level" tracker used by the experimental bleeding system.
* **experimental.BulletWounds.BloodIncreasePerSecond**: `0.01` - Likely represents the rate at which the "blood level" decreases per second when bleeding (needs verification, name is counter-intuitive).
* **experimental.BulletWounds.Medkit\_Heal\_Bloodloss\_Rate**: `0.05` - The rate at which using a medkit counteracts bleeding or restores the "blood level".
* **experimental.BulletWounds.enableBleeding**: `false` - Enables the experimental system where players can suffer from bleeding after being shot, potentially requiring a medkit.
* **disableHotbarMessages.OutOfAmmo**: `false` - If `true`, prevents the "Out of Ammo" message from appearing above the hotbar.
* **disableHotbarMessages.Shoot**: `false` - If `true`, prevents the ammo count message from appearing above the hotbar when shooting.
* **disableHotbarMessages.Reload**: `false` - If `true`, prevents the "Reloading..." message from appearing above the hotbar.
* **automaticallyReloadGunWhenOutOfAmmo**: `false` - If `true`, the gun will automatically begin reloading as soon as the player tries to fire with no ammo left.
* **generalModifiers.sway.Run**: `1.3` - A multiplier affecting the amount of weapon sway while the player is running.
* **generalModifiers.sway.Walk**: `1.5` - A multiplier affecting the amount of weapon sway while the player is walking.
* **generalModifiers.sway.Ironsights**: `0.8` - A multiplier affecting the amount of weapon sway while the player is aiming down sights (values \< 1 reduce sway).
* **generalModifiers.sway.Sneak**: `0.7` - A multiplier affecting the amount of weapon sway while the player is sneaking (values \< 1 reduce sway).
* **deathmessages.enable**: `true` - If `true`, enables custom death messages indicating kills made with QualityArmory weapons.
* **impenetrableEntityTypes**: `[ARROW]` - A list of entity types that bullets cannot pass through (e.g., arrows, potentially other projectiles).
* **DefaultResourcepackOverride**: `false` - If `true`, forces the plugin to use the resource pack URL(s) defined under `DefaultResourcepack` instead of its internal defaults.
* **IronSightsOnRightClick**: `false` - If `true`, aiming down sights (iron sights) is activated by right-clicking instead of the default (usually sneaking).
* **SwapSneakToSingleFire**: `false` - If `true`, changes the control for single-fire mode on automatic weapons to Sneak + Left-Click.
* **DestructableMaterials**: `[MATERIAL_NAME_HERE]` - A list of material names (e.g., `GLASS`, `WHITE_WOOL`) that can be broken by bullets if `enableExplosionDamage` is appropriately configured or via specific weapon properties.
* **RegenDestructableBlocksAfter**: `-1` - The time in seconds after which a block destroyed by a QualityArmory weapon/explosion will regenerate. `-1` disables regeneration.
* **overrideAttackSpeed**: `true` - If `true` (primarily for `1.14+`), overrides the default item attack speed attribute, potentially allowing faster firing rates.
* **enable\_lore\_gun-info\_messages**: `true` - If `true`, displays weapon statistics like damage, ammo type, etc., in the item's lore text.
* **enable\_lore\_gun-bullets**: `false` - If `true`, displays the bullet amount in the item's lore text. This will make the gun go "up and down" when shooting.
* **weaponSwitchDelay**: `0` - The delay in seconds before a player can fire after switching weapon. A value of `0` means no delay.
* **DefaultResourcepack**: Defines the resource pack URLs. Refer to [ResourcePack Configuration](/qualityarmory/config/resourcepack) for more information.
* **restoreOffHand**: `false` - If `true`, restores the off-hand item after iron sights are unaimed.
* **hitDistance**: `5` - The maximum distance (in blocks) at which a gun can register melee hits on entities when using the gun to hit directly.
* **enableUnloadingOnDrop**: `false` - If `true`, allows players to unload their gun's magazine by pressing their drop key (default 'Q') while holding a gun.


# Menu Configuration
Source: https://wiki.lorenzo0111.me/qualityarmory/config/menu

Configure the GUI system for QualityArmory shop and crafting menus

# Menu Configuration

`menu.yml` controls the new GUI system for `/qa shop` and `/qa craft` (categories, item pages, navigation). Edit and save, then reload the plugin.

## Categories

* Defined under `categories.shop` and `categories.crafting`; the order in the file is the order shown in the GUI.
* Each category entry includes:
  * **`name`**: Button label (supports `&` colors).
  * **`icon.type`**: Bukkit material for the icon item.
  * **`icon.name` / `icon.lore`**: Custom name and lore for the icon item.
  * **`filter`**: Controls which registry items are loaded (case-insensitive). Supported filters in the current code:
    * `ALL`: Everything from guns, ammo, misc, armor.
    * `GUN`: Only `Gun` objects.
    * `AMMO`: Only `Ammo` objects.
    * `ARMOR`: Only `ArmorObject` items.
    * `MISC`: Items that are not Gun/Ammo/Armor (anything else registered).
    * Any other value falls back to `ALL`.
* Add a new category by copying an existing block:

```yaml theme={null}
categories:
  shop:
    explosives:
      name: "&cExplosives"
      icon:
        type: "TNT"
        name: "&c&lExplosives"
        lore:
          - "&7All explosive weapons"
      filter: "MISC" # must be one of: ALL, GUN, AMMO, ARMOR, MISC
```

## Menu layouts

* Layouts live under `menus.*`:
  * `shop_categories` / `crafting_categories`: Category selector menus.
  * `shop_items` / `crafting_items`: Paginated item menus (`title` accepts `%category%`).
* **`structure`**: Each row is 9 characters (inventory width). Characters map to slots left→right, top→bottom:
  * `.` → Dynamic slots (category buttons or items, filled in order)
  * `#` → Decorative filler from `items.custom.#`
  * `B` → Back to categories
  * `<` → Previous page button
  * `>` → Next page button
* Example bottom row in items views: `B # # # < # > # #` puts Back on the first slot, Previous at slot 5, Next at slot 7 (0-indexed within the row).
* To add more decorative blocks, insert another symbol in `structure` (e.g., `*`) and define it under `items.custom.*`. Rows shorter/longer than 9 are ignored.

## Buttons & custom items

* `items.previous` / `items.next`: Navigation buttons. Supports `%prevpage%`, `%nextpage%` and `%pages%`.
* `items.back`: Returns to the category selector defined by the current mode (shop or crafting).
* `items.custom`: Maps every non-special symbol used in `structure` to an item. The symbol is the first character of the key. Default `#` is a black stained glass pane. Add more keys for extra fillers or separators:

```yaml theme={null}
items:
  custom:
    "*":
      type: "GRAY_STAINED_GLASS_PANE"
      name: "&r"
      lore: []
```

## Placeholders

* `%category%`: Current category display name (used in titles).
* `%prevpage%` / `%nextpage%` / `%pages%`: Current and total pages (used in navigation lore).

## Tips

* Shop and crafting must be enabled in `config.yml` (`enableShop`, `enableCrafting`) for the menus to be reachable.
* Shop pages only show items with `price >= 0` and `enableShop: true`. Crafting pages only show items that have `ingredients` configured.
* If a button symbol in `structure` has no matching item definition, that slot stays empty.
* Keep row lengths to 9 characters—shorter or longer rows are ignored. Use spaces only inside quotes if you need visual separators; otherwise prefer symbols mapped via `items.custom`.


# ResourcePack Configuration
Source: https://wiki.lorenzo0111.me/qualityarmory/config/resourcepack

Configure QualityArmory to send the correct resource pack to players based on their Minecraft version

# ResourcePack Configuration

This guide explains how to configure QualityArmory to send the correct resource pack to your players.

## Basic Setup & Auto-Detection (Recommended)

* **`useDefaultResourcepack: true`**: Keep this `true` when using the auto-detection system. It tells the plugin to use the URLs defined under the `DefaultResourcepack:` section below.
* **`DefaultResourcepack:`**: This section defines the different resource pack URLs for various Minecraft versions.
  * You **must** have an entry with the key `"0"`. This is the **fallback URL** used if no specific version matches or if the player's version cannot be detected.
  * Add entries for specific Minecraft versions using the format `"minor"` or `"minor-patch"`. The plugin will select the *highest* version entry that is *less than or equal to* the player's version.
  * Keys should be strings (use quotes).
  * This system requires [ViaVersion](https://www.spigotmc.org/resources/19254/) installed to work.

**Example `DefaultResourcepack` Section:**

```yaml theme={null}
# ... other config settings ...

useDefaultResourcepack: true

DefaultResourcepack:
  # Fallback/Default URL (REQUIRED)
  '0': 'https://your-default-pack-url.zip'
  # Pack for 1.19.0 up to (but not including) 1.20.0
  '19': 'https://your-1.19.x-pack-url.zip'
  # Pack specifically for 1.20.0 up to (but not including) 1.20.2
  '20': 'https://your-1.20.0-pack-url.zip'
  # Pack for 1.20.2 up to (but not including) 1.21.0
  '20-2': 'https://your-1.20.2-pack-url.zip'
  # Pack for 1.21.0 and newer (until a higher version is added)
  '21': 'https://your-1.21.x-pack-url.zip'

# ... other config settings ...
```

**How it works with the example:**

* Player joins with `1.18.2` -> Gets the `'0'` pack.
* Player joins with `1.19.4` -> Gets the `'19'` pack.
* Player joins with `1.20.1` -> Gets the `'20'` pack.
* Player joins with `1.20.4` -> Gets the `'20-2'` pack.
* Player joins with `1.21.0` -> Gets the `'21'` pack.

## Manual Override (Alternative - Not Recommended unless needed)

* If you don't want auto-detection or don't have ViaVersion, you can force the plugin to use *one specific* set of models/systems.
* Set `Auto-Detect-Resourcepack: false`.
* Set **one** of the following to `true`:
  * `ManuallyOverrideTo_1_8_systems: true` (For `1.8` style models/mechanics)
  * `ManuallyOverrideTo_1_13_systems: true` (For `1.9-1.13` style models/mechanics)
  * `ManuallyOverrideTo_1_14_systems: true` (For `1.14+` style models/mechanics)
* In this case, the plugin will use the fallback `'0'` URL from `DefaultResourcepack`. This setup is less flexible and generally only used for troubleshooting or specific server setups.

## Using a Single Custom URL (Simple)

* If you only have *one* resource pack URL you want *everyone* to use, regardless of version:
* Set `useDefaultResourcepack: false`.
* Set `DefaultResourcepackOverride: true`.
* Define your single URL under `DefaultResourcepack:` :

```yaml theme={null}
# ... other config settings ...

useDefaultResourcepack: false
DefaultResourcepackOverride: true

DefaultResourcepack: 'https://your-single-custom-pack-url.zip'

# ... other config settings ...
```


# QualityArmory API
Source: https://wiki.lorenzo0111.me/qualityarmory/developers/api

Complete API reference for QualityArmory plugin integration

# QualityArmory API

The `me.zombie_striker.qg.api.QualityArmory` class provides static methods for interacting with the QualityArmory plugin, allowing other plugins to access information about guns, ammo, armor, and miscellaneous items, as well as perform actions like giving items or checking player states.

## Core Item Management & Creation

### `createAndLoadNewGun(String name, String displayname, Material material, int id, WeaponType type, WeaponSounds sound, boolean hasIronSights, String ammotype, int damage, int maxBullets, int cost)`

**Description**: Creates a new gun configuration file (`.yml`) in the `plugins/QualityArmory/newGuns/` directory and immediately attempts to load it into the running server.

**Parameters**:

* `name`: Internal name for the gun (used in commands).
* `displayname`: In-game display name (supports color codes).
* `material`: Base `Material` for the item.
* `id`: CustomModelData (`1.14+`) or Durability (`<1.14`) value.
* `type`: The `WeaponType` enum value (e.g., `PISTOL`, `RIFLE`).
* `sound`: The `WeaponSounds` enum value for firing.
* `hasIronSights`: `true` if the gun should support aiming down sights.
* `ammotype`: Internal name of the required `Ammo` item.
* `damage`: Base damage per bullet.
* `maxBullets`: Magazine capacity.
* `cost`: Price in the `/qa shop`.

**Returns**: A `GunYML` object representing the created configuration (allows further modification before saving, though this method saves immediately).

**Note**: Creates a file and schedules a task to load it.

### `createNewGunYML(String name, String displayname, Material material, int id, WeaponType type, WeaponSounds sound, boolean hasIronSights, String ammotype, int damage, int maxBullets, int cost)`

**Description**: Creates a `GunYML` object representing a new gun configuration but *does not* automatically save or load it. You would need to call methods on the returned `GunYML` object to save it.

**Parameters**: Same as `createAndLoadNewGun`.

**Returns**: A `GunYML` object representing the potential configuration.

### `registerNewUsedExpansionItem(Material used, int id)`

**Description**: Registers a specific Material/ID combination as being used by an expansion pack or addon. This helps prevent ID conflicts when QualityArmory searches for available IDs. Assumes variant 0.

**Parameters**:

* `used`: The `Material` used by the expansion item.
* `id`: The CustomModelData/Durability value used.

### `registerNewUsedExpansionItem(Material used, int id, int var)`

**Description**: Registers a specific Material/ID/Variant combination as being used by an expansion pack or addon.

**Parameters**:

* `used`: The `Material` used by the expansion item.
* `id`: The CustomModelData/Durability value used.
* `var`: The variant value used.

### `registerNewUsedExpansionItem(MaterialStorage ms)`

**Description**: Registers a `MaterialStorage` object (which encapsulates Material, ID, and Variant) as being used by an expansion pack or addon.

**Parameters**:

* `ms`: The `MaterialStorage` object representing the item.

## Retrieving Registered Items

* **`getGuns()`**: Returns an `Iterator<Gun>` for all loaded guns.
* **`getAmmo()`**: Returns an `Iterator<Ammo>` for all loaded ammo types.
* **`getMisc()`**: Returns an `Iterator<CustomBaseObject>` for all loaded miscellaneous items (like medkits, ammo bags).
* **`getArmor()`**: Returns an `Iterator<ArmorObject>` for all loaded armor pieces.
* **`getCustomItems()`**: Returns an `Iterator<CustomBaseObject>` containing all loaded guns, ammo, armor, and misc items combined.
* **`getCustomItemsAsList()`**: Returns a `List<CustomBaseObject>` containing all loaded guns, ammo, armor, and misc items combined.
* **`getGun(ItemStack is)`**: Returns the `Gun` object associated with the given `ItemStack`, or `null` if it's not a QA gun.
* **`getAmmo(ItemStack is)`**: Returns the `Ammo` object associated with the given `ItemStack`, or `null` if it's not QA ammo.
* **`getArmor(ItemStack is)`**: Returns the `ArmorObject` associated with the given `ItemStack`, or `null` if it's not QA armor.
* **`getMisc(ItemStack is)`**: Returns the `CustomBaseObject` (often castable to a specific type like `AmmoBag`) associated with the given `ItemStack`, or `null` if it's not a QA misc item.
* **`getCustomItem(ItemStack is)`**: Returns the `CustomBaseObject` (Gun, Ammo, Armor, or Misc) associated with the given `ItemStack`, or `null` if it's not a QA item.
* **`getCustomItem(Material material, int data, int variant)`**: Returns the `CustomBaseObject` matching the specified Material, CustomModelData/Durability, and Variant, or `null`.
* **`getCustomItem(MaterialStorage material)`**: Returns the `CustomBaseObject` matching the specified `MaterialStorage`, or `null`.
* **`getGunByName(String name)`**: Returns the `Gun` object with the matching internal name, or `null`.
* **`getAmmoByName(String name)`**: Returns the `Ammo` object with the matching internal name, or `null`.
* **`getArmorByName(String name)`**: Returns the `ArmorObject` with the matching internal name, or `null`.
* **`getMiscByName(String name)`**: Returns the `CustomBaseObject` (Misc) with the matching internal name, or `null`.
* **`getCustomItemByName(String name)`**: Returns the `CustomBaseObject` (any type) with the matching internal name, or `null`.
* **`getGunInHand(@NotNull HumanEntity entity)`**: Returns the `Gun` the player is effectively holding (checks main hand and off-hand for iron sights), or `null`.

## Checking Item Types

* **`isCustomItem(ItemStack is)`**: Returns `true` if the `ItemStack` is any registered QA item (Gun, Ammo, Armor, Misc, or registered Expansion item).
* **`isCustomItem(ItemStack is, int dataOffset)`**: Checks if the item would be a custom item if its CustomModelData/Durability were offset by `dataOffset`. Useful for checking durability changes.
* **`isCustomItemNextId(ItemStack is)`**: Checks if an item with the *next* sequential CustomModelData/Durability value (same material) is a registered QA item.
* **`isGun(ItemStack is)`**: Returns `true` if the `ItemStack` is a registered QA gun.
* **`isAmmo(ItemStack is)`**: Returns `true` if the `ItemStack` is a registered QA ammo type.
* **`isArmor(ItemStack is)`**: Returns `true` if the `ItemStack` is a registered QA armor piece.
* **`isMisc(ItemStack is)`**: Returns `true` if the `ItemStack` is a registered QA miscellaneous item.
* **`isAmmoBag(ItemStack is)`**: Returns `true` if the `ItemStack` is a registered QA miscellaneous item that is specifically an `AmmoBag`.
* **`isIronSights(ItemStack is)`**: Returns `true` if the `ItemStack` represents the temporary item shown when aiming down sights.

## Player Interaction & State

### `sendResourcepack(final Player player, final boolean warning)`

**Description**: Sends the appropriate server resource pack to the player after a configured delay (`SecondsTillRPIsSent`). Uses the multi-version system if enabled.

**Parameters**:

* `player`: The player to send the pack to.
* `warning`: If `true`, sends warning messages/titles before sending the pack prompt.

**Note**: Schedules tasks. Relies on `config.yml` settings for URLs, delays, and behavior. Requires ViaVersion for version detection if `Auto-Detect-Resourcepack` is true.

### `allowGunsInRegion(Location loc)`

**Description**: Checks with the registered protection hooks (like WorldGuard) if PvP or gun usage is allowed at the specified location.

**Parameters**:

* `loc`: The `Location` to check.

**Returns**: `true` if allowed, `false` otherwise. Returns `true` if no protection hooks deny it or if hooks fail.

### `sendHotbarGunAmmoCount(final Player p, final CustomBaseObject gun, ItemStack usedItem, boolean reloading)`

**Description**: Sends the ammo count/status message above the player's hotbar. Uses the format defined in `config.yml`.

**Parameters**:

* `p`: The player to send the message to.
* `gun`: The `Gun` or `AttachmentBase` object being used.
* `usedItem`: The `ItemStack` representing the gun in the player's hand.
* `reloading`: `true` if the player is currently reloading this weapon.

### `sendHotbarGunAmmoCount(final Player p, final CustomBaseObject gun, ItemStack usedItem, boolean reloading, int currentAmountInGun, int maxAmount)`

**Description**: Sends the ammo count/status message above the player's hotbar, allowing manual specification of current/max ammo (useful for custom reload handlers).

**Parameters**:

* `p`: The player.
* `gun`: The `Gun` or `AttachmentBase`.
* `usedItem`: The `ItemStack`.
* `reloading`: `true` if reloading.
* `currentAmountInGun`: The current ammo count to display.
* `maxAmount`: The maximum ammo capacity to display.

### `getAmmoInInventory(Player player, Ammo a)`

**Description**: Calculates the total amount of a specific `Ammo` type the player has in their main inventory, including amounts stored in `AmmoBag` items. Returns `99999` if the player is in Creative mode.

**Parameters**:

* `player`: The player whose inventory to check.
* `a`: The `Ammo` type to count.

**Returns**: The total count of the specified ammo.

### `getAmmoInInventory(Player player, Ammo a, boolean ignoreBag)`

**Description**: Calculates the amount of a specific `Ammo` type the player has. Can optionally ignore ammo bags.

**Parameters**:

* `player`: The player.
* `a`: The `Ammo` type.
* `ignoreBag`: If `true`, does not count ammo inside `AmmoBag` items.

**Returns**: The total count of the specified ammo.

### `getAmmoInBag(@NotNull Player player, Ammo a)`

**Description**: Calculates the total amount of a specific `Ammo` type stored *only* within `AmmoBag` items in the player's inventory.

**Parameters**:

* `player`: The player.
* `a`: The `Ammo` type.

**Returns**: The total count within ammo bags.

### `addAmmoToInventory(Player player, Ammo a, int amount)`

**Description**: Attempts to add the specified amount of ammo to the player's inventory, stacking with existing ammo items first, then filling empty slots.

**Parameters**:

* `player`: The player.
* `a`: The `Ammo` type to add.
* `amount`: The quantity to add.

**Returns**: `true` if all ammo was successfully added, `false` if there wasn't enough space.

### `removeAmmoFromInventory(Player player, Ammo a, int amount)`

**Description**: Attempts to remove the specified amount of ammo from the player's inventory, taking from main inventory stacks first, then from `AmmoBag` items if necessary. Does nothing if the player is in Creative mode.

**Parameters**:

* `player`: The player.
* `a`: The `Ammo` type to remove.
* `amount`: The quantity to remove.

**Returns**: `true` if the specified amount was successfully removed, `false` if the player didn't have enough ammo.

* **`getBulletsInHand(Player player)`**: Returns the current ammo count stored in the NBT data of the gun item the player is holding.
* **`isOverLimitForPrimaryWeapons(Gun g, Player p)`**
  * **Description**: Checks if adding the specified gun (`g`) would put the player (`p`) over the primary or secondary weapon limit configured in `config.yml` (if the limiter is enabled).
  * **Parameters**:
    * `g`: The `Gun` being checked.
    * `p`: The player.
  * **Returns**: `true` if the player is already at or above the limit for that weapon type (primary/secondary), `false` otherwise.
* **`giveOrDrop(HumanEntity entity, ItemStack item)`**
  * **Description**: Gives the specified `ItemStack` to the entity. If their inventory is full, drops the item at their location instead.
  * **Parameters**:
    * `entity`: The `HumanEntity` (usually a `Player`) to give the item to.
    * `item`: The `ItemStack` to give.

## Item & Utility Methods

* **`getCustomItemAsItemStack(String name)`**: Retrieves a `CustomBaseObject` by its internal name and returns a fresh `ItemStack` representation of it.
* **`getCustomItemAsItemStack(CustomBaseObject obj)`**: Returns a fresh `ItemStack` representation of the given `CustomBaseObject`. Returns `null` if the input object is `null`.
* **`getIronSightsItemStack()`**: Returns the specific `ItemStack` used to represent the aiming-down-sights view.
* **`findSafeSpot(ItemStack newItem, boolean findHighest, boolean allowPockets)`**: Searches for an unused CustomModelData/Durability value for the given item's Material, starting from the item's current value and searching up (`findHighest = true`) or down (`findHighest = false`). `allowPockets` determines if it searches for any gap or just the absolute highest/lowest used ID. Primarily for internal use or advanced item creation.
* **`findSafeSpot(Material newItemtype, int startingData, boolean findHighest, boolean allowPockets)`**: Same as above, but takes Material and starting data directly.
* **`findSafeSpotVariant(ItemStack newItem, boolean findHighest)`**: Searches for an unused Variant value for the given item's Material and CustomModelData/Durability, starting from 0 and searching up (`findHighest = true`) or down (`findHighest = false`).
* **`findSafeSpotVariant(Material newItemtype, int startingData, boolean findHighest)`**: Same as above, but takes Material and data directly.
* **`getMaxPagesForGUI()`**: Calculates the number of pages needed to display all registered QA items in the default shop/GUI layout (5 rows of 9 items per page).
* **`repeat(String string, int times)`**: A simple utility method to repeat a given string multiple times. Used internally for formatting reload progress bars.


# Adding the Dependency
Source: https://wiki.lorenzo0111.me/qualityarmory/developers/dependency

Learn how to add QualityArmory as a dependency to your project using Maven or Gradle

# Adding the Dependency

In order to use the QualityArmory API you need to add the plugin as a dependency. Replace VERSION with the latest version:

![GitHub release](https://img.shields.io/github/v/release/Lorenzo0111/QualityArmory)

## Java Dependency

<Tabs>
  <Tab title="Maven">
    To add QA to your project using maven, copy the following into the POM.xml.

    ```xml theme={null}
    <repository>
        <id>codemc-repo</id>
        <url>https://repo.codemc.io/repository/maven-public/</url>
    </repository>

    <dependency>
        <groupId>me.zombie_striker</groupId>
        <artifactId>QualityArmory</artifactId>
        <version>VERSION</version>
        <scope>provided</scope>
    </dependency>
    ```
  </Tab>

  <Tab title="Gradle">
    To add QA to your project using gradle, copy the following into the build.gradle.

    ```gradle theme={null}
    repositories {
        maven {
            name = "codemc-repo"
            url = "https://repo.codemc.io/repository/maven-public/"
        }
    }

    dependencies {
        compileOnly 'me.zombie_striker:QualityArmory:VERSION'
    }
    ```
  </Tab>

  <Tab title="Gradle KTS">
    To add QA to your project using gradle, copy the following into the build.gradle.kts.

    ```gradle theme={null}
    repositories {
        maven {
            name = "codemc-repo"
            url = uri("https://repo.codemc.io/repository/maven-public/")
        }
    }

    dependencies {
        compileOnly("me.zombie_striker:QualityArmory:VERSION")
    }
    ```
  </Tab>
</Tabs>

## Plugin Dependency

Add the plugin as a dependency to your plugin by editing the `plugin.yml` file by including the following line under the `depend` section:

```yaml theme={null}
# Use this if QualityArmory is required
depend: [QualityArmory]
# Use this if QualityArmory is optional
softdepend: [QualityArmory]
```

This ensures that your plugin will load after QualityArmory. If your plugin requires specific features from QualityArmory at runtime, remember to also use appropriate checks in your code to confirm that QualityArmory is enabled.


# Getting Started
Source: https://wiki.lorenzo0111.me/qualityarmory/getting-started

Learn how to install QualityArmory and get started with customizing guns and weapons

# Installation

Welcome to QualityArmory (QA). Here you will learn how to customize the plugin and create your own guns.

With QualityArmory you have unlimited possibilities, the only limit is your creativity.

The plugin does not require any other dependency, after downloading the plugin, you are ready to use it.

## Compatibilities

You can install these plugins to add additional features to the plugin

* [LightAPI](https://www.spigotmc.org/resources/lightapi.4510/): Used for muzzle flashes when guns are used.
* [Parties](https://www.spigotmc.org/resources/parties-an-advanced-parties-manager.3709/): Used to disable friendly fire.
* [ProtocolLib](https://www.spigotmc.org/resources/protocollib.1997/): Used to smoothly change player's Yaw for recoil when guns are used
* [Vault](https://www.spigotmc.org/resources/vault.34315/updates): Used for the weapon shop, requires also an economy plugin such as [EssentialsX](https://www.spigotmc.org/resources/9089/)
* [ViaVersion](https://www.spigotmc.org/resources/viaversion.19254/): QualityArmory has ViaVersion support that allows players from different minecraft updates to see the same models
* [ItemBridge](https://www.spigotmc.org/resources/itembridge-save-items-and-use-them-wherever-you-want-including-other-plugins.77080/): This plugin allows other plugins to access QualityArmory items if they support that plugin.
* Others plugins are also supported but not listed here

<Warning>
  This documentation has been written with the help of AI, some data may be inaccurate. If you found an issue, feel free to contact me on the discord server.
</Warning>


# Ammo Configuration
Source: https://wiki.lorenzo0111.me/qualityarmory/items/ammo

Complete reference for all ammo configuration options in QualityArmory

# Ammo Configuration

<Info>I suggest copying another ammo's configuration as a reference</Info>

These are all the fields used by an ammo with their description:

* `invalid`: If set to `true`, this ammo configuration file will be skipped during loading. Defaults to `false`
* `name`: The internal, unique identifier for this ammo type. Used for referencing this ammo in gun configurations
* `displayname`: The name shown in-game for the ammo item. Supports color codes (e.g., `&f`). Defaults to the `name` if not specified
* `lore`: A list of strings that will appear as the item's lore (description below the name). Supports color codes
* `id`: The ammo id, used as durability before Minecraft `1.13` and for custom model data for newer versions
* `variant`: Used for item variants (e.g., different wood types, potion effects). Defaults to 0
* `craftingRequirements`: Defines the materials needed to craft this ammo. Each string follows the format `MATERIAL_NAME,DATA_VALUE,AMOUNT`
* `craftingReturnAmount`: The quantity of ammo items produced when crafted using the `craftingRequirements`
* `price`: The cost to purchase this ammo from the shop. If the price is 0 or less, `allowInShop` defaults to false. Defaults to 100
* `allowInShop`: Explicitly sets whether this ammo can be bought in the shop. Defaults to `true` if `price` is greater than 0
* `maxItemStack`: The maximum number of this ammo item that can be held in a single inventory stack
* `material`: The Bukkit Material name for the item used as ammo (e.g., `PHANTOM_MEMBRANE`, `IRON_NUGGET`)
* `skull_owner`: If `material` is `PLAYER_HEAD`, this sets the head's owner by player name
* `skull_owner_custom_url`: If `material` is `PLAYER_HEAD`, this sets the head's skin using a Base64 texture URL
* `piercingSeverity`: Multiplier applied to the base gun damage


# Armor Configuration
Source: https://wiki.lorenzo0111.me/qualityarmory/items/armor

Complete reference for all armor configuration options in QualityArmory

# Armor Configuration

<Info>I suggest copying another armor's configuration as a reference</Info>

These are all the fields used by an armor with their description:

* `invalid`: If set to `true`, this armor configuration file will be skipped during loading. Defaults to `false`
* `name` : The internal, unique identifier for this armor piece
* `displayname`: The name shown in-game for the armor item. Supports color codes (e.g., `&6`). Defaults to the `name` with white color if not specified
* `lore`: A list of strings that will appear as the item's lore (description below the name). Supports color codes
* `id`: The armor id, used as durability before Minecraft `1.13` and for custom model data for newer versions
* `variant`: Used for item variants. Defaults to 0
* `craftingRequirements`: Defines the materials needed to craft this armor. Each string follows the format `MATERIAL_NAME,DATA_VALUE,AMOUNT`
* `price`: The cost to purchase this armor from the shop. If the price is 0 or less, `allowInShop` defaults to false. Defaults to 100
* `allowInShop`: Explicitly sets whether this armor can be bought in the shop
* `MiscType`: Specifies the type of item. For armor, this should be `HELMET`
* `minProtectionHeight`: The minimum Y-coordinate relative to the player's feet where the helmet provides protection
* `maxProtectionHeight`: The maximum Y-coordinate relative to the player's feet where the helmet provides protection
* `protection` The amount of armor points this item provides. Defaults to 0. This value is used to add the `generic.armor` attribute modifier to the item
* `material`: The Bukkit Material name for the item used as armor. Defaults to `DIAMOND_AXE` if not specified


# Gun Configuration
Source: https://wiki.lorenzo0111.me/qualityarmory/items/gun

Complete reference for all gun configuration options in QualityArmory

# Gun Configuration

Creating a gun requires many steps, from configuring the settings to creating the model.

<Info>I suggest copying another gun's configuration as a reference</Info>

These are all the fields used by a gun with their description:

* `name`: The internal, unique identifier for the weapon used in commands (e.g., `/qa give cz75`). It's recommended to keep this lowercase and without space
* **`displayname`**: The name shown on the item in-game. Supports standard Minecraft color codes (e.g., `&6`).
* **`id`**: Used with `material` and `variant` to uniquely identify the item type.
  * **Minecraft `1.14+`**: This value corresponds to the `CustomModelData` tag on the item, used by resource packs to apply the correct model/texture.
  * **Minecraft `<1.14`**: This value corresponds to the item's durability/damage value, used by resource packs to apply the correct model/texture.
* **`variant`**: An additional identifier used alongside `material` and `id`. Allows creating different guns that use the same base `material` and `id`/`CustomModelData` but have different stats or behaviors.
* **`craftingRequirements`**: A list of materials required to craft this item using the `/qa craft` system. Format for each entry: `'MATERIAL_NAME,METADATA/DAMAGE_VALUE,AMOUNT'`. (Metadata/Damage value is often 0 for modern versions).
* **`weapontype`**: Classifies the weapon. Primarily used for organization and potentially by other plugins or specific features (like weapon limits). Can influence default sounds if `weaponsounds` isn't set. Valid types are: `PISTOL,SMG,RPG,RIFLE,SHOTGUN,FLAMER,SNIPER,BIG_GUN,GRENADES,SMOKE_GRENADES,FLASHBANGS,INCENDARY_GRENADES,MOLOTOV,PROXYMINES,STICKYGRENADE,MINES,MELEE,MISC,AMMO,HELMET,MEDKIT,AMMO_BAG,LAZER,BACKPACK,PARACHUTE,CUSTOM`
* **`weaponsounds`**: The sound event name(s) played when the weapon is fired. Can be a single string or a list of strings for variety. If omitted, a default sound based on `weapontype` is used.
* **`enableIronSights`**: If `true`, allows the player to aim down sights. Behavior depends on `IronSightsOnRightClick` in `config.yml`. If `false`, right-click (or the aim key) typically triggers reload.
* **`ammotype`**: The internal name of the `Ammo` item required to reload and fire this weapon. Must match the `name` field of an ammo configuration file. If omitted or invalid, the gun might have infinite ammo implicitly.
* **`damage`**: The base amount of damage each bullet inflicts upon hitting an entity. Headshots may multiply this.
* **`maxbullets`**: The maximum number of bullets the weapon can hold in its magazine/chamber.
* **`price`**: The cost of the weapon in the `/qa shop` if enabled.
  * If set to `-1` the gun won't show in the shop
* **`isPrimaryWeapon`**: Used by the weapon limiter feature (if enabled in `config.yml`). `true` classifies it as a primary weapon, `false` as secondary.
* **`material`**: The base Minecraft item material used for this weapon. This affects the item's appearance if no resource pack is used and is crucial for resource packs to target the item. `CROSSBOW` and `BOW` allow for charging animations, `FISHING_ROD` can work for some effects, otherwise `DIAMOND_HOE` or other tools/items are common.
* **`invalid`**: If set to `true`, QualityArmory will ignore this file and not load the weapon. Useful for temporarily disabling a weapon without deleting the file.
* **`durability`**: The total durability points the weapon has if `EnableWeaponDurability` is `true` in `config.yml`. Each shot or configured action consumes durability.
* **`maxItemStack`**: The maximum stack size for this item in inventories. Typically `1` for weapons.
* **`setZoomLevel`**: Applies a Slowness effect to simulate scope zoom when aiming (if `enableIronSights` is true). `0` = no zoom, `1` = Slowness I, `2` = Slowness II, etc. Higher values mean more zoom.
* **`sway`**: Configures weapon accuracy (spread). Lower values are more accurate.
  * **`defaultValue`**: The base sway value when standing still and not aiming/sneaking.
  * **`defaultMultiplier`**: A general multiplier applied to sway calculations, potentially affecting how much movement/running impacts accuracy.
  * **`sneakModifier`**: If `true`, sway is affected by the global `swayModifier_Sneak` from `config.yml` when the player is sneaking.
  * **`moveModifier`**: If `true`, sway is affected by the global `swayModifier_Walk` from `config.yml` when the player is walking.
  * **`runModifier`**: If `true`, sway is affected by the global `swayModifier_Run` from `config.yml` when the player is sprinting.
* **`firerate`**: For automatic weapons (`isAutomatic: true`), this controls how many shots are fired per "burst" or firing cycle. Often kept at `1`. The actual speed is controlled more by `delayForShoot`.
* **`delayForReload`**: The time in seconds it takes to reload the weapon.
* **`delayForShoot`**: The minimum time in seconds between consecutive shots (fire rate limiter). Lower values mean faster firing.
* **`bullets-per-shot`**: The number of bullets consumed and fired with each shot. Useful for shotguns (e.g., `8`), but each projectile calculates damage independently.
* **`isAutomatic`**: If `true`, the weapon can fire continuously when the fire button is held down (respecting `delayForShoot`). If `false`, it's semi-automatic (one shot per click).
* **`maxBulletDistance`**: The maximum distance (in blocks) a bullet will travel before despawning or stopping calculation.
* **`unlimitedAmmo`**: If `true`, the weapon does not consume ammo and does not need reloading.
* **`LightLeveOnShoot`**: If LightAPI is installed, creates a temporary light source with this light level (0-15) at the shooter's location when firing.
* **`recoil`**: The magnitude of vertical camera kick applied to the shooter when firing, if `enableRecoil` is true in `config.yml`.
* **`slownessOnEquip`**: Applies a permanent Slowness effect to the player while holding this weapon. `0` = no effect, `1` = Slowness I, `2` = Slowness II, etc.
* **`particles`**: Configures the bullet trail particle effect if `enableBulletTrails` is true in `config.yml`.
  * **`bullet_particle`**: The name of the particle type to use (from Bukkit `Particle` enum). `REDSTONE` is special as it allows custom colors via RGB.
  * **`bullet_particleR`**: Red component (0.0-1.0) for `REDSTONE` particles.
  * **`bullet_particleG`**: Green component (0.0-1.0) for `REDSTONE` particles.
  * **`bullet_particleB`**: Blue component (0.0-1.0) for `REDSTONE` particles.
  * **`bullet_particleData`**: Extra data value for certain particle types (often unused, 0).
  * **`bullet_particleMaterial`**: For particles like `BLOCK_DUST`, specifies the material whose texture is used.
* **`Version_18_Support`**: A flag potentially used for compatibility adjustments or model selection when ViaVersion/ViaRewind are present, indicating if the model is primarily designed for `1.8` clients.
* **`ChargingHandler`**: Specifies a custom Java class (handler) to manage weapon charging behavior (e.g., bows, miniguns). `none` means no special charging mechanic. Requires custom coding to add new handlers.
* **`ReloadingHandler`**: Specifies a custom Java class (handler) to manage weapon reloading behavior (e.g., shotguns reloading one shell at a time). `none` uses the default magazine reload. Requires custom coding to add new handlers.
* **`addMuzzleSmoke`**: If `true`, spawns a brief smoke particle effect at the barrel when firing.
* **`drop-glow-color`**: If set to a valid ChatColor name (e.g., `RED`, `GOLD`), makes the dropped item entity glow with that color. `none` disables the glow.
* **`headshotMultiplier`**: The factor by which base `damage` is multiplied when a headshot occurs. `1.0` means no extra damage.
* **`weaponsounds_volume`**: Controls the volume multiplier for the firing sounds (`weaponsounds`).
* **`firing_knockback`**: Applies a knockback force *to the shooter* when firing. Negative values push backwards.
* **`KilledByMessage`**: The custom death message format used when a player is killed by this weapon. Placeholders: `%player%` (victim), `%killer%` (attacker), `%name%` (weapon display name).
* **`DestructableMaterials`**: A list of block material names (e.g., `GLASS`, `WHITE_WOOL`) that bullets from this specific gun can break. Requires `enableExplosionDamage` or similar features to be enabled globally or per-weapon. `MATERIAL_NAME_HERE` is a placeholder.
* **`sound_equip`**: A sound that is played when the weapon is equipped.
* **`sound_equip_volume`**: The volume of the equip sound.
* **`sound_meleehit`**: A sound that is played when the weapon is used as a melee weapon.
* **`sound_meleehit_volume`**: The volume of the melee hit sound.


# ResourcePack Model
Source: https://wiki.lorenzo0111.me/qualityarmory/items/model

Learn how to create and integrate custom gun models into your resource pack

# Creating the Model

I suggest watching a tutorial on YouTube to learn how to create a model, here is a suggested one:

<iframe title="YouTube video player" />

## Choosing a Model Editor

* **For Simple Models:**
  MrCrayfish's Model Creator works well for basic guns.
* **For Advanced Models:**
  [BlockBench](http://blockbench.net) is recommended. It supports groups and complex display settings, making it ideal for first-person/off-hand configuration and iron sight alignment.

## Exporting the Model

1. Build your gun model in BlockBench.

2. Export it as a `.json` file once complete.

3. **Name the file the same as the gun** (e.g., `ak47.json`). This keeps things organized and makes it easier to update models later.

   * **Note:** From Minecraft **`1.12+`**, filenames **must be all lowercase**

## Adding Iron Sights

If you want to add iron sights:

* Set **first-person off-hand display** values — QA uses off-hand for scoping, but it appears in the **right hand**.
* Also define the **third-person display values** for proper iron sight positioning.
* You can use existing models in the pack as references to copy values or setups.

## Integrating the Model in Resource Packs

### Minecraft 1.9 – 1.13

You'll need to modify the `diamond_axe.json` file at `/assets/minecraft/models/item/diamond_axe.json`

Find the JSON object structure that looks like this:

```json theme={null}
{
    "predicate": {
        "damaged": 0,
        "damage": 0.0161
    },
    "model": "item/aa12"
},
```

Insert a new entry after the closing }, like so:

```json theme={null}
{
    "predicate": {
        "damaged": 0,
        "damage": ID
    },
    "model": "item/MODEL"
}
```

Replace the placeholders:

```yaml theme={null}
ID:
Calculated as 0.0161 + (0.006 * index)
(e.g., ID 27 → 0.0167, ID 28 → 0.0173, etc.)

MODEL:
The model file name (without .json)
```

### Minecraft 1.14+

In `1.14+`, Mojang introduced the custom\_model\_data tag — a cleaner way to add models.
You can modify `/assets/minecraft/models/item/crossbow.json` and add a new entry:

Here's an example structure:

```json theme={null}
{
    "predicate": {
        "custom_model_data": 66
    },
    "model": "item/stengun"
},
{
    "predicate": {
        "custom_model_data": 67
    },
    "model": "item/m32a1"
},
{
    "predicate": {
        "custom_model_data": 68
    },
    "model": "item/aiming"
}
```

Add your custom gun model:

```json theme={null}
{
    "predicate": {
        "custom_model_data": ID
    },
    "model": "item/MODEL"
}
```

Replace the placeholders:

```yaml theme={null}
ID:
This should match the custom_model_data value set in your plugin/mod (e.g., in the YAML config).

MODEL:
Name of your model file (no .json extension).
```


# Configuration
Source: https://wiki.lorenzo0111.me/qualityarmoryvehicles/configuration

Complete reference for all configuration options in QualityArmoryVehicles

# Configuration

The configuration documentation is structured in the following format:

**Title**: Setting\
**Description**: What the setting does

<Info>
  If an option is not documented on this list, it is a deprecated or a no longer used option
</Info>

## prefix

The prefix of the plugin. It is used in all messages.\
To disable it, just set it to "".

## USE\_1\_13\_MODEL\_SYSTEM

If set to true, the plugin will use a legacy method for handling vehicles.

## enable\_VehicleLimiter

If set to true, the plugin will limit per-player owned vehicles based on their permission.\
For example, if the player has the `qualityarmoryvehicles.vehiclelimit.5` permission, he will have a limit of 5 vehicles.

## enable\_PickupVehicles

If set to true, players will be able to pick up the vehicle from the gui.

## enable\_UnlockableVehicles

If set to true, when picking up a vehicle, it will be put in the player's garage.

## enable\_GarageCallback

If set to true, players will be able to pick up their spawned vehicles by clicking on it in the /garage gui.

## enable\_RequirePermsToDriveType

If set to true, players will have to have a permission to drive a vehicle.\
For example `qualityarmoryvehicles.candrive.ambulance`.

## enable\_SetOwnerOnVehicleSpawn

If set to true, when a vehicle is spawned, it will be automatically owned by the player who placed it.

## enable\_VehicleDamage

If set to true, players will be able to damage a vehicle with a gun or by hitting it.

## enable\_SetOwnerOfVehicleIfUnowned

If set to true, when a player enters a vehicle's driver seat, if no owner is set, he will become the vehicle's owner.

## Enable\_Creation\_Of\_Default\_Files

If set to true, the plugin will generate example vehicles files.

## enable\_RemoveVehiclesOnDismount

If set to true, when a user dismounts a vehicle, it will be picked up.

## enable\_RemoveVehiclesOnPlayerQuit

If set to true, when a user quits, his vehicle will be picked up.

## enable\_DestroyVehiclesOnPlayerQuit

If set to true, when a user quits, his vehicle will be destroyed.

## enable\_StopCreativeDuplication

If set to true, users will not be able to duplicate vehicles from the creative inventory.

## enable\_VehiclePlayerCollision

If set to true, vehicles will have collisions when they collide with others or with players.

<Warning>
  In rare cases, it may cause some small lag on the first collision. If this happens, I suggest disabling this option.
</Warning>

## enable\_SwapEndermiteWithCheckenForLowRider

If set to true, the plugin will use chickens for the passenger seats.

## enable\_FuelCarsWhenSpawnedFromGarage

If set to true, when picking a vehicle from the garage, it will be fueled.

## enable\_UseHeadsForGUI

If set to true, the plugin will use heads to make the vehicle gui cooler.

## enable\_AntiCheatHook

If set to true, the plugin will hook with the internal Minecraft anticheat to prevent users from getting kicked for flying.

## freezeOnDestroy

If set to true, when a vehicle is destroyed, it will be frozen and not removed.

## bypassCoalInCreative

If set to true, users will be able to bypass fuel requirement when in creative mode.

## sendActionBarOnMove

If set to true, users will see a customizable message in the actionbar when moving with a vehicle.

## enableShopCooldown

If set to true, there will be a cooldown of some milliseconds when shopping items in the /qav shop to prevent bugs.

## makeVehiclesPublic

If set to true, all vehicles will be public.

## enable\_RequirePermToBuyVehicle

If set to true, players will need to have a permission to buy a vehicle.\
The permission format is: `qualityarmoryvehicles.candrive.<type>`

## enable\_VehiclesHaveTrunks

If set to true, vehicles will have a trunk to store items.

## blockAccelerationReduction

This contains a list of blocks to accelerate the vehicle.\
This is the format:

```yaml theme={null}
blockAccelerationReduction:
  BLOCK_NAME: 1.0
```

You can get a list of block names [here](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html).

## enable\_RemoveVehiclesOnEmpty

If set to true, when a vehicle is empty, it will be picked up.

## BlacklistedWorlds

A list of worlds where the vehicles can't be used.

## maxYHeight

The max height for using vehicles.

## enable\_useChatForOutOfdFuelMessage

If set to true, when a vehicle will be out of fuel, a message will be sent to the user in the chat. If set to false, that message will be sent in the actionbar.

## enable\_DestroyVehiclesOnWater

If set to true, when a vehicle will touch water, it will be destroyed.

## modernPlaneMovements

If set true, the planes and helicopters will have easier controls.


# Getting Started
Source: https://wiki.lorenzo0111.me/qualityarmoryvehicles/getting-started

Learn how to install QualityArmoryVehicles and get started with custom vehicles

# Getting Started

Installing the plugin is very simple. There are only 4 steps to do.

* [ ] Buy the plugin
* [ ] Drag the jar in the plugins folder
* [ ] Install [ProtocolLib](https://www.spigotmc.org/resources/protocollib.1997/)
* [ ] Start the server


# ResourcePack
Source: https://wiki.lorenzo0111.me/qualityarmoryvehicles/installation/resourcepack

Learn how to set up the resource pack for QualityArmoryVehicles custom models

# ResourcePack

QualityArmoryVehicles uses a resourcepack to create realistic vehicles without replacing existing minecraft items.

Every user of the server should install the resourcepack to see them.

## Automatic installation

With the automatic installation, the resourcepack is downloaded and enabled by default on player join.

## Manual installation

If you set the QAMini.sendResourcepackOnJoin option to `false`.

<Warning>
  This will only work if QualityArmory is not installed.

  If it is installed the resourcepack will be handled from that plugin.
</Warning>


# Creating a Vehicle
Source: https://wiki.lorenzo0111.me/qualityarmoryvehicles/vehicles/creating-vehicle

Complete guide to creating and configuring custom vehicles in QualityArmoryVehicles

# Creating a Vehicle

For creating a vehicle I suggest editing a premade configuration.

These are all settings.

## vehicle\_type

The vehicle type.\
Available types: Car, Plane, Boat, Helicopter, Train, Drill, Tractor.

## name

The vehicle name, it must be unique.

## id

The vehicle id, it must be unique.

## displayname

The vehicle display name.

## center

A vector displaying the center of that vehicle.

## passagers

A list of vectors representing the position of the passengers' seats.

## stopMeleeDamage

If set to true, the vehicle will not be damaged by guns.

## RequiresFuel

If set to true, the vehicle will require the fuel for being used.

## widthOffset

The width of the hitbox

## heightOffset

The height of the hitbox

## vehicle\_texture\_material

The item of the vehicle

## maxHealth

The max health of the vehicle

## cost

The cost of the vehicle in the shop. To disable it, set it to -1.

## InputManager

A map of registered inputs.

Input types: HONK, SIREN, MININUKE\_BOMBER, TNT\_BOMBER, 40MM\_LAUNCHER, BULLETS\_556.

## ItemLore

A list of strings for the item lore

## TurnSpeedInRadians

The turn speed

## trunksize

The size of how many items can the trunk contain.

## allowedInShop

If set to true, players will be able to buy the vehicle from the shop.

## maxAcceleration

The max speed for the vehicle

## baseAcceleration

The base speed for the vehicle

## maxReverseAcceleration

The max reverse speed for the vehicle

## canJumpOnBlocks

If set to true, the vehicle will be able to jump on blocks

## jumpHeight

The height of how many blocks can the vehicle jump

## model.ModelSize

Current available options: BABY\_ARMORSTAND\_HEAD, ADULT\_ARMORSTAND\_HEAD, ADULT\_ARMORSTAND\_HAND, TURTLE

## rotationMultiplier

A number that is multiplied by the calculated rotation.

## sound

The id of the sound that is played while driving

## soundVolume

The volume of the sound

## driverseat.Offset

The vector that represents the position of the driver seat.


# Creating the Model
Source: https://wiki.lorenzo0111.me/qualityarmoryvehicles/vehicles/model

Learn how to create custom vehicle models for QualityArmoryVehicles

# Creating the Model

This is the hardest part but it's not impossible and you can do it. 💪

You can follow a tutorial on YouTube.

Here are some examples:

## Creating a model

<iframe title="Creating a model - YouTube video" />

## Creating a vehicle

<iframe title="Creating a vehicle - YouTube video" />


# Conditions
Source: https://wiki.lorenzo0111.me/rocketjoin/conditions

Learn how to create custom conditions for special join and leave messages based on permissions, first join, and more

# Conditions

RocketJoin's conditions system allows you to create custom join and leave messages for specific players based on various criteria. This system is similar to the RocketPlaceholders conditions system.

## Overview

Conditions let you customize messages for players who meet specific requirements, such as:

* Having a certain permission
* Joining for the first time
* Meeting custom criteria

## How Conditions Work

Conditions are evaluated in order, and the first matching condition will be used. This allows you to create priority-based message systems.

## Configuration Example

Here's a basic example of how to configure conditions:

```yaml theme={null}
conditions:
  example-vip:
    # Type of the condition
    type: PERMISSION
    # Optional: Value (depends on condition type)
    value: "rocketjoin.vip"

    # Join and leave messages
    join: "&e&l» &6&lVIP &7{player} joined!"
    leave: "&e&l» &6&lVIP &7{player} left!"
    
    # Sound options
    sound: true
    sound-type: "entity.experience_orb.pickup"
    
    # Fireworks options
    fireworks: false
    fireworks-amount: 3
    
    # Commands to execute on join. Placeholders: {player}
    commands: []
```

## Available Condition Types

RocketJoin supports the following condition types:

### Permission Condition

Check if a player has a specific permission node.

**Type:** `PERMISSION`\
**Requires:** Value (permission node)

See the [Permission Condition](/rocketjoin/conditions/permission) guide for details.

### First Join Condition

Trigger when a player joins for the first time.

**Type:** `FIRST`\
**Requires:** No value needed

See the [First Join Condition](/rocketjoin/conditions/first-join) guide for details.

## Condition Options

Each condition can have the following options:

### Messages

* **`join`** - Custom join message for players matching this condition
* **`leave`** - Custom leave message for players matching this condition

Both support all standard placeholders and color codes.

### Sound Effects

* **`sound`** - Enable or disable sound effects (true/false)
* **`sound-type`** - The sound to play. See the [Bukkit Sound enum](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html) for available sounds.

<Info>
  Common sound types include:

  * `entity.experience_orb.pickup` - Experience orb pickup sound
  * `entity.player.levelup` - Level up sound
  * `block.note_block.pling` - Note block pling
  * `ui.toast.challenge_complete` - Challenge complete sound
</Info>

### Fireworks

* **`fireworks`** - Enable or disable fireworks (true/false)
* **`fireworks-amount`** - Number of fireworks to spawn

<Warning>
  Fireworks and sounds don't work on proxy servers (BungeeCord/Velocity). They only work on Bukkit/Spigot/Paper servers.
</Warning>

### Commands

* **`commands`** - List of commands to execute from console when a player matching this condition joins. Use `{player}` placeholder in commands.

## Priority System

Conditions are evaluated in the order they appear in the configuration file. The first matching condition will be used, so order matters!

**Example:**

```yaml theme={null}
conditions:
  vip:
    type: PERMISSION
    value: "rocketjoin.vip"
    join: "&e&lVIP {player} joined!"
  
  premium:
    type: PERMISSION
    value: "rocketjoin.premium"
    join: "&6&lPREMIUM {player} joined!"
```

If a player has both `rocketjoin.vip` and `rocketjoin.premium` permissions, they will see the VIP message because it's listed first.

## Advanced Examples

### Multiple Conditions

You can create complex condition setups:

```yaml theme={null}
conditions:
  first-join:
    type: FIRST
    join: "&a&lWelcome {player} to the server for the first time!"
    sound: true
    sound-type: "entity.player.levelup"
    fireworks: true
    fireworks-amount: 5
  
  admin:
    type: PERMISSION
    value: "rocketjoin.admin"
    join: "&c&l[ADMIN] &7{player} joined!"
    leave: "&c&l[ADMIN] &7{player} left!"
  
  vip:
    type: PERMISSION
    value: "rocketjoin.vip"
    join: "&e&l[VIP] &7{player} joined!"
    leave: "&e&l[VIP] &7{player} left!"
```

### Condition with Commands

Execute commands when specific players join:

```yaml theme={null}
conditions:
  staff:
    type: PERMISSION
    value: "rocketjoin.staff"
    join: "&b&l[STAFF] &7{player} joined!"
    commands:
      - "say Welcome back, {player}!"
      - "give {player} diamond 1"
```

## Related Guides

* [Permission Condition](/rocketjoin/conditions/permission) - Detailed permission condition guide
* [First Join Condition](/rocketjoin/conditions/first-join) - First join condition guide
* [Configuration](/rocketjoin/configuration) - General configuration guide


# First Join Condition
Source: https://wiki.lorenzo0111.me/rocketjoin/conditions/first-join

Create special welcome messages for players joining your server for the first time

# First Join Condition

The First Join condition allows you to create special welcome messages and effects for players who are joining your server for the first time.

## Overview

This condition is perfect for creating memorable first impressions and welcoming new players to your community.

## Configuration

To create a first join condition, simply set the type to `FIRST`. No value is required.

### Basic Example

```yaml theme={null}
conditions:
  firstJoinExample:
    type: FIRST
    join: "&a&lWelcome {player} to the server for the first time!"
    leave: "&7{player} left"
```

## How It Works

When a player joins:

1. RocketJoin checks if this is their first time joining the server
2. If it is, the custom first join message is displayed
3. If not, the default message (or next matching condition) is used

<Info>
  The first join status is tracked per server. If you're using a proxy setup, each server tracks first joins independently.
</Info>

## Real-World Examples

### Simple Welcome

```yaml theme={null}
conditions:
  first-join:
    type: FIRST
    join: "&a&lWelcome {player} to our server!"
    leave: "&7{player} left"
```

### Enhanced Welcome with Effects

```yaml theme={null}
conditions:
  first-join:
    type: FIRST
    join: "&a&l» &e&lNEW PLAYER &a&l« &7Welcome {player} to the server!"
    leave: "&7{player} left"
    sound: true
    sound-type: "entity.player.levelup"
    fireworks: true
    fireworks-amount: 10
```

### Welcome with Commands

```yaml theme={null}
conditions:
  first-join:
    type: FIRST
    join: "&a&lWelcome {player}! Check out /help to get started!"
    leave: "&7{player} left"
    sound: true
    sound-type: "entity.player.levelup"
    commands:
      - "give {player} bread 5"
      - "give {player} wooden_sword 1"
      - "say Welcome {player} to the server!"
```

## Combining with Other Conditions

You can combine first join with other conditions. The first join condition should typically be placed first in your configuration to ensure it takes priority:

```yaml theme={null}
conditions:
  first-join:
    type: FIRST
    join: "&a&lWelcome {player} to the server for the first time!"
    sound: true
    sound-type: "entity.player.levelup"
    fireworks: true
    fireworks-amount: 10
  
  vip:
    type: PERMISSION
    value: "rocketjoin.vip"
    join: "&e&lVIP &7{player} joined!"
```

<Info>
  In this example, if a VIP player joins for the first time, they'll see the first join message because it's listed first. After their first join, they'll see the VIP message on subsequent joins.
</Info>

## Advanced Example

Here's a comprehensive first join setup:

```yaml theme={null}
conditions:
  first-join:
    type: FIRST
    join: |
      &8&l&m========================================
      &a&l  WELCOME {player}!
      &7This is your first time on our server!
      &7Use /help to get started
      &7Use /spawn to go to spawn
      &8&l&m========================================
    leave: "&7{player} left"
    sound: true
    sound-type: "entity.player.levelup"
    fireworks: true
    fireworks-amount: 15
    commands:
      - "give {player} bread 10"
      - "give {player} wooden_sword 1"
      - "give {player} leather_helmet 1"
      - "give {player} leather_chestplate 1"
      - "give {player} leather_leggings 1"
      - "give {player} leather_boots 1"
      - "say Welcome {player} to the server! Check out /help!"
```

## Tips and Best Practices

1. **Make it memorable** - First impressions matter! Use eye-catching colors and effects.

2. **Provide guidance** - Include helpful commands or tips in your first join message.

3. **Use multi-line messages** - Use `|` in YAML for multi-line messages to create formatted welcome messages.

4. **Combine with starter kits** - Use the `commands` option to give new players starter items.

5. **Test thoroughly** - Make sure to test your first join condition by using a test account or clearing player data.

## Troubleshooting

**Q: The first join message isn't showing up**\
A: Make sure the condition is placed before other conditions in your config. Also verify that the player hasn't joined before (check your server's player data).

**Q: Can I reset first join status?**\
A: First join status is stored in your server's player data. You may need to clear player data or use a plugin that manages this.

## Related Guides

* [Conditions Overview](/rocketjoin/conditions) - Learn about all condition types
* [Permission Condition](/rocketjoin/conditions/permission) - Permission-based conditions
* [Configuration](/rocketjoin/configuration) - General configuration guide


# Permission Condition
Source: https://wiki.lorenzo0111.me/rocketjoin/conditions/permission

Learn how to create custom join and leave messages for players with specific permissions

# Permission Condition

The Permission condition allows you to create custom join and leave messages for players who have a specific permission node.

## Overview

This is one of the most commonly used conditions, perfect for creating VIP, staff, or rank-based messages.

## Configuration

To create a permission condition, set the type to `PERMISSION` and provide the permission node as the value.

### Basic Example

```yaml theme={null}
conditions:
  permissionExample:
    type: PERMISSION
    value: "example.permission"
    join: "&e&lVIP &7{player} joined!"
    leave: "&e&lVIP &7{player} left!"
```

## How It Works

When a player joins or leaves:

1. RocketJoin checks if the player has the specified permission
2. If they do, the custom message is displayed
3. If they don't, the default message (or next matching condition) is used

## Real-World Examples

### VIP Players

```yaml theme={null}
conditions:
  vip:
    type: PERMISSION
    value: "rocketjoin.vip"
    join: "&e&l» &6&lVIP &7{player} joined!"
    leave: "&e&l» &6&lVIP &7{player} left!"
    sound: true
    sound-type: "entity.experience_orb.pickup"
```

### Staff Members

```yaml theme={null}
conditions:
  staff:
    type: PERMISSION
    value: "rocketjoin.staff"
    join: "&b&l[STAFF] &7{player} joined!"
    leave: "&b&l[STAFF] &7{player} left!"
    sound: true
    sound-type: "entity.player.levelup"
```

### Administrators

```yaml theme={null}
conditions:
  admin:
    type: PERMISSION
    value: "rocketjoin.admin"
    join: "&c&l[ADMIN] &7{player} joined!"
    leave: "&c&l[ADMIN] &7{player} left!"
    sound: true
    sound-type: "ui.toast.challenge_complete"
    fireworks: true
    fireworks-amount: 3
```

## Permission Node Best Practices

<Info>
  Use descriptive permission nodes that follow a clear hierarchy:

  * `rocketjoin.vip` - For VIP players
  * `rocketjoin.staff` - For staff members
  * `rocketjoin.admin` - For administrators
  * `rocketjoin.moderator` - For moderators
</Info>

## Combining with Other Options

You can combine permission conditions with sounds, fireworks, and commands:

```yaml theme={null}
conditions:
  premium:
    type: PERMISSION
    value: "rocketjoin.premium"
    join: "&6&l[PREMIUM] &7{player} joined!"
    leave: "&6&l[PREMIUM] &7{player} left!"
    sound: true
    sound-type: "entity.experience_orb.pickup"
    fireworks: true
    fireworks-amount: 5
    commands:
      - "say Welcome back, {player}!"
```

## Priority Considerations

Remember that conditions are evaluated in order. If a player has multiple permissions, the first matching condition will be used.

**Example:**

```yaml theme={null}
conditions:
  vip:
    type: PERMISSION
    value: "rocketjoin.vip"
    join: "&eVIP {player} joined!"
  
  premium:
    type: PERMISSION
    value: "rocketjoin.premium"
    join: "&6PREMIUM {player} joined!"
```

If a player has both permissions, they'll see the VIP message because it's listed first.

## Related Guides

* [Conditions Overview](/rocketjoin/conditions) - Learn about all condition types
* [First Join Condition](/rocketjoin/conditions/first-join) - First join condition
* [Configuration](/rocketjoin/configuration) - General configuration guide


# Configuration
Source: https://wiki.lorenzo0111.me/rocketjoin/configuration

Complete guide to configuring RocketJoin join messages, leave messages, titles, sounds, fireworks, and custom conditions

# Configuration

RocketJoin's configuration is straightforward and powerful. This guide will walk you through all available options.

## Configuration Overview

The config file is located at `plugins/RocketJoin/config.yml`. For each message string such as the `message` one, you can use a list to let the plugin choose a random one each time.

### Random Messages Example

```yaml theme={null}
message:
  - "&a{player} &7joined!"
  - "&a{player} &7appeared!"
```

Each time a player joins, RocketJoin will randomly select one of these messages.

## Default Configuration

Here's the complete default configuration with explanations:

```yaml theme={null}
#    _____            _        _          _       _
#    |  __ \          | |      | |        | |     (_)
#    | |__) |___   ___| | _____| |_       | | ___  _ _ __
#    |  _  // _ \ / __| |/ / _ \ __|  _   | |/ _ \| | '_ \
#    | | \ \ (_) | (__|   <  __/ |_  | |__| | (_) | | | | |
#    |_|  \_\___/ \___|_|\_\___|\__|  \____/ \___/|_|_| |_|

# Do not change these values
config-version: @version@
already-asked: false

# WARNING: If this plugin is running on bungeecord or velocity please read the proxy guide
# Start of the configuration

prefix: "&8&l»"

# Enable Update Message on Join. Default: true
update-message: true

# Placeholders: {Player} (Name) and {DisplayPlayer} (Display Name)
# PlaceholderAPI Support! Download it from tinyurl.com/PlaceholderAPI

# Join message
# Note:
# otherServerMessage is only available in a proxy( Velocity or Bungeecord)
# Additional placeholders: {server}
join:
  enabled: true
  message: "&a{player} &7joined!"
  otherServerMessage: "&a{player} &7joined &a{server}!"
  enable-title: true
  # Send a title to the player when they join the server!
  title: "&a&lWelcome {player}!"
  subtitle: "&7Welcome in ServerName Server!"

leave:
  enabled: true
  message: "&c{player} &7left!"
  otherServerMessage: "&c{player} &7left &a{server}!"

# Only available in a proxy( Velocity or Bungeecord)
# Called on server switch
# Additional placeholders: {oldServer} {newServer}
serverSwitch:
  enabled: false
  messageFrom: "&a{player} &7switched to &a{newServer}"
  messageTo: "&a{player} &7came from &a{oldServer}"

# Commands that will be executed from console when an user joins the server
# If you want to disable this just set it to []
# See the Join Commands guide for more information
commands: []

# If you enable hide feature people with the permission of hide-permission won't have a join message
enable-hide: false
hide-permission: "rocketjoin.silent"

# ---> Custom Conditions <---

conditions:
  example-vip:
    # Read the Conditions guide for more information
    type: PERMISSION
    value: "rocketjoin.vip"

    join: "&e&l» &6&lVIP &7{player} joined!"
    leave: "&e&l» &6&lVIP &7{player} left!"
    sound: true
    sound-type: "entity.experience_orb.pickup"
    fireworks: false
    fireworks-amount: 3
    commands: []

# Use \n for a new line
# Set to "disable" to disable this feature
welcome: "&8&l&m===============&e  Welcome &8&l&m===============\n
    &7Welcome {player} in Minecraft Server!\n
    Use /kit default to get your kit\n"
```

## Configuration Options Explained

### Basic Settings

**`prefix`** - The prefix shown before messages. Supports color codes.

**`update-message`** - Enable or disable update notifications when joining the server.

### Join Messages

**`join.enabled`** - Enable or disable join messages globally.

**`join.message`** - The message displayed when a player joins. Available placeholders:

* `{player}` - Player's name
* `{DisplayPlayer}` - Player's display name
* Any PlaceholderAPI placeholders (if installed)

**`join.otherServerMessage`** - Message shown on proxy servers when a player joins from another server. Additional placeholder:

* `{server}` - The server name the player joined from

**`join.enable-title`** - Enable or disable the welcome title.

**`join.title`** - The main title text shown to the player.

**`join.subtitle`** - The subtitle text shown below the title.

### Leave Messages

**`leave.enabled`** - Enable or disable leave messages globally.

**`leave.message`** - The message displayed when a player leaves.

**`leave.otherServerMessage`** - Message shown on proxy servers when a player leaves to another server.

### Server Switch Messages

<Info>
  Server switch messages are only available on Velocity or BungeeCord proxy
  servers.
</Info>

**`serverSwitch.enabled`** - Enable or disable server switch messages.

**`serverSwitch.messageFrom`** - Message shown on the server the player left from. Placeholders:

* `{oldServer}` - Server the player left
* `{newServer}` - Server the player joined

**`serverSwitch.messageTo`** - Message shown on the server the player joined.

### Join Commands

**`commands`** - List of commands executed from console when a player joins. Use `{player}` placeholder in commands. Set to `[]` to disable.

See the [Join Commands](/rocketjoin/join-commands) guide for more details.

### Hide Feature

**`enable-hide`** - Enable the hide feature. Players with the hide permission won't have join/leave messages shown.

**`hide-permission`** - Permission node for the hide feature (default: `rocketjoin.silent`).

### Custom Conditions

**`conditions`** - Define custom conditions for special join/leave messages. See the [Conditions](/rocketjoin/conditions) guide for detailed information.

Each condition can have:

* `join` - Custom join message
* `leave` - Custom leave message
* `sound` - Play a sound (true/false)
* `sound-type` - Sound type (see [Bukkit Sound enum](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html))
* `fireworks` - Spawn fireworks (true/false)
* `fireworks-amount` - Number of fireworks to spawn
* `commands` - Commands to execute on join

### Welcome Message

**`welcome`** - A welcome message sent to players when they join. Use `\n` for new lines. Set to `"disable"` to disable this feature.

## Related Guides

* [Conditions](/rocketjoin/conditions) - Learn about custom conditions
* [Join Commands](/rocketjoin/join-commands) - Configure commands on join
* [Proxy Setup](/rocketjoin/proxy) - Setup for BungeeCord/Velocity


# Getting Started
Source: https://wiki.lorenzo0111.me/rocketjoin/getting-started

Learn how to install and set up RocketJoin with all its integrations and dependencies

# Getting Started

RocketJoin is a powerful and flexible join/leave message plugin for Minecraft servers. It works without any dependencies, but its functionality can be greatly expanded with various integrations.

## Installation

RocketJoin can be installed on both Bukkit/Spigot/Paper servers and Velocity/BungeeCord proxy servers. Simply download the plugin and place it in your `plugins` folder.

<Info>
  The plugin works without any dependency, but its functionalities are limited. With its integrations, you can customize RocketJoin even more.
</Info>

## Supported Integrations

### Bukkit / Spigot / Paper

RocketJoin automatically hooks into these plugins when found:

* **[PlaceholderAPI](https://www.spigotmc.org/resources/6245/)** - Use placeholders in your join/leave messages
* **[SuperVanish](https://www.spigotmc.org/resources/1331/)** - Integration with SuperVanish for vanish support
* **[SayanVanish](https://modrinth.com/plugin/sayanvanish)** - Integration with SayanVanish for vanish support

### Velocity / BungeeCord

For proxy servers, RocketJoin supports:

* **[PAPIProxyBridge](https://modrinth.com/plugin/papiproxybridge)** - Use PlaceholderAPI placeholders from the proxy
* **[SayanVanish](https://modrinth.com/plugin/sayanvanish)** - Integration with SayanVanish for vanish support

<Info>
  The plugin automatically hooks into these plugins when found. No additional configuration is needed for basic integration.
</Info>

## Next Steps

Now that you've installed RocketJoin, check out the [Configuration](/rocketjoin/configuration) guide to customize your join and leave messages.


# Join Commands
Source: https://wiki.lorenzo0111.me/rocketjoin/join-commands

Learn how to configure commands that execute automatically when players join your server

# Join Commands

RocketJoin allows you to execute commands automatically when players join your server. This is useful for giving starter items, setting up new players, or running any server commands.

## Overview

Join commands are executed from the console when a player joins. You can use the `{player}` placeholder in commands to reference the joining player.

## Basic Configuration

Commands are configured in the main `config.yml` file under the `commands` section:

```yaml theme={null}
commands:
  - "say Welcome {player}!"
  - "give {player} bread 5"
```

### Disabling Commands

To disable join commands, simply set the commands list to empty:

```yaml theme={null}
commands: []
```

## Placeholders

### Player Placeholder

The `{player}` placeholder is replaced with the joining player's username.

**Example:**

```yaml theme={null}
commands:
  - "say Welcome {player} to the server!"
  - "give {player} diamond 1"
```

When a player named "Steve" joins, these commands will execute as:

* `say Welcome Steve to the server!`
* `give Steve diamond 1`

## Common Use Cases

### Starter Kit

Give new players a starter kit when they join:

```yaml theme={null}
commands:
  - "give {player} bread 10"
  - "give {player} wooden_sword 1"
  - "give {player} leather_helmet 1"
  - "give {player} leather_chestplate 1"
  - "give {player} leather_leggings 1"
  - "give {player} leather_boots 1"
```

### Welcome Message

Send a welcome message to all players:

```yaml theme={null}
commands:
  - "say Welcome {player} to the server!"
  - "broadcast {player} has joined for the first time!"
```

### Teleport to Spawn

Teleport players to spawn when they join:

```yaml theme={null}
commands:
  - "spawn {player}"
```

### Set Player Properties

Set various player properties:

```yaml theme={null}
commands:
  - "gamemode survival {player}"
  - "heal {player}"
  - "feed {player}"
```

## Commands in Conditions

You can also set commands for specific conditions. This allows you to execute different commands based on player permissions or other criteria.

### Example: VIP Starter Kit

```yaml theme={null}
conditions:
  vip:
    type: PERMISSION
    value: "rocketjoin.vip"
    join: "&e&lVIP &7{player} joined!"
    commands:
      - "give {player} diamond 5"
      - "give {player} iron_sword 1"
      - "give {player} golden_apple 3"
```

### Example: First Join Commands

```yaml theme={null}
conditions:
  first-join:
    type: FIRST
    join: "&a&lWelcome {player}!"
    commands:
      - "give {player} bread 10"
      - "give {player} wooden_sword 1"
      - "say Welcome {player} to the server! Check out /help!"
```

## Advanced Examples

### Conditional Commands with Multiple Actions

```yaml theme={null}
commands:
  - "say Welcome {player}!"
  - "give {player} bread 5"
  - "spawn {player}"
```

### Integration with Other Plugins

You can integrate with other plugins' commands:

```yaml theme={null}
commands:
  - "lp user {player} parent set default"
  - "essentials:kit starter {player}"
  - "towny:town new {player} MyTown"
```

<Info>
  Make sure the plugins you're integrating with support console command execution and the `{player}` placeholder format.
</Info>

## Best Practices

1. **Test commands first** - Always test commands in-game before adding them to the config to ensure they work as expected.

2. **Use appropriate permissions** - Some commands may require specific permissions. Make sure your server console has the necessary permissions.

3. **Avoid lag-inducing commands** - Be careful with commands that might cause server lag, especially if you have many players joining.

4. **Order matters** - Commands execute in the order they're listed. Place important commands first.

5. **Use condition-specific commands** - For player-specific actions, use commands in conditions rather than global commands.

## Troubleshooting

**Q: Commands aren't executing**\
A: Check that:

* The commands section is not set to `[]`
* The commands are properly formatted in YAML
* Your server console has permissions to execute the commands
* The plugin is properly loaded

**Q: Placeholders aren't working**\
A: Make sure you're using `{player}` (with curly braces) and that the player name is being properly substituted.

**Q: Commands execute but fail**\
A: Verify that:

* The command syntax is correct
* Required plugins are installed and enabled
* The server has necessary permissions

## Security Considerations

<Warning>
  Be careful with commands that modify player data or server state. Always test commands in a safe environment first.
</Warning>

* Avoid commands that could be exploited
* Don't give excessive items or permissions
* Review commands regularly for security issues

## Related Guides

* [Configuration](/rocketjoin/configuration) - General configuration guide
* [Conditions](/rocketjoin/conditions) - Learn about condition-specific commands


# Proxy Setup
Source: https://wiki.lorenzo0111.me/rocketjoin/proxy

Complete guide to setting up RocketJoin on BungeeCord or Velocity proxy servers

# Proxy Setup

RocketJoin works on both standalone Bukkit/Spigot/Paper servers and proxy servers (BungeeCord/Velocity). This guide covers everything you need to know about using RocketJoin on proxy servers.

## Overview

When using RocketJoin on a proxy server, you can:

* Show join/leave messages across all connected servers
* Display server-specific messages when players switch servers
* Use PlaceholderAPI placeholders from the proxy (with PAPIProxyBridge)

<Info>
  RocketJoin can be installed on both the proxy server and individual backend servers. This guide focuses on proxy-specific features and considerations.
</Info>

## Installation

1. Download RocketJoin for your proxy type:
   * **BungeeCord**: Use the BungeeCord version
   * **Velocity**: Use the Velocity version

2. Place the plugin in your proxy's `plugins` folder

3. Restart your proxy server

## PlaceholderAPI Integration

### Using PlaceholderAPI on Proxy

To use PlaceholderAPI placeholders from the proxy, you need to install **[PAPIProxyBridge](https://modrinth.com/plugin/papiproxybridge)**.

<Info>
  PAPIProxyBridge allows you to use PlaceholderAPI placeholders on your proxy server, bridging the gap between your backend servers and the proxy.
</Info>

**Installation:**

1. Install PAPIProxyBridge on your proxy server
2. Install PlaceholderAPI on your backend servers
3. Configure PAPIProxyBridge according to its documentation
4. RocketJoin will automatically detect and use PAPIProxyBridge if available

## Configuration

### Proxy-Specific Messages

RocketJoin supports special messages for proxy setups:

```yaml theme={null}
join:
  enabled: true
  message: "&a{player} &7joined!"
  otherServerMessage: "&a{player} &7joined &a{server}!"
```

**`otherServerMessage`** - This message is shown when a player joins from another server. The `{server}` placeholder contains the server name.

### Server Switch Messages

Server switch messages are only available on proxy servers:

```yaml theme={null}
serverSwitch:
  enabled: false
  messageFrom: "&a{player} &7switched to &a{newServer}"
  messageTo: "&a{player} &7came from &a{oldServer}"
```

**Available placeholders:**

* `{oldServer}` - The server the player left
* `{newServer}` - The server the player joined
* `{player}` - The player's name

## Common Issues and Solutions

### Double Posting Join Messages

**Problem:** Join messages are showing twice - once from the proxy and once from the backend server.

**Solution:** Disable join and leave messages on your backend servers. Only enable them on the proxy:

**Backend server config:**

```yaml theme={null}
join:
  enabled: false

leave:
  enabled: false
```

**Proxy server config:**

```yaml theme={null}
join:
  enabled: true
  message: "&a{player} &7joined!"
  otherServerMessage: "&a{player} &7joined &a{server}!"

leave:
  enabled: true
  message: "&c{player} &7left!"
  otherServerMessage: "&c{player} &7left &a{server}!"
```

### Fireworks and Sounds Don't Work

<Warning>
  Fireworks and sounds don't work on proxy servers (BungeeCord/Velocity). They only work on Bukkit/Spigot/Paper servers.
</Warning>

This is a limitation of proxy servers - they can't spawn entities or play sounds. If you need fireworks and sounds, you'll need to:

1. Enable them on your backend servers
2. Use a plugin that can handle these effects on the proxy (if available)

### Commands Not Executing

Commands in RocketJoin execute on the server where the plugin is installed. If you have RocketJoin on both proxy and backend servers:

* Proxy commands execute on the proxy
* Backend commands execute on the backend server

Make sure you're placing commands in the correct config file.

## Proxy Commands

RocketJoin provides different commands depending on where it's installed:

* **Bukkit/Spigot/Paper**: `/rocketjoin` or `/rj`
* **BungeeCord**: `/rjb`
* **Velocity**: `/rjv`

## Best Practices

### 1. Choose Your Setup

You have two main options:

**Option A: Proxy-Only Setup**

* Install RocketJoin only on the proxy
* Disable on backend servers
* All messages handled centrally
* No fireworks/sounds support

**Option B: Hybrid Setup**

* Install on both proxy and backend servers
* Use proxy for cross-server messages
* Use backend for server-specific features (fireworks, sounds)
* Requires careful configuration to avoid duplicates

### 2. Message Configuration

For proxy setups, use `otherServerMessage` to show which server players are joining from:

```yaml theme={null}
join:
  enabled: true
  message: "&a{player} &7joined!"
  otherServerMessage: "&a{player} &7joined &a{server}!"
```

### 3. Server Switch Messages

Enable server switch messages to notify players when someone moves between servers:

```yaml theme={null}
serverSwitch:
  enabled: true
  messageFrom: "&a{player} &7switched to &a{newServer}"
  messageTo: "&a{player} &7came from &a{oldServer}"
```

## Example Configurations

### Minimal Proxy Config

```yaml theme={null}
prefix: "&8&l»"
update-message: true

join:
  enabled: true
  message: "&a{player} &7joined!"
  otherServerMessage: "&a{player} &7joined &a{server}!"

leave:
  enabled: true
  message: "&c{player} &7left!"
  otherServerMessage: "&c{player} &7left &a{server}!"

serverSwitch:
  enabled: true
  messageFrom: "&a{player} &7switched to &a{newServer}"
  messageTo: "&a{player} &7came from &a{oldServer}"

commands: []
enable-hide: false
hide-permission: "rocketjoin.silent"
```

### Advanced Proxy Config with Conditions

```yaml theme={null}
prefix: "&8&l»"
update-message: true

join:
  enabled: true
  message: "&a{player} &7joined!"
  otherServerMessage: "&a{player} &7joined &a{server}!"

leave:
  enabled: true
  message: "&c{player} &7left!"
  otherServerMessage: "&c{player} &7left &a{server}!"

serverSwitch:
  enabled: true
  messageFrom: "&a{player} &7switched to &a{newServer}"
  messageTo: "&a{player} &7came from &a{oldServer}"

conditions:
  vip:
    type: PERMISSION
    value: "rocketjoin.vip"
    join: "&e&lVIP &7{player} joined &a{server}!"
    leave: "&e&lVIP &7{player} left &a{server}!"
    # Note: sound and fireworks don't work on proxy
    commands:
      - "say Welcome back, {player}!"

commands: []
enable-hide: false
hide-permission: "rocketjoin.silent"
```

## Troubleshooting

**Q: Messages aren't showing on the proxy**\
A: Make sure:

* RocketJoin is installed on the proxy server
* Messages are enabled in the config
* The proxy server has proper network connectivity

**Q: PlaceholderAPI placeholders aren't working**\
A: Install PAPIProxyBridge on your proxy server and configure it properly.

**Q: Server switch messages aren't working**\
A: Make sure `serverSwitch.enabled` is set to `true` and that players are actually switching between servers.

## Related Guides

* [Getting Started](/rocketjoin/getting-started) - Initial setup guide
* [Configuration](/rocketjoin/configuration) - Complete configuration reference
* [Conditions](/rocketjoin/conditions) - Custom conditions guide

## Need Help?

<Info>
  Still have questions? Join our [Discord server](https://to.lorenzo0111.me/discord) for support!
</Info>


# API Reference
Source: https://wiki.lorenzo0111.me/rocketplaceholders/api

Learn how to use the RocketPlaceholders API to create and manage placeholders programmatically

# API Reference

RocketPlaceholders provides a comprehensive API for developers to integrate custom placeholders into their plugins.

## Overview

The RocketPlaceholders API allows you to:

* Add placeholders programmatically
* Retrieve existing placeholders
* Integrate with other plugins
* Create dynamic placeholder systems

## Adding the Plugin as a Dependency

<CodeGroup>
  ```groovy Gradle theme={null}
  repositories {
      maven {
          url = uri('https://repo.codemc.org/repository/maven-public/')
      }
  }

  dependencies {
      compileOnly 'me.Lorenzo0111:RocketPlaceholders:VERSION'
  }
  ```

  ```xml Maven theme={null}
  <repositories>
      <repository>
          <id>codemc-repo</id>
          <url>https://repo.codemc.org/repository/maven-public/</url>
      </repository>
  </repositories>

  <dependencies>
      <dependency>
          <groupId>me.Lorenzo0111</groupId>
          <artifactId>RocketPlaceholders</artifactId>
          <version>VERSION</version>
          <scope>provided</scope>
      </dependency>
  </dependencies>
  ```

  ```txt Manual theme={null}
  Download the latest release from:
  https://github.com/Lorenzo0111/RocketPlaceholders/releases/latest

  Add it as a dependency in your project.
  ```
</CodeGroup>

<Info>
  Replace `VERSION` with the latest version. Check the [releases page](https://github.com/Lorenzo0111/RocketPlaceholders/releases/latest) for the current version.
</Info>

## Getting the API

Get the RocketPlaceholders API instance using Bukkit's ServicesManager:

```java theme={null}
RocketPlaceholdersAPI api = Bukkit.getServicesManager().load(RocketPlaceholdersAPI.class);
if (api != null) {
    this.getLogger().info("RocketPlaceholders hooked!");
} else {
    this.getLogger().severe("Unable to find RocketPlaceholdersAPI, disabling..");
    this.getServer().getPluginManager().disablePlugin(this);
}
```

<Warning>
  Always check if the API is null before using it. RocketPlaceholders might not be installed or enabled.
</Warning>

## Adding Placeholders

### Without Permission Nodes

Create a simple placeholder without permission requirements:

```java theme={null}
this.getAPI().addPlaceholder(new PlaceholderBuilder("identifier", "text"));
```

**Example:**

```java theme={null}
api.addPlaceholder(new PlaceholderBuilder("welcome", "Welcome to our server!"));
```

This creates a placeholder `%rp_welcome%` that displays "Welcome to our server!".

### With Permission Nodes

Create a placeholder that shows different text based on permissions:

```java theme={null}
this.api.addPlaceholder(
    new PlaceholderBuilder("identifier", "text")
        .createPermissionNode("permission.example", "secret text")
);
```

**Example:**

```java theme={null}
api.addPlaceholder(
    new PlaceholderBuilder("status", "Regular Player")
        .createPermissionNode("server.vip", "VIP Member")
);
```

**How it works:**

* Players without `server.vip` permission see: "Regular Player"
* Players with `server.vip` permission see: "VIP Member"

## Retrieving Placeholders

### Internal Placeholders

Get all internal placeholders (placeholders defined in config files):

```java theme={null}
this.getAPI().getInternalPlaceholders().getStorageManager().getInternalPlaceholders();
```

### External Placeholders

Get all external placeholders (placeholders added via API):

```java theme={null}
this.getAPI().getInternalPlaceholders().getStorageManager().getExternalPlaceholders().getHashMap();
```

## Important Notes

<Danger>
  Placeholders added via API won't be synchronized with MySQL. They are stored locally on each server.
</Danger>

If you're using MySQL synchronization:

* API placeholders are local to each server
* They won't sync across your network
* Consider using the configuration files for placeholders that need to sync

## API Cookbook

For more examples and advanced usage, check out the [RocketPlaceholders API Cookbook](https://github.com/RocketPluginsMC/RocketPlaceholdersAPI-Cookbook).

The cookbook includes:

* Advanced placeholder creation examples
* Integration patterns
* Best practices
* Common use cases

## Javadocs

<Info>
  For complete API documentation, see the [RocketPlaceholders Javadocs](https://rocketplaceholders.jd.rocketplugins.space/).
</Info>

The Javadocs include:

* Complete class references
* Method documentation
* Parameter descriptions
* Return type information

## Example Integration

Here's a complete example of integrating RocketPlaceholders into your plugin:

```java theme={null}
public class MyPlugin extends JavaPlugin {
    private RocketPlaceholdersAPI api;
    
    @Override
    public void onEnable() {
        // Get the API
        api = Bukkit.getServicesManager().load(RocketPlaceholdersAPI.class);
        
        if (api == null) {
            getLogger().severe("RocketPlaceholders not found! Disabling plugin.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }
        
        // Add a placeholder
        api.addPlaceholder(
            new PlaceholderBuilder("myplugin_status", "Online")
                .createPermissionNode("myplugin.admin", "Admin Mode")
        );
        
        getLogger().info("RocketPlaceholders integration enabled!");
    }
    
    @Override
    public void onDisable() {
        // Clean up if needed
    }
}
```

## Best Practices

1. **Check for API availability** - Always verify the API is available before using it

2. **Handle errors gracefully** - Wrap API calls in try-catch blocks if needed

3. **Use descriptive identifiers** - Choose clear placeholder names (e.g., `myplugin_status` instead of `status`)

4. **Document your placeholders** - Let users know what placeholders your plugin provides

5. **Consider MySQL sync** - If you need placeholders to sync across servers, use config files instead of the API

## Related Resources

* [API Cookbook](https://github.com/RocketPluginsMC/RocketPlaceholdersAPI-Cookbook) - Examples and patterns
* [Javadocs](https://rocketplaceholders.jd.rocketplugins.space/) - Complete API documentation
* [GitHub Repository](https://github.com/Lorenzo0111/RocketPlaceholders) - Source code and issues

## Support

Need help with the API? Join our [Discord server](https://to.lorenzo0111.me/discord) for developer support!


# Conditions
Source: https://wiki.lorenzo0111.me/rocketplaceholders/conditions

Learn how to create custom conditions for placeholders, including permission, money, item, group, and JavaScript conditions

# Conditions

RocketPlaceholders' conditions system allows you to create dynamic placeholders that change based on various criteria. This is the recommended way to create advanced placeholders.

## Overview

With conditions, you can create placeholders that display different text based on:

* Player permissions
* Player money/balance
* Items in inventory
* Player groups
* JavaScript expressions
* And more!

## How Conditions Work

Conditions are evaluated in order, and the first matching condition will be used. This allows you to create priority-based placeholder systems.

## Creating a Condition

Here's a basic example of how to create a custom condition:

```yaml theme={null}
placeholders:
  1:
    placeholder: "test"
    text: "This is an example" # Default text
    conditions:
      permissionExample:
        type: PERMISSION
        value: "rocketplaceholder.example"
        text: "Example condition"
```

**How it works:**

* Players **without** the permission see: "This is an example"
* Players **with** `rocketplaceholder.example` permission see: "Example condition"

## Available Condition Types

RocketPlaceholders supports the following condition types:

### Permission Condition

Check if a player has a specific permission node.

**Type:** `PERMISSION`\
**Requires:** Value (permission node)

See the [Permission Condition](/rocketplaceholders/conditions/permission) guide for details.

### Money Condition

Check if a player has a certain amount of money (requires Vault and an economy plugin).

**Type:** `MONEY`\
**Requires:** Value (numeric amount)

See the [Money Condition](/rocketplaceholders/conditions/money) guide for details.

### Item Condition

Check if a player has a specific item in their inventory.

**Type:** `ITEM`\
**Requires:** Material and optional name/lore

See the [Item Condition](/rocketplaceholders/conditions/item) guide for details.

### Group Condition

Check if a player is in a specific group (requires Vault and a permissions plugin).

**Type:** `GROUP`\
**Requires:** Value (group name)

See the [Group Condition](/rocketplaceholders/conditions/group) guide for details.

### JavaScript Condition

Use JavaScript expressions for complex logic (requires JShader).

**Type:** `JAVASCRIPT`\
**Requires:** Value (JavaScript expression)

See the [JavaScript Condition](/rocketplaceholders/conditions/javascript) guide for details.

## Priority System

Conditions are evaluated in the order they appear in the configuration. The first matching condition will be used.

**Example:**

```yaml theme={null}
conditions:
  vip:
    type: PERMISSION
    value: "server.vip"
    text: "VIP"
  premium:
    type: PERMISSION
    value: "server.premium"
    text: "Premium"
```

If a player has both `server.vip` and `server.premium` permissions, they will see "VIP" because it's listed first.

## Complete Example

Here's a comprehensive example using multiple condition types:

```yaml theme={null}
placeholders:
  1:
    placeholder: "status"
    text: "Default Player"
    conditions:
      rich:
        type: MONEY
        value: 10000
        text: "Rich Player"
      vip:
        type: PERMISSION
        value: "server.vip"
        text: "VIP Member"
      admin:
        type: PERMISSION
        value: "server.admin"
        text: "Administrator"
      staff:
        type: GROUP
        value: "staff"
        text: "Staff Member"
```

## Requirement Types Reference

You can view all available requirement types in the [RocketPlaceholders source code](https://github.com/Lorenzo0111/RocketPlaceholders/blob/master/src/main/java/me/lorenzo0111/rocketplaceholders/creator/conditions/RequirementType.java#L30-L54).

## Best Practices

1. **Order matters** - Place higher priority conditions first
2. **Use descriptive names** - Name your conditions clearly (e.g., `vip`, `admin`, `rich_player`)
3. **Combine condition types** - Mix different condition types for complex logic
4. **Test thoroughly** - Always test your conditions with different player scenarios

## Related Guides

* [Permission Condition](/rocketplaceholders/conditions/permission) - Permission-based conditions
* [Money Condition](/rocketplaceholders/conditions/money) - Money/balance conditions
* [Item Condition](/rocketplaceholders/conditions/item) - Item-based conditions
* [Group Condition](/rocketplaceholders/conditions/group) - Group-based conditions
* [JavaScript Condition](/rocketplaceholders/conditions/javascript) - JavaScript expression conditions


# Group Condition
Source: https://wiki.lorenzo0111.me/rocketplaceholders/conditions/group

Learn how to create placeholders that change based on player groups from permissions plugins

# Group Condition

The Group condition allows you to create placeholders that display different text based on a player's group from a permissions plugin.

## Overview

This condition is perfect for creating rank-based placeholders that integrate with permission systems like LuckPerms, GroupManager, or other Vault-compatible permission plugins.

<Info>
  This condition requires [Vault](https://www.spigotmc.org/resources/34315/) and a permissions plugin like [LuckPerms](https://luckperms.net).
</Info>

## Configuration

To create a group condition, set the type to `GROUP` and provide the group name as the value.

### Basic Example

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Default"
    conditions:
      groupExample:
        type: GROUP
        value: "ExampleGroup"
        text: "Example condition text"
```

**How it works:**

* Players **not in** "ExampleGroup" see: "Default"
* Players **in** "ExampleGroup" see: "Example condition text"

## Real-World Examples

### Rank-Based Placeholder

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Member"
    conditions:
      owner:
        type: GROUP
        value: "owner"
        text: "Owner"
      admin:
        type: GROUP
        value: "admin"
        text: "Administrator"
      moderator:
        type: GROUP
        value: "moderator"
        text: "Moderator"
      vip:
        type: GROUP
        value: "vip"
        text: "VIP"
```

### Staff Status

```yaml theme={null}
placeholders:
  1:
    placeholder: "status"
    text: "Player"
    conditions:
      staff:
        type: GROUP
        value: "staff"
        text: "Staff Member"
```

### Donor Tiers

```yaml theme={null}
placeholders:
  1:
    placeholder: "donor"
    text: "Not a donor"
    conditions:
      platinum:
        type: GROUP
        value: "platinum"
        text: "Platinum Donor"
      gold:
        type: GROUP
        value: "gold"
        text: "Gold Donor"
      silver:
        type: GROUP
        value: "silver"
        text: "Silver Donor"
```

## Priority System

Remember that conditions are evaluated in order. If a player is in multiple groups, the first matching condition will be used.

**Example:**

```yaml theme={null}
conditions:
  admin:
    type: GROUP
    value: "admin"
    text: "Administrator"
  moderator:
    type: GROUP
    value: "moderator"
    text: "Moderator"
```

If a player is in both "admin" and "moderator" groups, they'll see "Administrator" because it's listed first.

## Combining with Other Conditions

You can combine group conditions with permission, money, or item conditions:

```yaml theme={null}
placeholders:
  1:
    placeholder: "tier"
    text: "Basic"
    conditions:
      vip_rich:
        type: GROUP
        value: "vip"
        text: "VIP"
      rich:
        type: MONEY
        value: 10000
        text: "Wealthy"
```

## Group Name Matching

The group name must match exactly as it appears in your permissions plugin. Group names are case-sensitive.

**Example:**

* If your group is "VIP" (uppercase), use `value: "VIP"`
* If your group is "vip" (lowercase), use `value: "vip"`

## Best Practices

1. **Use consistent naming** - Follow your permissions plugin's group naming conventions

2. **Order by priority** - Place higher priority groups first in your condition list

3. **Test with your permission plugin** - Make sure group names match exactly

4. **Combine with other conditions** - Use group conditions alongside permission or money conditions for complex logic

## Troubleshooting

**Q: The condition isn't working**\
A: Make sure:

* Vault is installed and enabled
* A permissions plugin (like LuckPerms) is installed and configured
* The permissions plugin is properly connected to Vault
* The group name matches exactly (case-sensitive)
* Players are actually in the specified group

**Q: Multiple groups not working**\
A: Remember that only the first matching condition is used. If a player is in multiple groups, prioritize them in your configuration.

## Related Guides

* [Conditions Overview](/rocketplaceholders/conditions) - Learn about all condition types
* [Permission Condition](/rocketplaceholders/conditions/permission) - Permission-based conditions


# Item Condition
Source: https://wiki.lorenzo0111.me/rocketplaceholders/conditions/item

Learn how to create placeholders that change based on items in a player's inventory

# Item Condition

The Item condition allows you to create placeholders that display different text based on whether a player has a specific item in their inventory.

## Overview

This condition is perfect for creating item-based rewards, quest completion indicators, or special item holder statuses.

## Configuration

To create an item condition, set the type to `ITEM` and configure the item properties.

### Basic Example

```yaml theme={null}
placeholders:
  1:
    placeholder: "status"
    text: "No special item"
    conditions:
      itemExample:
        type: ITEM
        material: STONE
        text: "Example condition text"
```

**How it works:**

* Players **without** the item see: "No special item"
* Players **with** the item see: "Example condition text"

## Item Properties

### Material (Required)

The material of the item. You can view a list of all available materials in the [Bukkit Material enum](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html).

**Example:**

```yaml theme={null}
material: STONE
material: DIAMOND
material: GOLDEN_APPLE
```

### Name (Optional)

The display name of the item. Supports color codes if `colors` is enabled.

**Example:**

```yaml theme={null}
name: "&cExample Item"
name: "Special Sword"
```

### Lore (Optional)

The lore of the item as a string list. Supports color codes if `colors` is enabled.

**Example:**

```yaml theme={null}
lore:
  - "First line"
  - "Second line"
  - "&aColored line"
```

### Colors (Optional)

If set to `true`, color codes like `&a` are translated and displayed in color.

**Default:** `false`

**Example:**

```yaml theme={null}
colors: true
```

## Complete Example

Here's a full example with all options:

```yaml theme={null}
placeholders:
  1:
    placeholder: "badge"
    text: "No badge"
    conditions:
      itemExample:
        type: ITEM
        material: STONE
        name: "&cExample"
        lore:
          - "&aExample line"
          - "&7Second line"
        colors: true
        text: "Example condition text"
```

## Real-World Examples

### Quest Item Holder

```yaml theme={null}
placeholders:
  1:
    placeholder: "quest"
    text: "No quest item"
    conditions:
      quest_complete:
        type: ITEM
        material: EMERALD
        name: "&aQuest Completion Token"
        lore:
          - "&7You completed the quest!"
        colors: true
        text: "Quest Completed"
```

### Special Weapon Holder

```yaml theme={null}
placeholders:
  1:
    placeholder: "weapon"
    text: "No special weapon"
    conditions:
      legendary_sword:
        type: ITEM
        material: DIAMOND_SWORD
        name: "&6&lLegendary Sword"
        lore:
          - "&7A powerful weapon"
          - "&7Only for the worthy"
        colors: true
        text: "Legendary Warrior"
```

### VIP Token Holder

```yaml theme={null}
placeholders:
  1:
    placeholder: "vip_status"
    text: "Regular Player"
    conditions:
      vip_token:
        type: ITEM
        material: GOLD_INGOT
        name: "&e&lVIP Token"
        lore:
          - "&7Hold this to show VIP status"
        colors: true
        text: "VIP Token Holder"
```

## Matching Behavior

The item condition checks if the player has an item that matches:

* The specified material
* The specified name (if provided)
* The specified lore (if provided)

All provided properties must match for the condition to be true.

## Tips and Best Practices

1. **Be specific** - Use name and lore to make items unique and prevent false matches

2. **Use colors** - Enable `colors: true` to make items more visually distinct

3. **Test thoroughly** - Make sure the item matching works as expected with your specific items

4. **Combine conditions** - You can combine item conditions with permission, money, or group conditions

## Troubleshooting

**Q: The condition isn't matching**\
A: Make sure:

* The material name is correct (case-sensitive)
* If you specified a name, it matches exactly (including color codes)
* If you specified lore, all lines match exactly
* The player actually has the item in their inventory

**Q: Color codes aren't working**\
A: Make sure `colors: true` is set in your condition configuration.

## Related Guides

* [Conditions Overview](/rocketplaceholders/conditions) - Learn about all condition types
* [Permission Condition](/rocketplaceholders/conditions/permission) - Permission-based conditions


# JavaScript Condition
Source: https://wiki.lorenzo0111.me/rocketplaceholders/conditions/javascript

Learn how to use JavaScript expressions to create advanced placeholder conditions

# JavaScript Condition

The JavaScript condition allows you to create complex conditions using JavaScript expressions. This provides maximum flexibility for creating advanced placeholder logic.

## Overview

With JavaScript conditions, you can create placeholders that evaluate complex expressions, check multiple conditions, and perform calculations.

<Warning>
  The JavaScript feature requires RocketPlaceholders 1.9.1+ and the [JShader](https://git.io/Jnq1P) plugin.
</Warning>

## Available Variables

You have access to two variables in your JavaScript expressions:

* **`Player`** - Represents the [Player](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/Player.html) object
* **`Server`** - Represents the [Server](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Server.html) object

## How It Works

Your JavaScript expression must return a **boolean** value (`true` or `false`). If the expression evaluates to `true`, the condition matches and the placeholder text is displayed.

## Configuration

To create a JavaScript condition, set the type to `JAVASCRIPT` and provide a JavaScript expression as the value.

### Basic Example

```yaml theme={null}
placeholders:
  1:
    placeholder: "status"
    text: "Default"
    conditions:
      javascriptExample:
        type: JAVASCRIPT
        value: "Player.hasPermission('example.permission');"
        text: "Example condition text"
```

**How it works:**

* If the expression returns `true` (player has permission), show: "Example condition text"
* If the expression returns `false`, show: "Default"

## Real-World Examples

### Permission Check

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Member"
    conditions:
      admin:
        type: JAVASCRIPT
        value: "Player.hasPermission('server.admin');"
        text: "Administrator"
      vip:
        type: JAVASCRIPT
        value: "Player.hasPermission('server.vip');"
        text: "VIP"
```

### Multiple Conditions

```yaml theme={null}
placeholders:
  1:
    placeholder: "status"
    text: "Regular"
    conditions:
      special:
        type: JAVASCRIPT
        value: "Player.hasPermission('server.vip') && Player.getLevel() >= 50;"
        text: "VIP Level 50+"
```

### World Check

```yaml theme={null}
placeholders:
  1:
    placeholder: "location"
    text: "Unknown"
    conditions:
      nether:
        type: JAVASCRIPT
        value: "Player.getWorld().getName() === 'world_nether';"
        text: "In Nether"
      end:
        type: JAVASCRIPT
        value: "Player.getWorld().getName() === 'world_the_end';"
        text: "In End"
```

### Health Check

```yaml theme={null}
placeholders:
  1:
    placeholder: "health_status"
    text: "Healthy"
    conditions:
      critical:
        type: JAVASCRIPT
        value: "Player.getHealth() < 5;"
        text: "Critical Health"
      low:
        type: JAVASCRIPT
        value: "Player.getHealth() < 10;"
        text: "Low Health"
```

### Game Mode Check

```yaml theme={null}
placeholders:
  1:
    placeholder: "mode"
    text: "Survival"
    conditions:
      creative:
        type: JAVASCRIPT
        value: "Player.getGameMode().toString() === 'CREATIVE';"
        text: "Creative Mode"
      spectator:
        type: JAVASCRIPT
        value: "Player.getGameMode().toString() === 'SPECTATOR';"
        text: "Spectator Mode"
```

### Complex Logic

```yaml theme={null}
placeholders:
  1:
    placeholder: "tier"
    text: "Basic"
    conditions:
      elite:
        type: JAVASCRIPT
        value: "Player.hasPermission('server.vip') && Player.getLevel() >= 100 && Player.getHealth() === Player.getMaxHealth();"
        text: "Elite Player"
```

## Using JavaScript in Placeholder Text

You can also use JavaScript expressions directly in placeholder text (without conditions):

```yaml theme={null}
placeholders:
  1:  # DO NOT USE THE 0 NUMBER
    placeholder: "test"
    text: "'Hello World' === 'Hello World' ? 'YES' : 'NO'"  # This will return YES
    parsejs: true
```

<Info>
  When using `parsejs: true`, the JavaScript expression is evaluated and the result is displayed as the placeholder text.
</Info>

## JavaScript Expression Tips

1. **Return boolean values** - Conditions must return `true` or `false`

2. **Use proper syntax** - Follow JavaScript syntax rules

3. **Access Player methods** - Use `Player.methodName()` to access player methods

4. **Access Server methods** - Use `Server.methodName()` to access server methods

5. **String comparisons** - Use `===` for strict equality checks

6. **Logical operators** - Use `&&` (AND), `||` (OR), `!` (NOT)

## Common Player Methods

Here are some commonly used Player methods:

* `Player.hasPermission(String permission)` - Check permission
* `Player.getLevel()` - Get player level
* `Player.getHealth()` - Get current health
* `Player.getMaxHealth()` - Get max health
* `Player.getWorld()` - Get player's world
* `Player.getGameMode()` - Get game mode
* `Player.getName()` - Get player name

## Troubleshooting

**Q: The condition isn't working**\
A: Make sure:

* JShader is installed and enabled
* RocketPlaceholders version is 1.9.1 or higher
* Your JavaScript syntax is correct
* The expression returns a boolean value

**Q: Getting errors**\
A: Check:

* JavaScript syntax is valid
* Method names are correct (case-sensitive)
* Variables are properly referenced

## Related Guides

* [Conditions Overview](/rocketplaceholders/conditions) - Learn about all condition types
* [Custom Placeholders](/rocketplaceholders/custom-placeholders) - Basic placeholder creation


# Money Condition
Source: https://wiki.lorenzo0111.me/rocketplaceholders/conditions/money

Learn how to create placeholders that change based on player money or balance

# Money Condition

The Money condition allows you to create placeholders that display different text based on a player's balance.

## Overview

This condition is perfect for creating wealth-based placeholders, donor tiers, or economic status indicators.

<Info>
  This condition requires [Vault](https://www.spigotmc.org/resources/34315/) and an economy plugin like [EssentialsX](https://www.spigotmc.org/resources/9089/).
</Info>

## Configuration

To create a money condition, set the type to `MONEY` and provide a numeric value.

### Basic Example

```yaml theme={null}
placeholders:
  1:
    placeholder: "wealth"
    text: "Poor"
    conditions:
      moneyExample:
        type: MONEY
        value: 10
        text: "Example condition text"
```

**How it works:**

* Players with **less than** \$10 see: "Poor"
* Players with **\$10 or more** see: "Example condition text"

<Warning>
  Do not use numbers starting with `-` (negative numbers) as values.
</Warning>

## Real-World Examples

### Wealth Tiers

```yaml theme={null}
placeholders:
  1:
    placeholder: "wealth"
    text: "Poor"
    conditions:
      billionaire:
        type: MONEY
        value: 1000000
        text: "Billionaire"
      millionaire:
        type: MONEY
        value: 100000
        text: "Millionaire"
      rich:
        type: MONEY
        value: 10000
        text: "Rich"
      wealthy:
        type: MONEY
        value: 1000
        text: "Wealthy"
```

### Donor Status

```yaml theme={null}
placeholders:
  1:
    placeholder: "donor"
    text: "Not a donor"
    conditions:
      platinum:
        type: MONEY
        value: 50000
        text: "Platinum Donor"
      gold:
        type: MONEY
        value: 25000
        text: "Gold Donor"
      silver:
        type: MONEY
        value: 10000
        text: "Silver Donor"
      bronze:
        type: MONEY
        value: 5000
        text: "Bronze Donor"
```

### Economic Status

```yaml theme={null}
placeholders:
  1:
    placeholder: "status"
    text: "Struggling"
    conditions:
      thriving:
        type: MONEY
        value: 50000
        text: "Thriving"
      comfortable:
        type: MONEY
        value: 10000
        text: "Comfortable"
      stable:
        type: MONEY
        value: 1000
        text: "Stable"
```

## Priority System

Remember that conditions are evaluated in order. Place higher amounts first if you want them to take priority.

**Example:**

```yaml theme={null}
conditions:
  rich:
    type: MONEY
    value: 10000
    text: "Rich"
  wealthy:
    type: MONEY
    value: 1000
    text: "Wealthy"
```

A player with \$15,000 will see "Rich" because it's checked first and they meet the requirement.

## Combining with Other Conditions

You can combine money conditions with permission, item, or group conditions:

```yaml theme={null}
placeholders:
  1:
    placeholder: "tier"
    text: "Basic"
    conditions:
      vip_rich:
        type: PERMISSION
        value: "server.vip"
        text: "VIP"
      rich:
        type: MONEY
        value: 10000
        text: "Wealthy"
```

## Troubleshooting

**Q: The condition isn't working**\
A: Make sure:

* Vault is installed and enabled
* An economy plugin (like EssentialsX) is installed and configured
* The economy plugin is properly connected to Vault
* Players actually have the required amount of money

**Q: Negative values**\
A: Do not use negative values. The condition checks if the player has **at least** the specified amount.

## Related Guides

* [Conditions Overview](/rocketplaceholders/conditions) - Learn about all condition types
* [Permission Condition](/rocketplaceholders/conditions/permission) - Permission-based conditions


# Permission Condition
Source: https://wiki.lorenzo0111.me/rocketplaceholders/conditions/permission

Learn how to create placeholders that change based on player permissions

# Permission Condition

The Permission condition allows you to create placeholders that display different text based on player permissions.

## Overview

This is one of the most commonly used conditions, perfect for creating rank-based, VIP, or role-specific placeholders.

## Configuration

To create a permission condition, set the type to `PERMISSION` and provide the permission node as the value.

### Basic Example

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Default"
    conditions:
      permissionExample:
        type: PERMISSION
        value: "example.permission"
        text: "Example condition text"
```

**How it works:**

* Players **without** `example.permission` see: "Default"
* Players **with** `example.permission` see: "Example condition text"

## Real-World Examples

### VIP Rank Placeholder

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Member"
    conditions:
      vip:
        type: PERMISSION
        value: "server.vip"
        text: "VIP"
```

### Multiple Rank Levels

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Member"
    conditions:
      admin:
        type: PERMISSION
        value: "server.admin"
        text: "Administrator"
      moderator:
        type: PERMISSION
        value: "server.moderator"
        text: "Moderator"
      vip:
        type: PERMISSION
        value: "server.vip"
        text: "VIP"
```

### Staff Status

```yaml theme={null}
placeholders:
  1:
    placeholder: "status"
    text: "Player"
    conditions:
      staff:
        type: PERMISSION
        value: "server.staff"
        text: "Staff"
```

## Priority System

Remember that conditions are evaluated in order. If a player has multiple permissions, the first matching condition will be used.

**Example:**

```yaml theme={null}
conditions:
  vip:
    type: PERMISSION
    value: "server.vip"
    text: "VIP"
  premium:
    type: PERMISSION
    value: "server.premium"
    text: "Premium"
```

If a player has both `server.vip` and `server.premium` permissions, they'll see "VIP" because it's listed first.

## Best Practices

1. **Use clear permission nodes** - Follow a consistent naming pattern (e.g., `server.vip`, `server.admin`)

2. **Order by priority** - Place higher priority permissions first in your condition list

3. **Combine with other conditions** - You can mix permission conditions with money, item, or group conditions

## Related Guides

* [Conditions Overview](/rocketplaceholders/conditions) - Learn about all condition types
* [Custom Placeholders](/rocketplaceholders/custom-placeholders) - Basic placeholder creation


# Configuration
Source: https://wiki.lorenzo0111.me/rocketplaceholders/configuration

Complete guide to configuring RocketPlaceholders, including MySQL setup, prefix settings, and basic configuration

# Configuration

This guide covers all configuration options available in RocketPlaceholders.

## Configuration File

The main configuration file is located at `plugins/RocketPlaceholders/config.yml`.

## Basic Configuration

Here's the default configuration with explanations:

```yaml theme={null}
#
#
#    _____  _                _           _     _
#    |  __ \| |              | |         | |   | |
#    | |__) | | __ _  ___ ___| |__   ___ | | __| | ___ _ __ ___
#    |  ___/| |/ _` |/ __/ _ \ '_ \ / _ \| |/ _` |/ _ \ '__/ __|
#    | |    | | (_| | (_|  __/ | | | (_) | | (_| |  __/ |  \__ \
#    |_|    |_|\__,_|\___\___|_| |_|\___/|_|\__,_|\___/|_|  |___/
#
#
# This config has been generated with RocketPlaceholders v@version@
# RocketPlaceholders Wiki: https://docs.rocketplugins.space/rocketplaceholders

# RocketPlaceholders prefix
prefix: "&9RocketPlaceholders &8»&r"
no_permission: "&cYou do not have permission to use this command!"
debug: false

# Enable Update Message on Join. Default: true
update-message: true

mysql:
  # If this is not enabled will be used local placeholders
  enabled: false
  # The main server is the server from the placeholders are copied
  main: false
  # Database information
  ip: 0.0.0.0
  port: 3306
  username: ""
  password: ""
  database: ""

# All placeholders have been moved in the placeholders folder.
```

## Configuration Options

### Basic Settings

**`prefix`** - The prefix shown in plugin messages. Supports Minecraft color codes.

**`no_permission`** - Message shown when a player doesn't have permission to use a command.

**`debug`** - Enable debug mode for troubleshooting. Set to `true` to see detailed logs.

**`update-message`** - Enable or disable update notifications when joining the server.

### MySQL Configuration

RocketPlaceholders supports MySQL for synchronizing placeholders across multiple servers.

**`mysql.enabled`** - Enable or disable MySQL synchronization.

**`mysql.main`** - Set to `true` on your main server. The main server is where placeholders are stored and copied from.

**`mysql.ip`** - MySQL server IP address.

**`mysql.port`** - MySQL server port (default: 3306).

**`mysql.username`** - MySQL username.

**`mysql.password`** - MySQL password (leave empty if no password).

**`mysql.database`** - MySQL database name.

<Info>
  For detailed MySQL setup instructions, see the [MySQL guide](/rocketplaceholders/mysql).
</Info>

## Placeholder Storage

All custom placeholders are stored in the `placeholders` folder. Each placeholder is defined in its own YAML file.

<Info>
  The placeholders folder structure allows for better organization and easier management of multiple placeholders.
</Info>

## Example Configuration

### Basic Setup (Local Storage)

```yaml theme={null}
prefix: "&9RocketPlaceholders &8»&r"
no_permission: "&cYou do not have permission to use this command!"
debug: false
update-message: true

mysql:
  enabled: false
```

### MySQL Setup

```yaml theme={null}
prefix: "&9RocketPlaceholders &8»&r"
no_permission: "&cYou do not have permission to use this command!"
debug: false
update-message: true

mysql:
  enabled: true
  main: true  # Set to false on other servers
  ip: "localhost"
  port: 3306
  username: "root"
  password: "yourpassword"
  database: "rocketplaceholders"
```

## Related Guides

* [Custom Placeholders](/rocketplaceholders/custom-placeholders) - Learn how to create placeholders
* [MySQL Setup](/rocketplaceholders/mysql) - Detailed MySQL configuration guide
* [Conditions](/rocketplaceholders/conditions) - Add conditions to placeholders


# Custom Permissions (Deprecated)
Source: https://wiki.lorenzo0111.me/rocketplaceholders/custom-permissions

Legacy guide for the deprecated custom permissions system. Use conditions instead.

# Custom Permissions (Deprecated)

<Danger>
  This section has been deprecated. Please use [Custom Conditions](/rocketplaceholders/conditions) instead. The custom permissions system is still functional but no longer recommended for new setups.
</Danger>

## Overview

The custom permissions system allowed you to create placeholders with multiple permission levels. While still functional, the conditions system provides more flexibility and is the recommended approach.

## Creating a MultiPermission Placeholder

With RocketPlaceholders you can create a custom placeholder based on multiple permission levels.

### Basic Structure

```yaml theme={null}
placeholders:
  1:
    placeholder: "example"
    text: "This is an example"  # Default text for players without any permission
    permissions:
      1:
        permission: "example.example"
        text: "Example"
```

**How it works:**

* Players **without** `example.example` permission see: "This is an example"
* Players **with** `example.example` permission see: "Example"

### Multiple Permission Levels

You can create unlimited permission levels:

```yaml theme={null}
placeholders:
  1:
    placeholder: "example"
    text: "This is an example"
    permissions:
      1:
        permission: "example.example"
        text: "Example"
      2:
        permission: "example.2"
        text: "Example 2"
      3:
        permission: "example.3"
        text: "Example 3"
```

## Priority System

The priority is based on the order in the configuration. The first matching permission will be used.

**Example:**

```yaml theme={null}
placeholders:
  1:
    placeholder: "example"
    text: "This is an example"
    permissions:
      1:
        permission: "example.example"
        text: "Example"
      2:
        permission: "example.2"
        text: "Example 2"
```

If a player has both `example.example` and `example.2` permissions, they will see "Example" because it's listed first (higher priority).

## Creating a Public Placeholder

Public placeholders can be viewed by everyone with the same text. Simply remove the `permissions` section:

```yaml theme={null}
placeholders:
  1:
    placeholder: "example"
    text: "This is an example"
```

**Viewed text:** `This is an example` (for all players)

## Migration to Conditions

<Info>
  We strongly recommend migrating to the [Conditions](/rocketplaceholders/conditions) system, which provides more flexibility and features.
</Info>

### Old System (Deprecated)

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Default"
    permissions:
      1:
        permission: "server.vip"
        text: "VIP"
      2:
        permission: "server.admin"
        text: "Admin"
```

### New System (Recommended)

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Default"
    conditions:
      vip:
        type: PERMISSION
        value: "server.vip"
        text: "VIP"
      admin:
        type: PERMISSION
        value: "server.admin"
        text: "Admin"
```

## Why Use Conditions Instead?

The conditions system offers several advantages:

1. **More condition types** - Not just permissions, but also money, items, groups, JavaScript, and more
2. **Better organization** - Clearer structure and naming
3. **Active development** - New features are added to conditions, not permissions
4. **More flexibility** - Combine multiple condition types

## Related Guides

* [Conditions](/rocketplaceholders/conditions) - **Recommended:** Modern condition system
* [Custom Placeholders](/rocketplaceholders/custom-placeholders) - Basic placeholder creation
* [Configuration](/rocketplaceholders/configuration) - Plugin configuration


# Custom Placeholders
Source: https://wiki.lorenzo0111.me/rocketplaceholders/custom-placeholders

Learn how to create custom placeholders with RocketPlaceholders, including basic placeholders and permission-based placeholders

# Custom Placeholders

RocketPlaceholders allows you to create custom placeholders that can be used with PlaceholderAPI and MVdWPlaceholderAPI. This guide will teach you how to create your own placeholders.

## Overview

Custom placeholders are stored in the `placeholders` folder. Each placeholder is defined in its own YAML file with a unique identifier.

## Creating a Basic Placeholder

To create a custom placeholder, create a new file in the `placeholders` folder with the following structure:

```yaml theme={null}
placeholders:
  1:  # Unique identifier (CHANGE IT, DO NOT USE 0)
    placeholder: "test"  # The placeholder will be %rp_test% (PlaceholderAPI) or {rp_test} (MVdWPlaceholderAPI)
    text: "This is an example"
```

### Placeholder Format

* **PlaceholderAPI**: `%rp_<name>%` (e.g., `%rp_test%`)
* **MVdWPlaceholderAPI**: `{rp_<name>}` (e.g., `{rp_test}`)

Where `<name>` is the value you set in the `placeholder` field.

## Public Placeholders

A public placeholder is visible to everyone with the same text:

```yaml theme={null}
placeholders:
  1:
    placeholder: "welcome"
    text: "Welcome to our server!"
```

**Result:** All players will see "Welcome to our server!" when using `%rp_welcome%`.

## Permission-Based Placeholders

You can create placeholders that show different text based on permissions:

```yaml theme={null}
placeholders:
  1:
    placeholder: "test"
    text: "This is a test"  # Shown to players without permission
    permission: "example.1"  # Permission node
    text_with_permission: "this is a secret test!"  # Shown to players with permission
```

**How it works:**

* Players **without** `example.1` permission see: "This is a test"
* Players **with** `example.1` permission see: "this is a secret test!"

## Examples

### Example 1: Simple Welcome Message

```yaml theme={null}
placeholders:
  1:
    placeholder: "welcome"
    text: "Welcome to our amazing server!"
```

### Example 2: Permission-Based Secret Message

```yaml theme={null}
placeholders:
  1:
    placeholder: "secret"
    text: "You don't have access"
    permission: "server.vip"
    text_with_permission: "Welcome, VIP member!"
```

### Example 3: Multiple Placeholders

You can define multiple placeholders in the same file:

```yaml theme={null}
placeholders:
  1:
    placeholder: "welcome"
    text: "Welcome!"
  
  2:
    placeholder: "server"
    text: "Amazing Server"
  
  3:
    placeholder: "status"
    text: "Online"
    permission: "admin.status"
    text_with_permission: "Server Status: Online"
```

## Using JavaScript Expressions

You can use JavaScript expressions for placeholder text (requires JShader):

```yaml theme={null}
placeholders:
  1:
    placeholder: "test"
    text: "'Hello World' === 'Hello World' ? 'YES' : 'NO'"  # This will return YES
    parsejs: true
```

<Warning>
  The JavaScript feature requires RocketPlaceholders 1.9.1+ and JShader plugin. See the [JavaScript Condition](/rocketplaceholders/conditions/javascript) guide for more details.
</Warning>

## Placeholder Identifiers

<Warning>
  **Important:** Do not use `0` as an identifier. Always use numbers starting from 1 or higher.
</Warning>

**Good:**

```yaml theme={null}
placeholders:
  1:
    placeholder: "example"
    text: "Example"
```

**Bad:**

```yaml theme={null}
placeholders:
  0:  # DON'T USE 0!
    placeholder: "example"
    text: "Example"
```

## Best Practices

1. **Use descriptive names** - Choose placeholder names that clearly indicate their purpose (e.g., `welcome`, `server_name`, `player_count`)

2. **Organize by purpose** - Group related placeholders together or create separate files for different categories

3. **Document your placeholders** - Add comments in your YAML files to explain what each placeholder does

4. **Test thoroughly** - Always test your placeholders in-game to ensure they work as expected

5. **Use conditions for complex logic** - For more advanced logic, use [conditions](/rocketplaceholders/conditions) instead of just permissions

## Advanced: Using Conditions

For more complex placeholder logic, you can use conditions:

```yaml theme={null}
placeholders:
  1:
    placeholder: "rank"
    text: "Default"
    conditions:
      vip:
        type: PERMISSION
        value: "server.vip"
        text: "VIP"
      admin:
        type: PERMISSION
        value: "server.admin"
        text: "Admin"
```

See the [Conditions](/rocketplaceholders/conditions) guide for detailed information.

## Troubleshooting

**Q: My placeholder isn't showing up**\
A: Make sure:

* The placeholder identifier is not `0`
* The file is in the `placeholders` folder
* You've restarted the server or reloaded the plugin
* PlaceholderAPI is installed and working

**Q: Permission-based placeholder shows the same text for everyone**\
A: Check that:

* The permission node is correct
* Players actually have the permission
* The `text_with_permission` field is set

**Q: Placeholder shows as `%rp_name%` instead of the text**\
A: This usually means PlaceholderAPI isn't detecting the placeholder. Make sure:

* PlaceholderAPI is installed and enabled
* RocketPlaceholders is properly installed
* You're using the correct placeholder format

## Related Guides

* [Configuration](/rocketplaceholders/configuration) - Plugin configuration
* [Conditions](/rocketplaceholders/conditions) - Advanced placeholder conditions
* [Custom Permissions](/rocketplaceholders/custom-permissions) - Legacy permission system (deprecated)


# Getting Started
Source: https://wiki.lorenzo0111.me/rocketplaceholders/getting-started

Learn how to install and set up RocketPlaceholders, the powerful custom placeholders plugin for Minecraft servers

# Getting Started

RocketPlaceholders is a powerful plugin that allows you to create custom placeholders for your Minecraft server. These placeholders can be used with PlaceholderAPI and MVdWPlaceholderAPI.

## Installation

Follow these steps to install RocketPlaceholders:

### Step 1: Install PlaceholderAPI

RocketPlaceholders requires **[PlaceholderAPI](https://www.spigotmc.org/resources/6245/)** to function. Download and install PlaceholderAPI first.

<Info>
  PlaceholderAPI is essential for RocketPlaceholders to work. Make sure it's installed and enabled before installing RocketPlaceholders.
</Info>

### Step 2: Install RocketPlaceholders

1. Download RocketPlaceholders from the [official release page](https://github.com/Lorenzo0111/RocketPlaceholders/releases/latest)
2. Place the `.jar` file in your server's `plugins` folder
3. Restart your server

### Step 3: Install JShader (Optional)

If you plan to use the [JavaScript condition](/rocketplaceholders/conditions/javascript), you'll need to install **[JShader](https://git.io/Jnq1P)**.

<Info>
  JShader is only required if you want to use JavaScript expressions in your placeholders. For basic placeholder creation, it's not necessary.
</Info>

## Quick Start

After installation, RocketPlaceholders will create a configuration file at `plugins/RocketPlaceholders/config.yml`. You can start creating custom placeholders immediately!

### Your First Placeholder

Here's a simple example to get you started:

```yaml theme={null}
placeholders:
  1:
    placeholder: "welcome"
    text: "Welcome to our server!"
```

This creates a placeholder `%rp_welcome%` (PlaceholderAPI) or `{rp_welcome}` (MVdWPlaceholderAPI) that displays "Welcome to our server!".

## What's Next?

Now that you've installed RocketPlaceholders, check out these guides:

* [Configuration](/rocketplaceholders/configuration) - Learn how to configure the plugin
* [Custom Placeholders](/rocketplaceholders/custom-placeholders) - Create your first custom placeholder
* [Conditions](/rocketplaceholders/conditions) - Add conditions to your placeholders

## Support

Need help? Join our [Discord server](https://to.lorenzo0111.me/discord) for support!


# MySQL Setup
Source: https://wiki.lorenzo0111.me/rocketplaceholders/mysql

Learn how to synchronize placeholders across multiple servers using MySQL

# MySQL Setup

RocketPlaceholders supports MySQL for synchronizing placeholders across multiple servers. This allows you to manage placeholders centrally and have them automatically sync to all your servers.

## Overview

With MySQL synchronization, you can:

* Manage placeholders from a single server
* Automatically sync placeholders to all connected servers
* Keep placeholder data consistent across your network

## How It Works

1. **Main Server** - One server is designated as the "main" server. This server stores placeholders in the MySQL database.

2. **Other Servers** - Other servers connect to the same MySQL database and retrieve placeholders from it.

3. **Synchronization** - When placeholders are updated on the main server, they're automatically available to all other servers.

## Configuration

### Step 1: Fill Connection Information

Configure your MySQL connection settings:

```yaml theme={null}
mysql:
  # If this is not enabled will be used local placeholders
  enabled: true
  # The main server is the server from the placeholders are copied
  main: true  # Set to false on other servers
  # Database information
  ip: "localhost"  # Your MySQL server IP
  port: 3306
  username: "root"  # Your MySQL username
  password: "yourpassword"  # Your MySQL password (leave empty if none)
  database: "rocketplaceholders"  # Database name
```

### Step 2: Choose a Main Server

<Warning>
  Only one server can be the main server. Choose one server to be your main server and set `main: true` on it. Set `main: false` on all other servers.
</Warning>

**Main Server Configuration:**

```yaml theme={null}
mysql:
  enabled: true
  main: true  # This server manages placeholders
  ip: "localhost"
  port: 3306
  username: "root"
  password: "yourpassword"
  database: "rocketplaceholders"
```

**Other Servers Configuration:**

```yaml theme={null}
mysql:
  enabled: true
  main: false  # This server reads from database
  ip: "localhost"
  port: 3306
  username: "root"
  password: "yourpassword"
  database: "rocketplaceholders"
```

### Step 3: Create the Database

Create the MySQL database (if it doesn't exist):

```sql theme={null}
CREATE DATABASE rocketplaceholders;
```

RocketPlaceholders will automatically create the necessary tables when it connects.

### Step 4: (Re)Start the Server

After configuring MySQL, restart your server. RocketPlaceholders will connect to the database and sync placeholders.

## How Placeholders Work with MySQL

### Main Server

On the main server:

* Placeholders from the `placeholders` folder are copied to the database
* Any changes to placeholders are saved to the database
* The database is the source of truth

### Other Servers

On other servers (where `main: false`):

* Placeholders are loaded from the MySQL database
* Placeholders from the local `placeholders` folder are also loaded
* Database placeholders take priority

### Using Only Database Placeholders

If you want to use only database placeholders (no local placeholders), simply delete all placeholders from the local `placeholders` folder:

```yaml theme={null}
placeholders:
  # Nothing here ツ
```

## Common Questions

### What is the difference between MySQL and YML?

With MySQL, you can sync placeholders across multiple servers. With YML (local storage), placeholders are only available on the server where they're created.

### What is a Main Server?

The main server is the server that stores placeholders in the database. All other servers read placeholders from the database. Only one server can be the main server.

### Will MySQL cause lag?

No, MySQL synchronization is optimized and won't cause noticeable lag. All database operations are performed asynchronously.

### If I use MySQL, are the config's placeholders read?

Yes! If the server is not a main server, you'll have:

* Placeholders from the database (from the main server)
* Placeholders from the local config file

Database placeholders take priority over local placeholders.

### How can I delete all config placeholders to use only database placeholders?

Simply delete all placeholders from your local `placeholders` folder:

```yaml theme={null}
placeholders:
  # Empty - only database placeholders will be used
```

## Troubleshooting

**Q: Can't connect to MySQL**\
A: Check:

* MySQL server is running
* IP address and port are correct
* Username and password are correct
* Database exists
* Firewall allows connections
* MySQL user has proper permissions

**Q: Placeholders aren't syncing**\
A: Make sure:

* MySQL is enabled on all servers
* Main server is set correctly (only one server with `main: true`)
* All servers are connected to the same database
* Servers have restarted after configuration

**Q: Changes aren't appearing**\
A: Remember:

* Only make changes on the main server
* Changes on non-main servers won't sync
* Restart servers after making changes

## Best Practices

1. **Backup your database** - Regularly backup your MySQL database containing placeholders

2. **One main server** - Always have exactly one server set as main

3. **Test locally first** - Test placeholder changes on the main server before expecting them on other servers

4. **Monitor connections** - Keep an eye on MySQL connection logs to ensure all servers are connecting properly

## Related Guides

* [MySQL FAQ](/rocketplaceholders/mysql-faq) - Frequently asked questions about MySQL
* [Configuration](/rocketplaceholders/configuration) - General configuration guide
* [Custom Placeholders](/rocketplaceholders/custom-placeholders) - Creating placeholders


# MySQL FAQ
Source: https://wiki.lorenzo0111.me/rocketplaceholders/mysql-faq

Frequently asked questions about MySQL synchronization in RocketPlaceholders

# MySQL FAQ

Common questions and answers about using MySQL with RocketPlaceholders.

## General Questions

### What is the difference from MySQL and YML?

**YML (Local Storage):**

* Placeholders stored in local files
* Only available on the server where they're created
* No synchronization between servers

**MySQL:**

* Placeholders stored in a database
* Synchronized across all connected servers
* Centralized management from one main server

<Info>
  Use MySQL if you have multiple servers and want to manage placeholders centrally. Use YML for single-server setups or when you don't need synchronization.
</Info>

### What is a Main Server?

The main server is the server that stores placeholders in the MySQL database. All other servers read placeholders from the database.

<Warning>
  Only one server can be the main server. If multiple servers have `main: true`, it can cause conflicts.
</Warning>

**How it works:**

1. Main server writes placeholders to the database
2. Other servers read placeholders from the database
3. Changes on the main server automatically sync to other servers

### Will the MySQL cause lag?

No, MySQL synchronization is optimized and won't cause noticeable lag. All database operations are performed asynchronously, meaning they don't block the main server thread.

<Info>
  RocketPlaceholders uses efficient database queries and connection pooling to minimize any performance impact.
</Info>

## Configuration Questions

### If I use MySQL, are the config's placeholders read?

Yes! If the server is **not** a main server, you'll have:

* Placeholders from the MySQL database (from the main server)
* Placeholders from the local config file

**Priority:**

1. Database placeholders (from main server)
2. Local config placeholders

Database placeholders take priority over local placeholders.

### How can I delete all my config's placeholders to use only database placeholders?

Simply delete all placeholders from your local `placeholders` folder:

```yaml theme={null}
placeholders:
  # Nothing here ツ
```

This ensures only database placeholders are used.

### Can I have different placeholders on different servers?

Yes, but with limitations:

* Main server: Manages database placeholders (shared across all servers)
* Other servers: Can have local placeholders in addition to database placeholders
* Local placeholders on non-main servers won't sync to other servers

**Example Setup:**

* Main server: Has database placeholders (shared)
* Server 1: Has database placeholders + local server-specific placeholders
* Server 2: Has database placeholders + different local server-specific placeholders

## Troubleshooting

### Placeholders aren't syncing between servers

**Check:**

1. MySQL is enabled on all servers (`enabled: true`)
2. Only one server has `main: true`
3. All servers are connected to the same database
4. Database connection information is correct on all servers
5. Servers have restarted after configuration changes

### Changes on non-main server aren't appearing

**Remember:**

* Only changes on the main server sync to the database
* Changes on other servers are local only
* Make all placeholder changes on the main server

### Can't connect to MySQL

**Check:**

* MySQL server is running
* IP address and port are correct
* Username and password are correct
* Database exists
* Firewall allows connections
* MySQL user has CREATE, SELECT, INSERT, UPDATE, DELETE permissions

### Database connection errors

**Common issues:**

* Incorrect credentials
* Database doesn't exist
* MySQL server not running
* Network/firewall blocking connection
* MySQL user lacks permissions

## Best Practices

### 1. Backup Regularly

Always backup your MySQL database containing placeholders:

```bash theme={null}
mysqldump -u root -p rocketplaceholders > backup.sql
```

### 2. One Main Server

Always have exactly one server set as main. Having zero or multiple main servers can cause issues.

### 3. Test Changes

Test placeholder changes on the main server before expecting them on other servers.

### 4. Monitor Connections

Keep an eye on MySQL connection logs to ensure all servers are connecting properly.

## Related Guides

* [MySQL Setup](/rocketplaceholders/mysql) - Complete MySQL configuration guide
* [Configuration](/rocketplaceholders/configuration) - General configuration guide