Skip to content
RitomasssCommunity
Reward & retention suite

NexaRewards Documentation

NexaRewards is a configurable retention platform for daily, weekly, monthly, playtime, vote, streak, referral, AFK, advent, mystery and purchasable rewards. The same claim pipeline validates availability, locks duplicate clicks, executes actions and persists the result.

Paper 1.21.xJava 21 target
SQLite / MySQLHikariCP-backed storage
10+ reward typesShared availability checks
API + EventsServicesManager registered

Installation#

Start with the local reward flow, then add vote, Discord, economy and content integrations one at a time.

Missing soft integrations do not block startup. The plugin reports unavailable hooks and keeps affected actions unavailable.
Place the jarCopy NexaRewards-x.y.z.jar into plugins/ on Paper 1.21.x.
Generate filesStart once to create config.yml, rewards.yml, pools.yml, modules.yml, integrations.yml, schedules, randoms, rarities, events, webhooks and menus.
Set license and storageSet license-key, timezone and storage provider. SQLite is the safe default for a single server.
Reload after editingUse /nexarewards reload, then test with a staff account using /nexarewards test or simulate.

First Setup#

Reward definitions are data-driven. Keep the first rollout small enough to verify claim state and action output.

Use a harmless message or item action for the first test. Add economy, commands and webhooks only after the claim state is correct.
  1. Enable the desired modules in modules.yml.
  2. Create one daily and one one-time reward.
  3. Open /rewards and verify locked, available, cooldown and claimed lore.
  4. Test reset, history and reload.
  5. Add weighted pools and scheduled actions.
  6. Enable vote/referral/AFK integrations after their source plugins are confirmed.

Minimal reward#

daily_key:
  type: DAILY
  enabled: true
  category: daily
  cooldown:
    mode: FIXED_TIME
    time: "00:00"
  actions:
    - "console:give %player% diamond 1"
    - "message:&aDaily reward claimed!"

Reward Types#

Handlers isolate availability and claim state while the common pipeline keeps lock, validation, action execution and persistence consistent.

Time & progress#

Daily, weekly, monthly, one-time, playtime, renewable playtime, vote, renewable vote and streak rewards.

Retention modules#

Referral milestones, AFK rewards, advent calendar entries and scheduled fixed-time/repeatable actions.

Choice & economy#

Pickable/mystery pools, purchasable rewards through Vault, custom handlers and fallback actions.

Actions & Weighted Pools#

Actions are defined in YAML and can be chained. Pools add weighted selection, rarity labels, broadcasts and optional nothing slots.

A claim can stop on the first failed action or continue and log the failure through action-failure-policy.

Action vocabulary#

console:, player:, op-player:, message:, broadcast:, actionbar:, bossbar:, title:, sound:, firework:, money:, item:, chance:, pool: and webhook:.

Placeholders include player, reward id/type, tag, cooldown, progress, required amount and streak. Random values from randoms.yml can be used in action text.

Pool testing#

mystery_daily:
  entries:
    common:
      rarity: common
      weight: 70
      actions:
        - "item:IRON_INGOT|8"
    rare:
      rarity: rare
      weight: 30
      actions:
        - "item:DIAMOND|1"

Run /nexarewards simulate mystery_daily 1000 to inspect distribution before exposing a pool to players.

Progress, Cooldowns & Abuse Controls#

Availability checks are evaluated before actions execute and claim state is locked per player/reward to prevent duplicate clicks.

Do not rely on a GUI alone for abuse protection. Keep cooldown, inventory, world, playtime and IP policy enabled where appropriate.

Common checks#

Enabled state, module state, permission, disabled worlds, empty inventory slots, session playtime, cooldown, one-time state, playtime/vote/streak progress.

Anti-abuse#

Optional IP claim limits, same-IP referral block, required session playtime and bypass permissions for controlled staff testing.

Player feedback#

