Rank Guide

This guide details the rank system configuration based on the core implementation.

Rank Status Types

The rank system defines four distinct status types that determine a rank’s state for a player:

• IN_PROGRESS: Player is currently working towards this rank
• COMPLETED: Player has achieved this rank
• LOCKED: Rank is not yet available (previous ranks not completed)
• CURRENT: Player’s active rank

Requirements System

Requirement Types

The system supports three fundamental requirement types:

• TEXT: Text-based requirements (e.g., permissions, names)
• NUMBER: Numerical requirements (e.g., money, playtime, kills)
• BOOLEAN: True/false requirements (e.g., has permission)

Requirement Evaluation Methods

Requirements can be evaluated using these comparison methods:

• EQUAL: Value must match exactly
• GREATER: Value must be greater than requirement
• LESSER: Value must be less than requirement
• GREATER_EQUAL: Value must be greater than or equal to requirement
• LESSER_EQUAL: Value must be less than or equal to requirement
• NOT_EQUAL: Value must not match requirement

Rank Configuration Example

explorer:
  # Basic rank properties
  prefix: "&8[&aEXPLORER&8]"
  display_name: '&aExplorer'
  icon: DIAMOND_PICKAXE
  icon_amount: 1
  icon_model_data: 0
  
  # Rank requirements
  requirements:
    # Money requirement example
    '%vault_eco_balance%':
      type: NUMBER
      eval: GREATER_EQUAL
      value: 1000
      gui_message: '&7Balance: &a$%current%&7/&e$%required% &r%status%'
      deny_message: '&cYou need $%required% to rank up!'
    
    # Permission requirement example
    '%luckperms_has_permission_warps%':
      type: TEXT
      eval: EQUAL
      value: 'yes'
      gui_message: '&7Warp Access: %status%'
      deny_message: '&cYou need warp access!'
    
    # Playtime requirement example
    '%statistic_play_one_minute%':
      type: NUMBER
      eval: GREATER_EQUAL
      value: 3600
      gui_message: '&7Playtime: &a%current%s&7/&e%required%s &r%status%'
      deny_message: '&cPlay for %required% seconds!'
  
  # Rank rewards
  lore:
    - '&eRequirements:'
    - ' '
    - '&7- %requirement_0%'
    - '&7- %requirement_1%'
    - '&7- %requirement_2%'
    - ' '
    - '&eRewards:'
    - '&7- &f$2000'
    - '&7- &fExplorer Kit'
  
  # Reward commands
  commands:
    - 'eco give %player% 2000'
    - 'lp user %player% permission set essentials.kits.explorer true'
    - 'discord: :star: %player% reached Explorer rank!'
    # Conditional commands
    - 'perm_rank.vip: eco give %player% 1000' # Requires permission
    - 'perm_rank.vip1,rank.vip2: eco give %player% 2000' # Requires both permissions
    - 'perm_rank.vip1;rank.vip2: eco give %player% 1000' # Requires either permission

Conditional Commands

Commands can be made conditional using these formats:

• perm_permission.node: command - Requires specific permission
• perm_perm1,perm2: command - Requires all permissions (AND)
• perm_perm1;perm2: command - Requires any permission (OR)

Best Practices

1. Requirement Configuration

   • Use appropriate requirement types (TEXT, NUMBER, BOOLEAN)
   • Choose suitable evaluation methods
   • Provide clear gui_message and deny_message

2. Rank Progression

   • Balance requirements across ranks
   • Ensure logical progression difficulty
   • Use varied requirement types

3. Command Execution

   • Test conditional commands thoroughly
   • Use proper permission nodes
   • Implement appropriate rewards

4. PlaceholderAPI Integration

   • Utilize placeholders for dynamic values
   • Test placeholder resolution
   • Keep messages informative

Troubleshooting

• Verify requirement types match placeholder output types
• Check permission nodes exist and are correctly formatted
• Ensure conditional commands follow proper syntax
• Test placeholder resolution in messages
• Validate reward commands execute as expected