VanguardRanks User Guide

Welcome to the VanguardRanks user guide! This document will help you understand how to configure and use the VanguardRanks plugin for your Minecraft server.

Configuration Options
Setting Up Ranks
Requirement Types
Menu Flow System
Available Commands
Placeholders
Permissions

Configuration Options

The config.yml file contains several important configuration options:

General Settings

rank_checker: 300 - Time in seconds between automatic rank requirement checks. Set to -1 to disable.
rank_on_join: true - Whether to check a player’s rank when they join the server.

Storage Configuration


storage:
  adapter: yaml # yaml | mysql
  prefix: vanguard_ranks
  address: localhost:3306
  database: minecraft
  username: root
  password: ''

adapter - Choose between yaml or mysql storage
prefix - Table prefix for MySQL storage
Other MySQL connection details if using MySQL adapter

Discord Integration


discord:
  enabled: true
  avatar_url: 'https://minotar.net/helm/%player%/64.png'
  username: '%player%'
  webhook: 'https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz'

enabled - Enable/disable Discord integration
avatar_url - URL for the avatar image (supports placeholders)
username - Username to display in Discord messages (supports placeholders)
webhook - Discord webhook URL for sending messages

The menu section configures the GUI that players see when using /rank:


menu:
  open_on_current_rank: true
  gui:
    flow: SNAKE # SNAKE, HORIZONTAL, VERTICAL
    structure:
      - "B A B A * A B A B"
      - ". . . . . . . . ."
      - ". . . . . . . . ."
      - "B B B < X > B B B"

open_on_current_rank - Whether to open the GUI on the player’s current rank
flow - How items flow in the GUI (SNAKE, HORIZONTAL, VERTICAL)
structure - Layout of the GUI using special characters defined in the recipe section

The recipe section defines what each character in the structure represents:


  "*":
    icon: PLAYER_HEAD
    icon_amount: 1
    icon_model_data: 3
    function: PLAYER
    display_name: '&7%player%'
    lore:
        - "Current rank %rank%"
        - "..."
        - "..."
  # Fill the empty space with a material
  ".":
    icon: AIR
    function: RANK
  # You can use as a material
  "A":
    icon: BLACK_STAINED_GLASS_PANE
    function: DECORATIVE
  # You can also not define a function, default will be DECORATIVE
  "B": WHITE_STAINED_GLASS_PANE
  "X":
    icon: REDSTONE
    function: CLOSE
  # You can use as an item with model data
  "<":
    icon: RED_STAINED_GLASS_PANE
    icon_model_data: 10
    function: BACK
  ">":
    icon: LIME_STAINED_GLASS_PANE
    icon_model_data: 0
    function: FORWARD

The status section defines how ranks with different statuses appear in the GUI:


status:
  completed:
    display_name: '%rank% &7- &a&lCOMPLETED'
    icon: AIR
    icon_amount: 1
    display_lore: true
    prepend_lore:
      - " "
    append_lore:
      - " "
      - "&aYou have completed this rank!"
  current:
    # Similar configuration for current rank
  in_progress:
    # Similar configuration for in-progress rank
  locked:
    # Similar configuration for locked rank

Setting Up Ranks

Ranks are configured in the ranks.yml file. Each rank has a unique identifier and various properties:


rookie:
  prefix: "&8[&eROOKIE&8]"
  display_name: '&eRookie'
  icon: COBBLESTONE
  icon_amount: 1
  icon_model_data: 0
  lore:
    - '&eRewards'
    - ' '
    - '&7- &fAccess to %display_name% &7kit'
  commands:
    - 'lp user %player% permission set essentials.kits.%name% true'
    - 'discord: :medal: %player% has reached %display_name%!'
    - 'perm_rank.vip1;rank.vip2: eco give %player% 1000'

Rank Properties

prefix - Chat prefix for players with this rank
display_name - Formatted name for the rank
icon - Item to represent the rank in GUI (can be a regular item or custom head texture)
icon_amount - Number of items in the stack
icon_model_data - Custom model data for the item
lore - Description text shown in the GUI
commands - Commands executed when a player reaches this rank

Rank Requirements

Requirements define what a player needs to achieve to reach a rank:


explorer:
  # Basic rank properties...
  requirements:
    '%vault_eco_balance%':
      type: NUMBER
      eval: GREATER
      value: 100
      gui_message: '&7Money &a%formatter_number_shorten_{current}%&7/&e%formatter_number_shorten_{required}% &r%status%'
      deny_message: '&7You need to have more money than &c$%formatter_number_shorten_{required}%'

Each requirement has:

A placeholder that will be evaluated (e.g., %vault_eco_balance%)
type - The type of requirement (NUMBER, TEXT, BOOLEAN)
eval - How to evaluate the requirement (EQUAL, GREATER, etc.)
value - The target value
gui_message - Message shown in the GUI
deny_message - Message shown when the requirement is not met

Conditional Commands

Commands can be executed conditionally based on permissions:


commands:
  - 'eco give %player% 1000'
  - 'perm_rank.vip1,rank.vip2: eco give %player% 2000'  # Requires both permissions
  - 'perm_rank.vip1;rank.vip2: eco give %player% 1000'  # Requires either permission

Requirement Types

VanguardRanks supports three types of requirements:

NUMBER - For numerical comparisons
- Used with placeholders that return numbers (e.g., %vault_eco_balance%)
- Can be evaluated with: EQUAL, GREATER, LESSER, GREATER_EQUAL, LESSER_EQUAL, NOT_EQUAL
TEXT - For text comparisons
- Used with placeholders that return text
- Can be evaluated with: EQUAL, NOT_EQUAL
BOOLEAN - For true/false comparisons
- Used with placeholders that return true/false values
- Can be evaluated with: EQUAL, NOT_EQUAL

Evaluation Methods

The following evaluation methods are available:

EQUAL - Checks if values are equal
GREATER - Checks if the current value is greater than the required value
LESSER - Checks if the current value is less than the required value
GREATER_EQUAL - Checks if the current value is greater than or equal to the required value
LESSER_EQUAL - Checks if the current value is less than or equal to the required value
NOT_EQUAL - Checks if values are not equal

The menu flow system determines how items are arranged in the GUI when using the /rank command. VanguardRanks offers three different flow types that can be configured in the config.yml file:

Flow Types

HORIZONTAL - Items are arranged left-to-right, top-to-bottom (like reading a book)
- This is the default flow type
- Items fill the first row from left to right, then move to the next row
- Example pattern: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, …
VERTICAL - Items are arranged top-to-bottom, left-to-right (like reading a book column by column)
- Items fill the first column from top to bottom, then move to the next column
- Example pattern: 1, 4, 7, 10, 2, 5, 8, 11, 3, 6, 9, 12, …
SNAKE - Items are arranged in a snake-like pattern, connecting adjacent cells
- The system looks for connected characters in the structure
- Items follow a path that connects adjacent cells (up, right, left, down)
- Useful for creating custom paths or shapes for items

The menu structure is defined in the config.yml file using a grid of characters:


menu:
  gui:
    flow: SNAKE # SNAKE, HORIZONTAL, VERTICAL
    structure:
      - "# # # # * # # # #"
      - ". . . . . . . . ."
      - ". . . . . . . . ."
      - "# # # < X > # # #"

Each character in the structure represents a specific item or slot type:

Special characters like #, ., *, X, <, > are defined in the recipe section
Characters that are the same and adjacent to each other will be connected when using the SNAKE flow

How Flow Affects Item Positioning

The flow type affects how ranks and other items are positioned in the GUI:

For HORIZONTAL flow:
- If you use the same character (e.g., .) in multiple positions, ranks will fill these positions from left to right, top to bottom
- Example: If you have 5 ranks and 9 . characters in the first row, the ranks will fill the first 5 positions from left to right
For VERTICAL flow:
- If you use the same character in multiple positions, ranks will fill these positions from top to bottom, left to right
- Example: If you have 5 ranks and 3 . characters in each of the first 3 columns, the ranks will fill the first column completely, then start filling the second column
For SNAKE flow:
- If you use the same character in adjacent positions, ranks will follow the connected path
- This allows for creating custom layouts like circles, zigzags, or other patterns
- Example: If you create a U-shaped pattern with . characters, ranks will follow this U shape

Practical Examples

Example 1: Simple Horizontal Layout


