zMRankup

https://github.com/zmarkitos/zmrankup
Admin
zMRankup is a rank progression plugin for Minecraft Paper servers, offering multiple configurable...
Tokens:85,113
Snippets:564
Trust Score:4.3
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Admin command examples

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Example commands for the admin commands. All require the zmrankup.admin permission and work on online and offline players.

```text
/zmrankups admin set Steve ranks 5
/zmrankups admin reset Steve playtime
/zmrankups admin add Alex ranks 1
```

--------------------------------

### Configure placeholder lists with defaults and values (placeholder-list.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Defines placeholder lists with a global default, per-list defaults, and value sequences. The 'id' field is used in the placeholder, and positions start at 1.

```yaml
default: "&cN/A"   # Global fallback if a position is missing

lists:
  playtime-rewards:
    id: rewards-playtime        # The ID used in the placeholder
    default: "&cN/A"            # Fallback for this specific list
    values:
      - "&fKey &8→ &#00E40A&lCOMMON &fx1"   # Position 1
      - "&fKey &8→ &#2891FC&lVOTE &fx1"     # Position 2
      - "&fKey &8→ &#9528FC&lEPIC &fx1"     # Position 3

  color-system:
    id: color-system
    default: "&#FFFFFF"
    values:
      - "&#FB3838"   # Position 1 → used by rank with list-position: 1
      - "&#FF7817"
      - "&#FBEE45"
      - "&#31FF39"
      - "&#59D7FF"
      - "&#9B4DFF"
      - "&#FFB0E9"
```

--------------------------------

### Placeholder list format (placeholder-list.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Shows the placeholder format for placeholder lists. The placeholder uses the list's 'id' and a position starting at 1; if the position doesn't exist, the 'default' value is returned.

```text
%zmrankups_<list-id>_<position>%
```

--------------------------------

### PlaceholderAPI Conditions Requirement

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Uses a PlaceholderAPI placeholder with an expression. The 'display' field is shown in the menu. Examples include checking player level, world, and PlayerPoints.

```yaml
requirements:
  level:
    type: placeholder
    expression: "%player_level% >= 10"
    display: "&fExperience levels"

  # Check if player is in a specific world:
  nether:
    type: placeholder
    expression: "%player_world% == world_nether"
    display: "&fBe in the Nether"

  # PlayerPoints integration:
  points:
    type: placeholder
    expression: "%playerpoints_points% >= 100"
    display: "&fPlayerPoints"
```

--------------------------------

### File Structure Overview

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Shows the plugin's file layout, including config.yml, permission.yml, placeholder-list.yml, and systems/ directory. Each .yml file in systems/ becomes an independent progression system.

```text
plugins/zMRankup/
├── config.yml              ← Global settings (language, storage, auto-rankup, sounds, etc.)
├── permission.yml          ← Permission groups assignable to ranks
├── placeholder-list.yml    ← Reusable value lists for placeholders
└── systems/
    ├── ranks.yml           ← Example: general rank progression
    ├── playtime.yml        ← Example: playtime-based progression
    └── yourSystem.yml      ← Create as many as you want
```

--------------------------------

### Build with Maven

Source: https://github.com/zmarkitos/zmrankup/blob/main/README.md

Compile the plugin from source using Maven. The compiled jar will be in the target/ directory.

```bash
mvn clean package
```

--------------------------------

### Menu Settings (systems/*.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Defines the menu title, open commands, and inventory size for a system. The open_command list can contain multiple aliases, but only the first is registered as a Bukkit command when register_command is true.

```yaml
menu_title: '&8&nMy System ({page}/{max_page})&r'
open_command:
  - myranks          # Command that opens this menu
register_command: true  # Registers it as a real Bukkit command
size: 54              # Inventory size, must be a multiple of 9
```

--------------------------------

### Auto Rankup Configuration

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Automatically promotes players when they meet requirements, without them needing to click. Check interval in seconds, max promotions per cycle (0 = unlimited), and optional permission requirement.

```yaml
auto-rankup:
  enabled: false
  interval: 2          # Check every N seconds
  max-per-check: 0     # Max promotions per cycle (0 = unlimited)
  require-permission: false  # If true, player needs zmrankup.autorankup permission
```

--------------------------------

### Using Placeholder Lists in Displays

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

References entries from 'placeholder-list.yml' in the displays. The 'list-position' field on each rank determines which list entries cycle through.

```yaml
rewards:
  displays:
    - "&#FBCC23• &f%zmrankups_rewards-playtime_1%"
    - "&#FBCC23• &f%zmrankups_rewards-playtime_2%"
  commands:
    - "crate key give {player} comun 1"
```

--------------------------------

### config.yml - Global Settings

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Global configuration for the entire plugin. Sets prefix, language (EN or ES), debug mode, and storage provider (currently H2).

```yaml
settings:
  prefix: "<b><gradient:#FFDC12:#EAC800:#FFDC12>zMRankup</gradient></b> <dark_gray>|</dark_gray> "
  language: EN       # EN or ES
  debug: false       # Enable for troubleshooting
  storage: H2        # Storage provider (currently: H2)
```

