### 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→ �E40A&lCOMMON &fx1" # Position 1 - "&fKey &8→ ୋFC&lVOTE &fx1" # Position 2 - "&fKey &8→ ┸FC&lEPIC &fx1" # Position 3 color-system: id: color-system default: "&#FFFFFF" values: - "&#FB3838" # Position 1 → used by rank with list-position: 1 - "&#FF7817" - "&#FBEE45" - "FF39" - ";D7FF" - " B4DFF" - "&#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__% ``` -------------------------------- ### 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: "zMRankup | " 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] 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: "Progression" subtitle: "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: "" empty-color: "" ``` -------------------------------- ### 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 ```