menu:
  gui:
    flow: HORIZONTAL
    structure:
      - ". . . . . . . . ."
      - ". . . . . . . . ."
      - ". . . . . . . . ."

Ranks will fill from left to right, top to bottom.

Example 2: Vertical Layout with Border


menu:
  gui:
    flow: VERTICAL
    structure:
      - "# # # # # # # # #"
      - "# . . . . . . . #"
      - "# . . . . . . . #"
      - "# # # # # # # # #"

Ranks will fill the . positions from top to bottom, left to right, while # creates a border.

Example 3: Snake Layout with Custom Path


menu:
  gui:
    flow: SNAKE
    structure:
      - "# # # # # # # # #"
      - "# . . . . . . . #"
      - "# . # # # # # . #"
      - "# . . . . . . . #"
      - "# # # # # # # # #"

With SNAKE flow, ranks will follow the U-shaped path created by the . characters.

By understanding and utilizing these flow types, you can create custom and intuitive GUI layouts for your ranks.

Available Commands

VanguardRanks provides the following commands:

/rank - Opens the rank GUI for the player
/rank gui [player] - Opens the rank GUI for the specified player
/rank reload - Reloads the plugin configuration
/rank version - Shows the plugin version
/rank help - Displays help information
/rank save - Saves data
/rank list - Lists all available ranks
/rank players - Shows player information
/rank up [player] - Ranks up a player if they meet the requirements
/rank set <player> <rank> - Sets a player’s rank
/rank check [player] - Checks a player’s rank requirements
/rank checkall - Checks all players’ rank requirements

Placeholders

Internal Placeholders

Player Placeholders

%player% - The name of the player

Rank Placeholders

%name%, %next_name%, %previous_name% - The name of the current/next/previous rank
%prefix%, %next_prefix%, %previous_prefix% - The prefix of the current/next/previous rank
%order%, %next_order%, %previous_order% - The order of the current/next/previous rank
%rank%, %next_rank%, %previous_rank% - The display name of the current/next/previous rank
%display_name%, %next_display_name%, %previous_display_name% - The display name of the current/next/previous rank

Requirement Placeholders

%status% - Shows the status of the requirement (true/false)
%required% - The required value for the requirement
%current% - The current value for the requirement
%..{required}..% - Custom placeholders that include the required value
%..{current}..% - Custom placeholders that include the current value

PlaceholderAPI Integration

VanguardRanks provides the following placeholders for use with PlaceholderAPI:

%vanguardranks_prefix% - The prefix of the player’s current rank
%vanguardranks_next_prefix% - The prefix of the next rank
%vanguardranks_previous_prefix% - The prefix of the previous rank
%vanguardranks_display_name% - The display name of the player’s current rank
%vanguardranks_next_display_name% - The display name of the next rank
%vanguardranks_previous_display_name% - The display name of the previous rank
%vanguardranks_name% - The name of the player’s current rank
%vanguardranks_next_name% - The name of the next rank
%vanguardranks_previous_name% - The name of the previous rank
%vanguardranks_order% - The order of the player’s current rank
%vanguardranks_next_order% - The order of the next rank
%vanguardranks_previous_order% - The order of the previous rank
%vanguardranks_status% - The status of the player’s current rank

Permissions

The following permissions control access to VanguardRanks commands and features:

vanguardranks.gui - Allows the player to use the /rank and /rank gui commands
vanguardranks.gui.other - Allows the player to use the /rank gui <player> command
vanguardranks.gui.set - Allows the player to set rank on /rank gui command
vanguardranks.gui.set.other - Allows the player to set other player rank on /rank gui command
vanguardranks.reload - Allows the player to use the /rank reload command
vanguardranks.version - Allows the player to use the /rank version command
vanguardranks.help - Allows the player to use the /rank help command
vanguardranks.save - Allows the player to use the /rank save command
vanguardranks.list - Allows the player to use the /rank list command
vanguardranks.up - Allows the player to use the /rank up command
vanguardranks.up.other - Allows the player to use the /rank up command
vanguardranks.check - Allows the player to use the /rank check command
vanguardranks.checkall - Allows the player to use the /rank checkall command
vanguardranks.set - Allows the player to use the /rank set command
vanguardranks.players - Allows the player to list everybody ranks