--------------------------------

### Use placeholder list in language file (lang file)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Shows how to use a placeholder list in a language file. The '{position}' placeholder is replaced with the rank's 'list-position' value, which resolves to a color in the 'color-system' list.

```yaml
# lang file (EN/ES)
playtime_hours: "&fPlayed for %zmrankups_color-system_{position}%{amount} hours ⌚"
```

--------------------------------

### Rewards Configuration (Displays and Commands)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Defines rewards given on claim. 'displays' are shown in the menu lore, 'commands' are executed from console. '{player}' is replaced with the claiming player's name.

```yaml
rewards:
  displays:
    - "&#FF1616• &fStarter Kit (stone sword, bread)"
    - "&#FF1616• &f150 welcome coins"
    - "&#FF1616• &fTemporary /fly access (1 hour)"

  commands:
    - "give {player} stone_sword 1"
    - "give {player} bread 16"
    - "eco give {player} 150"
    - "lp user {player} permission settemp aircore.command.fly true 1h"
```

--------------------------------

### Sounds Configuration

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Configures sound effects for various events: rankup success, rankup fail, menu open, menu click, and page turn.

```yaml
sounds:
  enabled: true
  rankup-success: ENTITY_PLAYER_LEVELUP
  rankup-fail: ENTITY_VILLAGER_NO
  menu-open: BLOCK_CHEST_OPEN
  menu-click: UI_BUTTON_CLICK
  page-turn: ITEM_BOOK_PAGE_TURN
```

--------------------------------

### Templates Configuration (systems/*.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Defines item appearance for the locked, current, and available states. The color-system value sets the accent color used in the {color_system} placeholder. The current and available templates share the same fields as locked, but available lore should end with 'Click to claim'.

```yaml
templates:
  color-system: "&#FF1616"   # Accent color used in {color_system} placeholder

  locked:
    material: RED_STAINED_GLASS_PANE
    display_name: "&fRank → {rank_display}"
    glow: false
    lore:
      - "&#FF1616⭐ Rewards:"
      - "{rewards}"
      - ""
      - "&#FF1616✎ Requirements:"
      - "{requirements}"
      - ""
      - "&#FE4224⌚ Progress: &7({progress}%)"
      - "{progress_bar}"
      - ""
      - "&#F86767■ You need the previous rank"

  current:
    material: LIME_STAINED_GLASS_PANE
    glow: true
    # ... same fields as locked

  available:
    material: YELLOW_STAINED_GLASS_PANE
    glow: true
    # ... same fields as locked, but lore should end with "Click to claim"
```

--------------------------------

### Navigation Buttons (systems/*.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Defines navigation buttons for previous/next page, close, and info. The close button uses actions like [sound], [message], and [player_command]. The info button uses placeholders like %zmrankup_rank% and {page}/{max_page}.

```yaml
items:
  navigation:
    previous-page:
      enabled: true
      slot: 45
      material: ARROW
      display_name: "&fNavigation &8→ &#FF1616&lBACK"
      lore:
        - " &8| &fGo to the previous page."

    next-page:
      enabled: true
      slot: 53
      material: ARROW
      display_name: "&fNavigation &8→ &#FF1616&lNEXT"

    close:
      enabled: true
      slot: 49
      material: BARRIER
      display_name: "&fNavigation &8→ &#FF1616&lCLOSE"
      actions:
        - "[sound] UI_BUTTON_CLICK"
        - "[message] <gray>Closing menu..."
        - "[player_command] menu"

    info:
      enabled: true
      slot: 4
      material: BOOK
      display_name: "&fServer &8→ &#FF1616&lMY PROFILE"
      lore:
        - " &8| &fCurrent rank: %zmrankup_rank%"
        - " &8| &fNext rank: %zmrankup_next_rank%"
        - " &8| &fProgress: &a%zmrankup_progress%"
        - " &8| &fPage: &e{page}/{max_page}"
```

--------------------------------

### Integrations Configuration

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Enables integrations with Vault (required for economy-based requirements) and PlaceholderAPI (required for placeholder requirements and displays).

```yaml
integrations:
  vault:
    enabled: true       # Required for economy-based requirements
  placeholderapi:
    enabled: true       # Required for placeholder requirements and displays
```

--------------------------------

### Titles Configuration

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Displays a title to the player when they rank up. Configure title, subtitle, and fade-in/stay/fade-out durations in ticks.

```yaml
titles:
  enabled: true
  rankup-success:
    title: "<b><gradient:#FFDC12:#EAC800:#FFDC12>Progression</gradient></b>"
    subtitle: "<green>You reached {rank}"
    fade-in: 10    # ticks
    stay: 40
    fade-out: 10
```

--------------------------------

### Define permission groups with inheritance and negation (permission.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Defines permission groups with optional parent inheritance and permission negation using a '-' prefix. A higher group automatically includes all permissions from its parent, and negated permissions remove inherited ones.

