Skip to content
RitomasssCommunity
BattlePass & progression suite

NexaQuests Documentation

NexaQuests combines daily, weekly and monthly quests with seasonal BattlePass progression, milestones, QuestBoard entries, physical quest scrolls, boosters, conditional rewards and a developer API.

Paper 1.21.xJava 21 target
SQLite / MySQLHikariCP storage
Quest + PassRetention modules
API + HooksCustom actions/conditions

Installation#

NexaQuests is a standalone Paper plugin with optional hooks into Vault, PlaceholderAPI, WorldGuard, Citizens, item providers, voting and other Nexa plugins.

License validation runs at startup. Keep the key out of shared configs and support screenshots.
Install and generatePlace the jar in plugins/, start once and let the plugin create config, database, menu, quest, pass, milestone, scroll, reward, hook and placeholder resources.
Configure the seasonSet battlepass.default-pass, define the active season and choose free/premium reward tracks.
Validate contentUse the admin validation/editor workflow before exposing new quest or reward files to players.
Verify runtimeCheck /nexaquests hooks, open /quests, accept a test quest and confirm progress persists after reconnect.

First Setup#

Start with one quest, one reward and one BattlePass tier. Expand content after progress and claim persistence are confirmed.

The configured default requires acceptance for most quests. Players should accept before action progress is expected.
  1. Choose daily, weekly and monthly amounts/reset times.
  2. Create a simple block-break or playtime quest.
  3. Add a command/item reward and test claim.
  4. Configure a season with free and premium tiers.
  5. Add milestones, boosters and scrolls.
  6. Enable optional region, NPC and item-provider hooks.

Core policy#

modules:
  battlepass: true
  daily-quests: true
  weekly-quests: true
  monthly-quests: true
  quest-board: true
  milestones: true
  scroll-quests: true

progress:
  require-accept-by-default: true
  save-debounce-ticks: 40

Quest System#

Quest definitions can be single, multi-objective or multi-step. Assignments are persistent and can reset on daily, weekly or monthly schedules.

Secret quests remain hidden until accepted or completed; prerequisites and completion timers are checked before claim.

Progress actions#

Block break/place, entity kill, player kill, fishing, crafting, command execution, playtime and external hook actions.

Assignment modes#

Daily, weekly and monthly pools can scale amounts by permission. Reset day/time and BattlePass XP injection are configurable.

Player flow#

Open menu, browse list, accept, track, complete and claim. Favorite quests and tracked progress are persisted.

BattlePass#

Seasons define tiers, formulas, free rewards, premium rewards, claim-all behavior and optional infinite-tier compatibility.

Grant premium access with a permission or the admin command; do not assume a player can claim premium rewards because the tier is visible.

Progression#

  • BattlePass XP from quests and configured actions.
  • Formula-based XP requirements.
  • Free and premium tracks.
  • Tier-up event and claim-all.
  • Start/end/reset/archive hooks.
  • Permission prefix such as nexapass.premium..

Player commands#

/pass
/pass rewards
/pass quests
/pass premium
/pass leaderboard

Use season-aware placeholders for tier, XP, required XP, season, premium state and points.

Rewards & Conditions#

Rewards can execute commands, money, items, points, XP, permissions, messages, titles, sounds, broadcasts, pools and custom handlers.

Conditions#

Permission, world, biome, held item, local time, PlaceholderAPI value, economy balance and optional WorldGuard region conditions.

conditions:
  permission: "nexaquests.vip"
  world: "survival"
  economy:
    minimum: 100

Reward behavior#

Formula amounts, random pools, conditional rewards, Vault with command fallback, temporary permissions and API-registered handlers can be combined while preserving claim events.

Quest Scrolls#

Physical scrolls are UUID-backed items with their own progress, rarity, expiration and trade rules.

Scroll progress lore is updated on the item. Duplicate UUID cleanup and expiration checks protect against copied or stale items.

Identity#

UUID-backed scroll definitions prevent a copied item from becoming a second valid assignment.

Rarity#

Rarity can scale progress/reward, add glow, apply soulbound/trade enforcement and support reroll behavior.

Use#

Right-click to claim or interact with the scroll; configure expiration and duplicate cleanup in the scroll resources.

Commands#

Player commands focus on discovery and progress; admin commands provide safe testing and content management.

/questsPlayer
Actions

daily, weekly, monthly, accept, track, untrack, claim, profile, board, shop, buy, leaderboard, milestones.

Examples

/quests daily
/quests track miner_1

Purpose

Browse, progress and claim quests.

/passBattlePass
Actions

Open pass, rewards, quests, premium and leaderboard.

Examples

/pass rewards
/pass premium

Purpose

Inspect seasonal progression.

/nexaquestsAdmin
Actions

reload, hooks, progress, complete, editor, pass, season, booster, scroll, give and reset.

Examples

/nexaquests progress Steve miner_1 5
/nexaquests editor

Purpose

Operate, validate and test content.

Configuration Files#

Keep content definitions separate from module and provider policy.

config.yml

License, language, modules, progress save behavior, assignment amounts, BattlePass policy, boosters and integrations.

database.yml

SQLite/MySQL connection and table behavior.

quests/ · battlepasses/

Quest pools, seasons, tiers, formulas and reward tracks.

milestones/ · scrolls/ · rewards/

Milestone definitions, physical scrolls and reusable reward actions.

hooks.yml

External action bridge and integration detection.

placeholders.yml · messages.yml

