How to Make a Category
A category groups quests together so players can track progress across a set of related goals. When a player completes every quest in a category, the category fires its own rewards and triggers a libreforge event.
Quick start
Open the
/categories/folder and create a new file, e.g.easy.yml. The file name is the category ID.Set the
nameand optionally configureeffectsto run on completion.Add
category: <id>to any quest you want grouped under this category.Optionally set
gui.item, and setcategories-gui.enabledto true inconfig.ymlto give/questsa category menu.Run
/ecoquests reload.
Category file structure
# The ID of the category is the name of the .yml file.
# _example.yml is not loaded.
name: "Easy"
# Options for the category GUI (categories-gui in config.yml)
gui:
enabled: true # Show this category in the category GUI
item: lime_dye # GUI icon, read via the Item Lookup System
lore: # Lines added to the top of the icon lore
- "&7Quests to get you started."
# Optional. Pins this category to an exact slot instead of auto-placing it.
# Must fall within categories-gui.category-area in config.yml.
# position:
# row: 2
# column: 2
# Effects run when the player completes this category (all quests in it done).
# This fires every time the category is completed, including after a reset cycle.
# Read https://plugins.auxilor.io/effects/configuring-an-effect
effects: []
Assigning a quest to a category
Add one optional line to any quest config:
name: "Traveller"
category: easy # The category ID (matches the file name without .yml)
# ... rest of quest config
Omit the line entirely for quests that belong to no category. If the category ID does not match a loaded category file, a warning is printed to the console and the quest behaves normally.
Category GUI
Set categories-gui.enabled to true in config.yml to turn /quests into a menu of categories. Clicking a category opens a quests GUI with only that category's quests, and its back button returns to the category menu. Players can also open one category directly with /quests <category>, whether or not the category menu is enabled.
Quests with no category are listed behind the categories-gui.uncategorised button, which only shows when such quests exist. With no categories to show, /quests opens the list of every quest.
Each category's icon uses its gui.item, with gui.lore lines above the shared categories-gui.category-icon lore. Categories with gui.enabled: false are left out of the menu. The quests GUI for a category uses the gui settings from config.yml, with gui.category-title as its title.
Placeholders
Swap <category> for the category ID.
| Placeholder | Description |
|---|---|
%ecoquests_category_<category>_name% | The display name of the category |
%ecoquests_category_<category>_complete% | Whether the player has completed all quests in the category (true / false) |
%ecoquests_category_<category>_quests_completed% | How many quests in the category the player has completed |
%ecoquests_category_<category>_quests_remaining% | How many quests in the category the player has not yet completed |
_complete is computed live on every call, so it reflects the current state after any quest resets.
Libreforge integration
Categories expose a trigger, a condition, and a filter for use anywhere libreforge effects are supported.
Trigger: complete_category
Fires when a player completes a category (all quests in the category become completed).
triggers:
- id: complete_category
Fires every time the category completes, so if a resettable quest resets and the player completes it again, the trigger fires again.
Condition: has_completed_category
Passes when the player has completed all quests in the given category.
conditions:
- id: has_completed_category
args:
category: easy
Filter: category
Filters any quest or task trigger event by the category of the quest involved. Passes automatically when the triggering event is not a quest event.
filters:
- id: category
args:
category:
- easy
- medium
Use this to run effects only when a player completes (or starts) a quest belonging to a specific category, without listing every quest individually.
Where to go next
Build quests for your category: How to make a quest covers the
categoryfield and the full quest config.Track progress: PlaceholderAPI lists all category placeholders.