```yaml
groups:
  1:
    permissions:
      - essentials.warp.mina1

  2:
    parent: 1           # Inherits all permissions from group 1
    permissions:
      - essentials.warp.mina2

  3:
    parent: 2
    permissions:
      - essentials.warp.mina3
      - -essentials.warp.mina1   # Removes an inherited permission with "-" prefix
```

--------------------------------

### Progress Bar Configuration

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Customizes the visual progress bar shown in rank menus. Configure length, filled/empty characters, and colors.

```yaml
progress-bar:
  length: 8
  filled-char: "■"
  empty-char: "□"
  filled-color: "<green>"
  empty-color: "<gray>"
```

--------------------------------

### Playtime Requirement (Hours and Minutes)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Requires a minimum playtime, specified in hours or minutes. The 'type' field selects the unit.

```yaml
requirements:
  playtime:
    type: playtime_hours
    amount: 5

  # Or in minutes:
  time_minutes:
    type: playtime_minutes
    amount: 120
```

--------------------------------

### Cooldowns Configuration

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Prevents players from spamming rankup attempts. Configure enabled flag and cooldown time in seconds.

```yaml
cooldowns:
  enabled: false
  time: 5   # seconds
```

--------------------------------

### Decoration Item (systems/*.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Fills specific slots with a decorative item, commonly glass panes for borders. The slots list supports ranges like 0-8.

```yaml
items:
  DECORATION:
    enabled: true
    material: GRAY_STAINED_GLASS_PANE
    display_name: " "
    slots:
      - 0-8       # Slots 0 through 8 (top row)
      - 44-53     # Slots 44 through 53 (bottom row)
```

--------------------------------

### Set list-position for ranks (placeholder-list.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Assigns a 'list-position' to each rank to select which value from a placeholder list is used. If you have more ranks than colors, you can cycle back to earlier positions.

```yaml
ranks:
  1:
    list-position: 1    # Requirements shown with color at position 1 (e.g. &#FB3838)
    # ...
  2:
    list-position: 2    # Requirements shown with color at position 2 (e.g. &#FF7817)
    # ...
  8:
    list-position: 1    # If you have more ranks than colors, you can cycle back
    # ...
```

--------------------------------

### Economy (Vault) Requirement

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Requires the player to have a minimum Vault balance. The 'amount' is the required balance.

```yaml
requirements:
  money:
    type: vault_balance
    amount: 1500
```

--------------------------------

### Number Formatting Configuration

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Controls how large numbers are displayed in menus. Enables short format (e.g., 1000 → 1K) and defines suffixes for thousand, million, billion, trillion, and quadrillion.

```yaml
number-format:
  short: true   # 1000 → 1K, 1000000 → 1M
  suffixes:
    thousand: "K"
    million: "M"
    billion: "B"
    trillion: "T"
    quadrillion: "Q"
```

--------------------------------

### Defining Ranks (systems/*.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Defines a rank entry with material, display_rank, permission-group, page, slot, amount, list-position, requirements, and rewards. Ranks are claimed in order; the locked template is shown for ranks requiring a previous unclaimed rank. material: DEFAULT uses the template's material.

```yaml
ranks:
  1:
    material: RED_DYE         # Item shown in the menu for this rank
    display_rank: "&#FF1616&l1"  # Display name used in {rank_display}
    permission-group: 1       # Optional: assigns a permission group on rankup
    page: 1                   # Which menu page this rank appears on
    slot: 10                  # Inventory slot (0-based)
    amount: 1                 # Item stack size (purely visual)
    list-position: 1          # Color index used in requirement lore (maps to color-system list in placeholder-list.yml)
    requirements:
      # ... see Requirements section
    rewards:
      # ... see Rewards section
```

--------------------------------

### Assign permission groups to ranks (permission.yml)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Assigns a permission group to a rank using the 'permission-group' key. When a player reaches a rank, they receive all permissions from the assigned group, including inherited ones.

```yaml
ranks:
  1:
    permission-group: 1
    # ...
  2:
    permission-group: 2
    # ...
```

--------------------------------

### Mob Kills Requirement (Any and Specific Mob)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Requires a number of mob kills. Use 'mob' to specify a particular mob type; otherwise any mob counts.

```yaml
requirements:
  mobs:
    type: mob_kills
    amount: 50

  # Specific mob:
  zombies:
    type: mob_kills
    mob: ZOMBIE
    amount: 20
```

--------------------------------

### Blocks Mined Requirement (Any and Specific Block)

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Requires a number of blocks mined. Use 'block' to specify a particular block type; otherwise any block counts.

```yaml
requirements:
  # Any block:
  blocks:
    type: blocks_mined
    amount: 100

  # Specific block:
  diamonds:
    type: blocks_mined
    block: DIAMOND_ORE
    amount: 10
```

--------------------------------

### Player Kills and Deaths Requirements

Source: https://github.com/zmarkitos/zmrankup/wiki/Home

Requires a number of player kills and a number of deaths.

```yaml
requirements:
  pvp:
    type: player_kills
    amount: 5

  deaths:
    type: deaths
    amount: 10
```
Tokens:
Raw