# Home
## How to buy BattlePass?
You can purchase [BattlePass here](https://advancedplugins.net/item/BattlePass.11?ref=wiki)
## Summary
BattlePass is a plugin, enabling you to offer a practical solution to keep your players active by allowing them to gain experience and rewards for completing tasks! *PS: We now offer PlaceholderAPI support, check the quests.*
If you need something that's not on our wiki, contact us on Discord[ here.](https://advancedplugins.net/discord)
# Immersive BattlePass UI \[NEW]
Our immersive BattlePass UI designed to increase player retention and interest.
**Redesigned** Main, Rewards, Quest Overview, Daily Quests and Weekly Quests menus
* **New graphics** and UIs to create a more immersive experience
* **New Chat BattlePass Icon**
* **New progress bar** for completing quests
### **View it on our website:** [**https://advancedplugins.net/item/BattlePass-UI.110**](https://advancedplugins.net/item/BattlePass-UI.110)
### **How does this work?**
\
This uses ItemsAdder or Oraxen plugins to apply custom textures to BattlePass menus. This is as simple as just installing one of those plugins, adding this pack and custom BattlePass configuration - that's it!
Complete guide on how to install with those plugins is included within the pack files.\
\
**Full installation support is available for customers of this pack on our official AdvancedPlugins discord server, any questions or problems will be answered there.**
# Creating Quests
## Using in-game editor (easier method)
You use in-game editor you need to use command `/bpa editor`. In menu you need to choose category which you want edit. After that you can edit existing quest or create a new quest.
## By editing `.yml` files
To create or edit quest go to `plugins/BattlePass/quests` folder and open file with category which you want to edit. There you can edit quest which already exists or create a new quest by adding it to `quests` section using this template (if you don't need certain option, just remove line with it):
```yaml
10: # UNIQUE quest ID
name: "My Quest" # Name of your quest
type: "block-break" # Check "Quest Types"
variable: "iron_ore" #Check "Setting up and using Variables"
points: 5 # Number of points for completing quest
required-progress: 10 # Required progress to complete quest
exclusive: "free" # "free" if quest is for everyone or "premium" if is only for players with premium pass
special-progress: [] # Check "Special Cases Progress"
complete-commands: # Commands executed after completing quest
- "give %player% coal 1" # It will give 1 coal to player for completing this quest :)
whitelisted-world: [] # Worlds where player can complete quest (or empty when all worlds are allowed)
blacklisted-worlds: [] # Worlds where player can't complete quest
whitelisted-regions: [] # WorldGuard regions where player can complete quest (or empty when all regions are allowed)
blacklisted-regions: [] # WorldGuard regions where player can't complete quest
item: # Icon configuration
material: "diamond" # https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html
name: "&6Week X &7| &eMy Quest" # Name of item
lore: # Item description
- "&6Break 10 iron ores"
- "&e%total_progress%&7/&e%required_progress%"
item-flags: [] # https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html
enchants: # List of enchantments
- "PROTECTION:4"
customModelData: 0 # Custom Model Data of your item (for resource packs)
amount: 1 # Item amount
nbt: "" # Custom NBT text used like in /give command. Example: "diamond[unbreakable={}]" will add Unbreakable modification to this item
```
### Icon placeholders
```
%info% - Information about current step
%step% - Current step
%steps% - Number of steps in this quest
%total_progress% - Progress (number)
%required_progress% - Required progress (number)
%percentage_progress% - Progress (percent)
%progress_bar% - Progress (bar)
```
# Multi-Step quests
Learn how to create multiple step quests!
```yaml
10: # Multiple step quest
name: 'Week 1 - Advanced Miner'
steps:
1:
type: block-break
variable: coal_ore
required-progress: 10
points: 0
info:
- "&7Mine &e10 coal ores"
2:
type: block-break
variable: iron_ore
required-progress: 10
points: 5
info:
- "&7Mine &e10 iron ores"
3:
type: block-break
variable: diamond_ore
required-progress: 10
points: 25
info:
- "&7Mine &e10 diamond ores"
item:
material: golden_pickaxe:0
name: '&eAdvanced Miner &7(&e%step%&7/&6%steps%&7)'
lore:
- '&7Mine various ores'
- '%info%'
- ''
- '&7Progress &e%total_progress%&7/&e%required_progress%'
```
This quest has 3 steps:
* Mine 10 coal ores (no rewards)
* Mine 10 iron ores (gives 5 points)
* Mine 10 diamond ores (gives 25 points)
After completing all 3 steps, the quest will complete.
### How to create a quest with multiple steps
As in the example, create a section `steps` and add quest parameters to each step section as desired.
### Info parameter
Each step can contain a list of information which you can use inside the quest icon (`%info%`).
### Icon placeholders related to steps system
* `%step%` - current step
* `%steps%` - number of steps
* `%info%` - information from step `info` parameter
### Global quest parameters
Some values like type, required-progress, whitelist, blacklist etc. can be used globally by adding them to the quest section instead of the step section.
Example:
```yaml
yamlCopy10: # Multiple step quest
name: 'Week 1 - Advanced Miner'
required-progress: 10
points: 5
steps:
1:
type: block-break
variable: coal_ore
info:
- "&7Mine &e10 coal ores"
2:
type: block-break
variable: iron_ore
info:
- "&7Mine &e10 iron ores"
3:
type: block-break
variable: diamond_ore
info:
- "&7Mine &e10 diamond ores"
```
In this example, all steps require 10 progress and give 5 points (per step).
# Special Cases Progress
Define special cases progress multipliers, e.g. when you want a `kill-mob` action to give a different number of progress points depending on the mob, or mining ores.
Better, newer approach for special progress -> [Check](https://wiki.advancedplugins.net/actions/setting-up-and-using-variables)
### Syntax:
```yaml
special-progress:
- "VARIABLE MULTIPLIER"
```
### Example:
```yaml
type: block-break
variable: coal_ore OR diamond_ore
special-progress:
- "diamond_ore 5" # Diamond ore will give 5 progress instead of 1
```
# Daily Quests Difficulty
Sometimes we want to make that daily quests have same difficulty every day. I.e. we want to make that daily quests always have 1 hard quest, 3 medium quests and 5 easy quests. It's now possible by using 'difficulty' property.
## Setting quest's difficulty
Firstly, we need to set difficulty of all daily quests. You can set it using in-game editor or by adding `difficulty` property to every daily quest in server files.
Difficulty name can be anything. It can be just one word, or it can be entire sentence with colors, but you need to make sure that quests with same difficulty has same difficulty property.
**Example configuration**
```yaml
6: # Quest id
type: throw-projectile
variable: none
name: 'Throw and Throw'
required-progress: 200
points: 10
difficulty: medium # <-- Difficulty
item:
material: snowball
name: '&eBaller'
lore:
- '&7To complete this quest, you must'
- '&7throw/shoot 200 projectiles.'
- '&7Difficulty: &e%difficulty%' # <-- You can also show difficulty in quest's description using %difficulty% placeholder
- ''
- '&7(&a%percentage_progress%&7)'
```
## Enabling & Setting strategy
Now we need to configure strategy in `settings.yml`
```yaml
daily-quest-difficulty:
enabled: true
strategy:
easy: 5
medium: 3
hard: 1
```
As I said, name od difficulty can be anything, so you can even add `&4&lImpossible Quest` difficulty (sentence with colors)
{% hint style="info" %}
You can also configure i.e. 1 hard quest and 4 random quests by setting:
```yaml
# ...
strategy:
# ...
hard: 1
```
and
```yaml
current-season:
# ...
daily-quest-amount: 5
# ...
```
{% endhint %}
```yaml
# ...
strategy:
# ...
"&4&lImpossible Quest": 1
```
## Configuring permanent quests
Sometimes, we want to make that one or more daily quests are always available. You can achieve that by adding ids of these quests to `permanent-daily-quest-ids`. Example:
```yaml
permanent-daily-quest-ids: ['1', '3', '5']
```
In this example, daily quests with id 1,3 and 5 will be always available
# Events
You can also create event quests. They have own menu and are available in certain period of time. You can create them same as new week (in `quests` folder), but you need to change name to template `event--quests.yml` (Replace `` with id of your event i.e. `easter`). Also, you need to add this configuration:
```yaml
category:
start: # Start date
date: "14/04/2025"
time: "10:00"
end: # End date
date: "27/04/2025"
time: "22:00"
name: "Easter Quests" # Name
required-permission: "" # Required permission
required-completed: [] # Required completed categories i.e. ["week-1, event-xyz"] requires to complete 1st week & XYZ event before accessing this event
show-without-permission: true # Show event even if player doesn't have required permission
see-quests-when-not-active: true # Allow players to see event quests when event isn't active
item: # Event display icon
material: "EGG"
amount: 1
name: "&6Easter Quests"
lore:
- "&eSpecial quests for easter event"
- "&e14/04/2025 - 27/04/2025"
- ""
- "%status%" # %status% will be replaced with messages from lang file: Starts in ..., Ends in..., Ended, No permission
```
# Boosters
Boosters system allows adding booster for certain amount of time by admin. Booster can boost progress, points or rewards. It has a lot of possible areas where it affects.
### **Bungee Compatibility**
To make boosters work in bungee network, just set `bungee-fix: true` in `settings.yml`. Boosters will refresh every `auto-save-interval` from `settings.yml`
### New Commands
```
/bpa boosters add
