Skip to main content

Stat collections (PlaceholderAPI)

Some things you want to reward are not a block break, kill, or catch. They are a running number another plugin already keeps, like total votes, island level, or a job level. A STAT resource reads that number on a timer and turns it into a collection with tiers and rewards.

How it works​

A STAT resource with stat: PLACEHOLDER reads one PlaceholderAPI placeholder that resolves to a whole number. The plugin polls it on a timer and treats the result as the player's progress, so your tier thresholds are just numbers in that same unit (votes, levels, and so on).

This needs:

  • PlaceholderAPI installed.
  • The other plugin, plus its PlaceholderAPI expansion (install with /papi ecloud download <name> then /papi reload for most).

Only stat: PLAYTIME is built in and needs no other plugin. Everything else goes through a placeholder.

Hovering the built-in Playtime resource in the Divers menu, showing hours played and the next reward

Find the right placeholder​

Test the placeholder in game before wiring it up. It must return a plain number:

/papi parse me %VotingPlugin_Total%

If that prints a number, it works. If it prints the placeholder back unchanged, the expansion is missing or the name is wrong.

Example: votes (VotingPlugin)​

  voting:
    display-name: '&eVoting'
    icon: PAPER
    description:
      - '&7Vote for the server to rank up.'
    resources:
      votes:
        display-name: '&eVotes'
        material: PAPER
        trigger:
          type: STAT
          stat: PLACEHOLDER
          placeholder: '%VotingPlugin_Total%'
        unlocked-lore:
          - '&7Votes: &f{current}&8/&f{next}'
          - '&7Tier: &f{tier}&8/&f{max-tier}'
        tiers:
          - threshold: 25
            rewards:
              - 'money:5000'
          - threshold: 100
            rewards:
              - 'money:25000'

Hovering the Votes resource in the Divers menu, reading the live vote total from a placeholder

Example: island level (SuperiorSkyblock2)​

  island:
    display-name: '&aIsland'
    icon: GRASS_BLOCK
    description:
      - '&7Grow your island to rank up.'
    resources:
      level:
        display-name: '&aIsland Level'
        material: GRASS_BLOCK
        # Rewards can only be claimed after 48 hours on the same island.
        island-membership: 48h
        trigger:
          type: STAT
          stat: PLACEHOLDER
          placeholder: '%SuperiorSkyblock2_island_level%'
        unlocked-lore:
          - '&7Level: &f{current}&8/&f{next}'
          - '&7Tier: &f{tier}&8/&f{max-tier}'
        tiers:
          - threshold: 10
            rewards:
              - 'money:10000'
          - threshold: 50
            rewards:
              - 'money:50000'

Hovering the Island Level resource in the Divers menu, reading the island level from a placeholder

island-membership is optional. It keeps a player from hopping between high-level islands to claim the same tiers again: the resource stays locked until the player has been on the same island for that long, and changing island restarts the clock. After the wait, the tiers that island reaches stay unlocked for good. Claimed tiers are remembered per player, so nothing is ever paid twice. Which island the player is on is read from island.placeholder in config.yml (%superior_island_uuid% by default). See Island membership lock.

Generic template​

Any plugin that exposes a numeric placeholder works the same way. Swap the placeholder and set thresholds in its unit:

        trigger:
          type: STAT
          stat: PLACEHOLDER
          placeholder: '%<plugin>_<number>%'

Common ones to try: %Jobs_total_level%, %mcmmo_power_level%, %statistic_mob_kills%. Whatever returns a number with /papi parse me can drive a collection.

A live, self-adjusting goal​

If the target should be read from a placeholder too (instead of fixed thresholds), add goal-placeholder. The resource then has one tier that completes when the tracked value reaches that live goal, re-read every poll. The AdvancedHunt heads page is a full walkthrough of that setup.

Notes​

info

STAT resources refresh on a timer set by divers.poll-interval in config.yml (default 60 seconds), so progress and rewards update on the next poll, not the instant the other plugin's number changes.

  • A placeholder that is missing or returns a non-number is treated as 0, so nothing breaks; the resource just never advances until it resolves.
  • These are absolute values, not per-action counts. The plugin stores the latest reading, it does not add up changes.
  • AdvancedHunt heads for the live goal-placeholder setup.
  • Categories for the full categories.yml format.
  • Placeholders for the %zcollections_*% placeholders this plugin provides for scoreboards and tab lists.