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`
`itemsadder`	Optional ItemsAdder item id (`namespace:item`) to show instead of the plain `icon`. See Icons
`custom-model-data`	Optional custom model data number applied to the icon. See Icons
`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
`subcategories`	Optional discoverable groups of resources inside this collection. See Subcategories

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`
`itemsadder`	Optional ItemsAdder item id to show instead of the plain `material` once discovered. See Icons
`custom-model-data`	Optional custom model data number applied to the icon. See Icons
`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. Takes the same `material`, `texture`, `itemsadder` and `custom-model-data` keys as the unlocked icon
`unlocked-lore`	The lore shown once discovered, with placeholders
`island-membership`	Optional. A duration such as `48h`, `2d`, or `90m`. The resource's rewards can only be claimed once the player has been on the same island for that long. See Island membership lock
`tiers`	The list of thresholds and rewards

Icons

Every icon in the file (a collection's icon, a subcategory's icon, a resource's material, and the material inside any locked-icon block) accepts the same optional extras next to it:

Key	What it does
`texture`	Base64 head value, applied when the icon is `PLAYER_HEAD`
`itemsadder`	An ItemsAdder item id such as `fishing_expansion:mackerel`. The menu shows that item, custom model included, so players see the real modded fish, ore, or crop. Needs the ItemsAdder plugin. Without it, or if the id is not known to ItemsAdder, the plain material is shown instead and a warning is logged once
`custom-model-data`	A number set as the icon's custom model data, for resource-pack models that do not go through ItemsAdder

The plain icon / material stays required: it is the fallback, and it is what non-ItemsAdder servers see.

mackerel:
  display-name: '&bMackerel'
  material: COD
  itemsadder: 'fishing_expansion:mackerel'
  locked-icon:
    material: GRAY_DYE
    name: '&7??? &8(Locked)'
  # trigger, unlocked-lore, tiers...

The itemsadder key on an icon only changes how the icon looks. To make catching or breaking that item count, the resource still needs itemsadder-ids in its trigger, see Modded content.

Subcategories

A subcategory is a discoverable group of resources inside a collection, for example Fishing, then Pirate Dimension Fish, then each fish, then that fish's tiers. It is a way to organise custom content without giving it its own top-level collection.

fishing:
  display-name: '&#5599FFFishing'
  icon: FISHING_ROD
  resources:
    cod:
      # a normal resource, shown directly in the Fishing menu
  subcategories:
    pirate_fish:
      display-name: '&#55DDFFPirate Dimension Fish'
      icon: COD
      itemsadder: 'fishing_expansion:mackerel'
      description:
        - '&7Discovered: &f{discovered}&8/&f{total}'
        - '&7Click to open.'
      locked-icon:
        material: GRAY_DYE
        name: '&7??? &8(Locked)'
        lore:
          - '&7Catch a fish from the'
          - '&7pirate dimension to unlock.'
      resources:
        mackerel:
          display-name: '&bMackerel'
          material: COD
          itemsadder: 'fishing_expansion:mackerel'
          trigger:
            type: FISH_CATCH
            itemsadder-ids: ['fishing_expansion:mackerel']
          locked-icon:
            material: GRAY_DYE
            name: '&7??? &8(Locked)'
          unlocked-lore:
            - '&7Progress: &f{current}&8/&f{next}'
          tiers:
            - threshold: 10
              rewards: ['money:500']
        trout:
          # same shape, id fishing_expansion:trout

Setting	What it does
`display-name`	The group name, with color codes. Translatable under `subcategory-names.<collection>.<group>` in the language files
`icon`, `texture`, `itemsadder`, `custom-model-data`	The icon shown once the group is unlocked. See Icons
`description`	Lore under the unlocked icon. Supports `{discovered}` (resources found so far) and `{total}` (resources in the group)
`locked-icon`	The `material`, `name`, and `lore` shown while locked. Takes the same icon extras
`slot`, `page`	Optional. Only used when the collection is `inline: true`: pins the group's icon on the main menu like an inline resource
`resources`	The resources inside the group, written exactly like any other resource

How it behaves for each player:

Locked. Until the player has discovered any resource in the group, the group shows its locked-icon in the collection menu and clicking it does nothing.
Unlocking. Discovering any one resource in the group (catching one mackerel) unlocks the group for that player. Its icon switches to the normal one and clicking it opens the group's own menu. Nothing needs to be stored for the group itself: it is unlocked whenever one of its resources is discovered, so it survives restarts along with the resource progress.
Inside the group. Undiscovered resources are still locked icons; discovered ones show their real icon and open their tier menu, exactly like resources in a collection.
Separate progress. Each resource keeps its own discovery, counter, tiers, and rewards. The group is only a way to organise them, not a shared counter. Catching a mackerel unlocks the group and the mackerel entry; trout, sardine, and the rest stay locked until caught.

Groups are listed before the collection's plain resources in the collection menu. Resource ids must be unique across the whole collection, including inside groups: a resource id used both directly and inside a group is skipped with a console warning, because progress is stored per collection and resource id. Placeholders such as %zcollections_fishing_mackerel_progress% work for resources inside a group the same way as for any other resource.

The same structure works in every collection: Farming with Pirate Dimension Crops, Mining with Pirate Dimension Ores, Hunting with Pirate Dimension Mobs (using mythicmobs-types in the trigger instead of itemsadder-ids).

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
`mythicmobs-types`	MythicMobs internal mob type ids that count, instead of `targets`. `ENTITY_KILL` only
`itemsadder-ids`	ItemsAdder namespaced ids that count, instead of `targets`. `BLOCK_BREAK` and `FISH_CATCH` 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. See Modded content for mythicmobs-types and itemsadder-ids.

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.

Island membership lock

An island-level collection has a weak spot: a player could join a high-level island, claim its tiers, leave, join another one, and claim again. island-membership closes that.

      island_level:
        display-name: '&6Island Level'
        material: GRASS_BLOCK
        island-membership: 48h
        trigger:
          type: STAT
          stat: PLACEHOLDER
          placeholder: '%superior_island_level_int%'

With this line, the resource stays locked until the player has been on the same island for 48 hours in a row: it is not discovered, and none of its tiers can be claimed. The wait accepts d, h, m, and s, so 2d, 1d12h, or 90m all work; a bare number counts as hours.

Leaving for another island, or having no island, restarts the clock from zero. Joining a high-level island for a moment unlocks nothing. The island is checked every 5 seconds.
Every new island needs its own full wait. Until it is served the resource shows as undiscovered, even for a player who claimed tiers from it on an earlier island.
Once the wait is over, the resource is discovered and every tier the island's level reaches is unlocked for good. Unlocked tiers stay claimable even if the player leaves the island later, so they can be claimed whenever the player likes: while any unlocked tier is still unclaimed, the resource stays discovered on any island. A later island only adds tiers it reaches after its own full wait.
Tiers already claimed stay claimed. They are stored for the player, not the island, so the same tier is never paid twice no matter how many islands the player goes through.
When the resource is discovered only because of unclaimed unlocked tiers, a tier the current island reaches beyond them shows as Island lock in the resource menu with the time left, and clicking it explains the wait. In auto reward mode, unlocked tiers are paid as soon as the wait is over.

Which island the player is on comes from island.placeholder in config.yml (SuperiorSkyblock2 by default) and needs PlaceholderAPI. The built-in island_level resource ships with island-membership: 48h; remove the line to drop the wait.

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. To group custom content inside an existing collection, add a subcategory. 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​

Icons​

Subcategories​

The trigger​

Stat triggers (the Divers collection)​

Island membership lock​

Lore placeholders​

Tiers and rewards​

Adding your own​

Related pages​