Join-open, join notification, auto-claim, live notification, sounds, bossbars, reminders and close-after-claim are independently configurable.

Commands#

Player commands stay short; the admin command exposes deterministic tests and diagnostics.

The most useful validation loop is: edit → /nexarewards reload → open menu → test → inspect history.
/rewards · /rewardPlayer
Actions

Open menu/category, claim, available, history and personal toggle settings.

Examples

/rewards daily
/reward claim daily_key

Purpose

Browse and claim configured rewards.

/referral · /voteProgress sources
Actions

Create/apply/reset referrals; view vote information, proceed and reset vote state.

Examples

/referral create
/vote

Purpose

Feed referral and vote reward progress.

/nexarewardsAdmin
Actions

about, reload, admin, reset, resetall, test, addprogress, history, simulate, enable, disable, toggle, license.

Examples

/nexarewards test Steve daily_key
/nexarewards simulate pool 500

Purpose

Operate and verify reward definitions.

Permissions#

Player permissions cover normal use; admin and bypass nodes should stay restricted to staff.

/lp group admin permission set nexarewards.admin true

Player#

nexarewards.use, open, claim, available, history, toggle, referral.create, referral.apply and vote.use.

Admin#

nexarewards.admin, admin.reload, admin.menu, admin.reset, admin.test, admin.simulate, admin.history, admin.editor, admin.debug and admin.migrate.

Bypass#

bypass.cooldown, bypass.world, bypass.ip-limit, bypass.inventory, bypass.discord, bypass.playtime and advent.recursive.

Configuration Files#

Definitions, presentation, integrations and runtime policy stay separated for safer iteration.

config.yml

License, timezone, storage, claim behavior, playtime, join/live notifications, anti-abuse and feature policy.

rewards.yml

Reward id, type, category, cooldown, requirements and actions.

pools.yml · rarities.yml

Weighted entries, rarity presentation, lookback and mystery behavior.

modules.yml · integrations.yml

Feature toggles and soft hook settings for PlaceholderAPI, Vault, DiscordSRV, vote, WorldGuard and item providers.

events.yml · schedules.yml

Event-driven and fixed/repeatable action runners.

randoms.yml · webhooks.yml

Random placeholders and outbound webhook templates. Keep tokens outside shared support logs.

Storage#

SQLite is the default. MySQL/MariaDB settings use HikariCP pool configuration for larger networks.

Back up the database before resetting players or changing table prefixes.

Tracked state#

  • Player profile and reward states
  • Last/next claim timestamps
  • Claim count, progress and streak
  • Claim history and audit records
  • Referral codes/applications
  • Vote queue

Operational rules#

  1. Use /reward history before resetting state.
  2. Test resets on a disposable player.
  3. Keep DB credentials and webhook tokens private.
  4. Use a maintenance window for provider changes.

Developer API & Events#

NexaRewardsAPI is registered with Bukkit ServicesManager for safe cross-plugin access.

Available operations#

NexaRewardsAPI api = Bukkit.getServicesManager()
    .load(NexaRewardsAPI.class);

api.getReward("daily_key");
api.canClaim(player, "daily_key");
api.addProgress(player, "playtime_hour", 60);
api.claim(player, "daily_key");

Use null-safe lookups and treat disabled modules or unavailable integrations as normal states.

Events#

RewardClaimEvent, RewardProgressEvent, RewardResetEvent, RewardAvailableEvent, RewardPurchaseEvent, ReferralApplyEvent and VoteRewardEvent.

Claim events are the right place to cancel a claim before actions execute.

Quick Start#

Create one deterministic reward and confirm availability, claim and history.

Start with message/item; add economy and commands later.
OpenUse /rewards and inspect locked, progress, available, cooldown and claimed states.
CheckUse /reward available and trigger playtime, vote or streak source.
ClaimClaim, inspect /reward history and reconnect.

Player Claim Setup#

Make categories and progress sources clear.

Reward lore should explain why a reward is locked and what happens next.