Expansion values, formatting and player-facing text.

Storage#

The schema stores players, assignments, progress, BattlePass state, milestones, scrolls, boosters and QuestBoard state.

Player data loads on join, saves on quit and flushes during shutdown. Keep a database backup before resets or migrations.

Data tables#

players, quest_progress, quest_assignments, battlepass_progress, milestone_progress, scroll_quests, active_boosters and quest_board_state.

Persistence rules#

Progress is debounced to reduce writes, while completion/claim state is persisted before success is presented to the player. Avoid editing the database manually while the server is running.

Integrations#

All listed integrations are soft hooks; they can enrich conditions, menus, items and progression without becoming hard startup dependencies.

Conditions & economy#

PlaceholderAPI, Vault and WorldGuard conditions.

NPC & items#

Citizens NPC menu access; ItemsAdder, Oraxen and Nexo custom menu/reward items.

Network ecosystem#

NuVotifier/VotingPlugin and optional NexaCombat, NexaSpawners, NexaTeams and NexaChat hooks.

Developer API & Events#

Use the provider/service to register custom action and condition handlers and to read player progression.

Extension points#

Register custom objectives/actions, reward handlers and condition handlers. External plugins can report progress with the configured /nexaquests hook <action> <player> [target] [amount] bridge.

Events#

QuestProgressEvent, QuestCompleteEvent, RewardClaimEvent and BattlePassTierUpEvent. Check cancellation and player state before running external effects.

Quick Start#

Publish one daily quest and validate progression.

A menu item is not proof that objective, condition and reward are valid.
OpenUse /quests daily and inspect category, lore, reset and states.
TrackAccept and run /quests track <quest>; verify HUD/placeholder progress.
CompleteTrigger objective, claim reward and verify /quests profile after reconnect.

Player Progression Setup#

Make daily, weekly, monthly and BattlePass progress understandable.

Use detail menu and history for missing-progress reports.

Quest loop#

  1. Open a category and read objective/condition/reward lore.
  2. Track and trigger one quest.
  3. Claim and confirm reset/cooldown.

Pass loop#

  1. Earn XP from tested source.
  2. Open /pass rewards.
  3. Test free/premium, claim-all and end date.
  4. Reconnect and verify tiers.

Quest & Season Publishing#

Author stable ids, validated actions and predictable reset behavior.

Give every new quest a new id; changing a live id can orphan progress.
Quest authoring YAML
  1. Define objective, conditions, amount, actions and metadata.
  2. Reload and fix validation.
  3. Use /nexaquests progress/complete on disposable player.
  4. Publish and verify reset.
BattlePass release free/premium
  1. Test XP, thresholds and end date.
  2. Verify permissions independently.
  3. Test claim-all and rollover.

Production Rollout#

Run quests as durable progression with safe rewards and resets.

Back up quest, reward, season and progress data before id/schedule changes.

Go-live#

  • Test reward actions individually.
  • Set reset timezone explicitly.
  • Verify HUD/PlaceholderAPI/hooks.
  • Monitor history and duplicates.

Baseline#

progress: save-on-change: true prevent-duplicate-claims: true seasons: require-explicit-end-date: true reset-timezone: "UTC"

Operational Reference#

A full content-publishing and player-progression loop for quests and BattlePass seasons.

Validate quest, reward and season files before assigning them. A visible menu item is not proof that its objective or reward is valid.

Player progression loop#

  1. Open /quests daily, select a quest and accept it.
  2. Use /quests track <quest> to show progress in the configured HUD.
  3. Trigger the objective in its allowed world/region/condition context.
  4. Open the quest detail menu, confirm completion and claim the reward.
  5. Open /pass rewards to claim the tier unlocked by BattlePass XP.
  6. Check /quests profile, milestones and leaderboard state after reconnect.

Admin content workflow#

  1. Duplicate an existing quest/reward as a template instead of editing a live id.
  2. Validate objectives, conditions, action amounts and menu references.
  3. Test with /nexaquests progress and complete on a disposable player.
  4. Publish the quest to daily/weekly/monthly pools, then verify reset timing.
  5. For a season, test free and premium tiers, claim-all and end-date behavior.

Assignment baseline#

daily-quests:
  amount:
    default: 3
    vip: 5
  require-accept: true
  reset-time: "00:00"
battlepass:
  claim-all-enabled: true

External progress#

For a third-party action, use the registered custom action or /nexaquests hook <action> <player> [target] [amount]. Confirm the hook name and amount in debug output before promising integration behavior.

Troubleshooting#

Validate content first, then inspect hooks, assignment timing and persistence.

Include plugin version, Paper/Java version, quest/season id, relevant YAML, hook status and the complete stack trace in reports.

Quest progress does not move#

Confirm the player accepted the quest, the objective action matches the listener, the module is enabled and the player is not excluded by a condition.

Daily list is empty#

Check reset time/timezone, permission-scaled amount, pool definitions and assignment storage. Reload after content edits.

BattlePass reward is locked#

Check tier XP, season dates, free/premium track and the premium permission prefix.

Custom item renders as stone#

Verify the ItemsAdder/Oraxen/Nexo hook and item id. Vanilla material fallback is intentional when a provider is unavailable.

Scroll was duplicated#

Review UUID cleanup, expiration and trade/soulbound rules. Do not clone scrolls through external NBT tools.

Reload changes are missing#

Use /nexaquests reload and inspect validation output. Database/provider and license changes require a restart.