Categories

categories.yml defines every collection, resource, tier, and reward. Edit it freely.

This is the file you change most. After any edit, run /collection reload.

warning

Do not change the categories-version line at the top. It controls automatic updates.

The shape of the file

categories:
  <collection-id>:
    display-name, icon, slot, description
    resources:
      <resource-id>:
        display-name, material, trigger
        locked-icon, unlocked-lore
        tiers:
          - threshold, rewards

A collection holds resources. A resource holds tiers. A tier holds a threshold and a list of rewards.

A collection

mining:
  display-name: '&#FFAA00Mining'
  icon: IRON_PICKAXE
  inline: false
  description:
    - '&7Discover and gather'
    - '&7all mining resources.'
  resources:
    ...

Setting	What it does
`display-name`	The name shown in menus, with color codes
`icon`	The item shown for this collection in the main menu
`texture`	Optional base64 head value for a custom skull icon. Needs `icon: PLAYER_HEAD`
`inline`	`false` (default): the collection is one icon on the main menu; click it to open. `true`: each resource shows directly on the main menu instead of one icon
`slot`	Optional. Pins this collection to that exact main-menu slot. Slots count from 0, so the top-left is slot 0, the first row is 0-8, the second row starts at 9, and so on. Leave it out to auto-fill
`page`	Optional. The main-menu page (1, 2, 3, ...) the pinned slot sits on. Defaults to 1
`description`	Lore lines shown under the icon
`resources`	The resources inside this collection

info

Set slot to pin a collection to an exact main-menu slot, and page to choose which page it sits on. Collections with no slot auto-fill the leftover content-slots from menus.yml, overflowing onto extra pages as needed. A Next Page button appears only when more than one page is used. Use inline: true to break a small collection like Divers apart so its resources sit on the main menu directly.

When a collection is inline: true you can pin each resource the same way: give the resource its own slot (and optional page) to place it on an exact main-menu spot. Inline resources with no slot auto-fill the leftover slots. A resource slot only does something while its collection is inline; on a normal collection the resource lives in the collection's own sub-menu, so it is ignored.

A resource

stone:
  display-name: '&7Stone'
  material: STONE
  trigger:
    type: BLOCK_BREAK
    targets: [STONE, COBBLESTONE]
    ignore-player-placed: true
  locked-icon:
    material: GRAY_DYE
    name: '&7??? &8(Locked)'
    lore:
      - '&7Break this resource'
      - '&7to discover it.'
  unlocked-lore:
    - '&7Progress: &f{current}&8/&f{next}'
    - '&#FFAA00Tier: &f{tier}&8/&f{max-tier}'
  tiers:
    - threshold: 300
      rewards:
        - 'money:500'

Setting	What it does
`display-name`	The resource name, with color codes
`material`	The item shown once discovered
`texture`	Optional base64 head value for a custom skull icon. Needs `material: PLAYER_HEAD`
`slot`	Optional. When the collection is `inline: true`, pins this resource to that exact main-menu slot (counts from 0). Ignored unless inline
`page`	Optional. The main-menu page (1, 2, 3, ...) the pinned inline resource sits on. Defaults to the collection's page
`trigger`	What counts toward this resource (see below)
`locked-icon`	The item, name, and hint shown while undiscovered
`unlocked-lore`	The lore shown once discovered, with placeholders
`tiers`	The list of thresholds and rewards

The trigger

trigger:
  type: BLOCK_BREAK
  targets: [STONE, COBBLESTONE]
  ignore-player-placed: true
  require-fully-grown: true

Field	What it does
`type`	`BLOCK_BREAK`, `ENTITY_KILL`, `FISH_CATCH`, `EXP_GAIN`, or `STAT`
`targets`	The blocks, mobs, or fish that count, by Minecraft name
`ignore-player-placed`	Skip blocks the player placed. `BLOCK_BREAK` only
`require-fully-grown`	Only count fully grown crops. `BLOCK_BREAK` only
`count-stacked`	Count every block that falls when breaking a stacked plant (sugar cane, kelp, cactus, bamboo), not just the one broken. `BLOCK_BREAK` only

BLOCK_BREAK, ENTITY_KILL, and FISH_CATCH add one progress per player action.

See Collections for trigger types and Anti-exploit for the two checks.

Stat triggers (the Divers collection)

Some things aren't a single break, kill, or catch. The EXP_GAIN and STAT trigger types track running totals instead, and power the built-in Divers collection (playtime, votes, experience, island level).

divers:
  display-name: '&dDivers'
  icon: CLOCK
  inline: false
  resources:
    playtime:
      display-name: '&bPlaytime'
      material: CLOCK
      trigger:
        type: STAT
        stat: PLAYTIME            # hours played, built-in
      # locked-icon, unlocked-lore, tiers (thresholds in hours)...
    xp:
      display-name: '&aExperience'
      material: EXPERIENCE_BOTTLE
      trigger:
        type: EXP_GAIN            # lifetime experience earned, counts from install

Field	What it does
`type: EXP_GAIN`	Adds up experience points the player earns over time (lifetime total, not their current XP). No `targets` needed.
`type: STAT`	Reads a whole number on a timer instead of per action. Needs `stat`.
`stat: PLAYTIME`	Hours played. Built in, no other plugin needed.
`stat: PLACEHOLDER`	Reads any number from a PlaceholderAPI placeholder. Needs `placeholder`.
`placeholder`	The placeholder to read, like `%VotingPlugin_Total%` or `%SuperiorSkyblock2_island_level%`. Only for `stat: PLACEHOLDER`.
`goal-placeholder`	Optional, `STAT` only. A placeholder giving the live completion target. The resource then has one tier, awarded when the tracked value reaches this goal, and the goal is re-read every poll so it adjusts itself. Used for the AdvancedHunt heads collection.

info

STAT resources refresh on a timer set by divers.poll-interval in config.yml (default 60 seconds).

Tracking another plugin's number (votes, island level, and so on) with stat: PLACEHOLDER has its own page with worked examples: Stat collections (PlaceholderAPI). For a live, self-adjusting goal, see AdvancedHunt heads.

Lore placeholders

Use these inside unlocked-lore. The plugin fills them in per player.

Placeholder	Shows
`{current}`	Current progress
`{next}`	Progress needed for the next tier
`{tier}`	Current tier number
`{max-tier}`	Highest tier number
`{next-reward-summary}`	A short summary of the next reward

Tiers and rewards

tiers:
  - threshold: 300
    rewards:
      - 'money:500'
      - 'command:broadcast {player} reached tier 1 in Stone!'
  - threshold: 1000
    rewards:
      - 'money:1500'
      - 'item:DIAMOND:3'

List tiers in order, lowest threshold first. Each tier has a threshold (progress needed) and a list of rewards. The five reward formats are covered in full on Tiers and Rewards:

Type	Example
Money	`money:500`
Item	`item:DIAMOND:3`
Command	`command:give {player} netherite_ingot 1`
Permission	`permission:zcollections.title.stonemaster`
Experience	`exp:500`

Adding your own

To add a resource, copy an existing one inside a collection, change the id, the display-name, the material, and the trigger targets, then set your tiers. To add a whole collection, copy an existing collection block, change its id, display-name, and icon, and give it resources. Run /collection reload when done.

Collections for the big picture.
Tiers and Rewards for reward details.
Anti-exploit for the placed-block and crop checks.

The shape of the file​

A collection​

A resource​

The trigger​

Stat triggers (the Divers collection)​

Lore placeholders​

Tiers and rewards​

Adding your own​

Related pages​