Claim loop#

  1. Open category and select reward.
  2. Read progress lore and trigger source.
  3. Claim with inventory space.
  4. Reopen and verify history.

Mystery/streak#

  1. Trigger with disposable account.
  2. Finish reveal before closing GUI.
  3. Verify one action only.
  4. Reset and re-claim.

Reward Publishing Setup#

Build rewards in order: definition, availability, actions, history and reset.

Test every action separately; multi-action rewards are hard to diagnose.
Definition workflow rewards.yml
  1. Create unique id/category.
  2. Define availability, cooldown and one safe action.
  3. Reload and fix validation.
  4. Use /nexarewards test <player> <reward>.
External actions hooks
  1. Add Vault, Discord, vote, referral or pool one at a time.
  2. Test provider-unavailable behavior and history.
  3. Keep commands allowlisted.

Production Rollout#

Protect reward economy, history and seasonal reset.

Back up definitions and claim data before changing ids or cooldowns.

Go-live#

  • Keep duplicate protection and audit history.
  • Gate premium rewards with permissions.
  • Test economy failure, full inventory and disconnect.
  • Announce reset/migration.

Baseline#

claims: prevent-duplicate: true write-history: true actions: command-allowlist: true require-confirmation: true

Operational Reference#

Build rewards in a deterministic order: definition, availability, action execution, history and reset.

Do not test economy or command actions first. Start with a message/item reward and inspect the claim history.

Player claim loop#

  1. Open /rewards and choose a category.
  2. Read the item lore: locked, progress, available, cooldown or claimed.
  3. Claim a simple reward and confirm message, inventory and history.
  4. Use /reward available and /reward history to verify state.
  5. For playtime/vote/streak rewards, trigger progress first and wait for the availability state.
  6. For mystery rewards, finish the reveal before closing the GUI.

Admin publishing loop#

  1. Define one reward id in rewards.yml with a single safe action.
  2. Reload and open the category menu; fix validation output before adding more actions.
  3. Test with /nexarewards test <player> <reward>.
  4. Test a reset and re-claim path, then inspect history/audit.
  5. Add Vault, Discord, vote, referral or pool actions one at a time.

Safe reward definition#

welcome_bonus:
  type: ONE_TIME
  enabled: true
  category: welcome
  actions:
    - "message:&aWelcome, %player%!"
    - "item:IRON_INGOT|8"

Abuse test matrix#

Attempt double-click, full inventory, wrong world, missing permission, cooldown bypass, reconnect during claim and duplicate referral IP. Each case should end with one clear availability reason and one persisted state.

Troubleshooting#

Check the reward id, module, permission, availability reason and action log before changing code.

Include plugin version, Paper/Java version, reward id, storage provider, relevant YAML and the complete console error in support reports.

Reward does not appear#

Check enabled, category/menu mapping, module state, permission and world restrictions. Invalid definitions are reported during validation.

Claim button is locked#

Inspect cooldown, one-time state, progress requirement, empty slots, session playtime and the player-facing availability reason.

Pool feels unbalanced#

Run /nexarewards simulate <pool> <rolls>, verify weights and inspect rarity/no-repeat settings.

Money action fails#

Verify Vault and a provider are loaded. Test with a small amount and confirm the configured failure policy.

Vote/referral progress is missing#

Check the source hook, module toggle, player permission and the relevant queue/history output. Soft hooks do not fabricate progress.

Reload is unsafe#

Reload definitions during a quiet window. Storage provider, schema and license behavior should be changed with a restart.

Support#

Share reproducible context, never secret credentials.

Documentation URL: www.ritomasss.com/docs/nexarewards

Include#

  • Version, Paper build and Java version
  • Reward id, player state and command used
  • Relevant config with secrets removed
  • Console output and availability reason
  • Storage and integration status

Redact#

License keys, database passwords, Discord/webhook tokens, Redis credentials and private player information.