Overview

AstralFarmPass is a seasonal battle-pass / quest plugin for AstralRealms. Each month a new season opens with a fresh set of randomly generated daily and weekly quests; players complete them through normal gameplay to earn points, and spend those points unlocking free and premium reward tiers from an in-game menu.

Core concepts

Concept	Summary
Season	A one-month period (`SeasonEntity`, calendar month boundaries). Auto-created and auto-rotated by the master node; holds every quest generated for that month.
Quest blueprint	A template defined in `quests/*.yml` — display item, a `QuestGoal` (the gameplay trigger), and per-category `min`/`max` requirement ranges.
Quest instance	A concrete quest rolled from a blueprint for a given season: a random target within the blueprint's range, an `unlocksAt`/`expiresAt` window, and per-player progress.
Category	`daily` or `weekly` (defined in `categories.yml`) — controls how often quests regenerate, whether old ones expire, and how many points completing one awards.
Points	Per-player, per-season currency (`FarmPassData.points()`) earned by completing quests; spent claiming reward tiers.
Reward tier	An entry in `rewards.yml` gated behind a `required-points` threshold, with separate `default` (free) and `premium` action lists.

Architecture at a glance

plugins/AstralFarmPass/
├── config.yml           ← single `master` boolean flag (no bundled default resource; `false` unless set)
├── database.properties  ← JDBC connection settings
├── messages.yml         ← localised strings
├── categories.yml       ← daily / weekly category + regeneration rules
├── rewards.yml          ← point-gated reward tiers (default + premium)
├── quests/              ← QuestBlueprint definitions (e.g. simple.yml)
└── menus/
    └── main.yml          ← the `farmpass-main` menu (quest grid, opened by /pass)

How the pieces fit together

quests/*.yml (loaded as a whole folder by BlueprintService) ships the quest blueprints, and categories.yml (CategoriesConfiguration) defines the daily/weekly categories those blueprints roll into — together they're the raw material for quest generation. See Quests & Goals and Seasons & Categories.
The master node (config.yml → master: true) runs SeasonRotationService, which polls every 5 minutes, creates a new SeasonEntity for the current month when none is active or the current one has expired, and populates it by calling QuestGenerationService.generateRandomQuest(...) once per day for each daily slot and once per week for each weekly slot — picking a random unused blueprint per category and rolling a random target inside its min/max range. See Seasons & Categories.
As players play, GoalListener (plus ArrowPiercingListener, which synthesizes a custom ArrowKillMultipleEntitiesEvent for multi-kill piercing-arrow shots) routes Bukkit/Astral events into QuestService#tryProgress, which advances any matching, unlocked, unexpired quest instance and, on completion, credits the quest's category rewarded-points to the player's FarmPassData. See Quests & Goals.
rewards.yml (RewardsConfiguration) defines the point-gated reward tiers; players claim them through the /pass menu, which fires the claim-farmpass-reward action. See Rewards.

Requirements

Dependency	Required	Notes
Paper 1.21+	Yes	`api-version: '1.21'`
AstralCore	Yes	Plugin bootstrap (`AstralPaperPlugin`), configuration, menus, actions, placeholders.
AstralVote	Yes	Fires `PlayerVoteEvent`, consumed by the vote quest goal.
AstralScrolls	Yes	Fires `ScrollCompletedEvent`, consumed by the scroll-completion quest goal.
AstralTower-Bridge	Yes	Fires `TowerFinishedEvent`, consumed by the tower-completion quest goal.
AstralSync	Runtime	Not declared in `plugin.yml` `depend`, but required at runtime: `FarmPassData` (quests, points, claimed rewards) is persisted and cross-server synced entirely through `SyncAPI`/`SnapshotAdapter`.
MariaDB	Yes	`DatabaseService`; seasons and quests tables (`schema.sql`).
Redis	Yes	`CacheService`.
RabbitMQ	Yes	`MessagingService`; carries the `farmpass` season-rotation packet channel.

Registered surfaces

Everything the plugin registers in AstralFarmPass#onEnable:

Surface	Name	Notes
Action	`claim-farmpass-reward`	Claims a free or premium reward tier for the executing player.
Command	`/pass` (alias `/farmpass`)	Opens the main menu; `info`, `reset`, `reload`, `reroll` subcommands.
Command	`/farmpass points`	`add`/`take`/`set` subcommands for admin point management.
Placeholder namespace	`%farmpass_...%`	`rewards`, `quests`, `points` sub-keys.
SyncAPI adapter	`farmpass:data`	`FarmPassSnapshotAdapter`, backs the `FarmPassData` player snapshot.
Listener	`GoalListener`	Routes 19 Bukkit/Astral events into quest-goal progress (plus a quit-cleanup handler).
Listener	`ArrowPiercingListener`	Tracks piercing-arrow multi-kills and raises `ArrowKillMultipleEntitiesEvent`.

See Commands, Placeholders, and Developer API for the full detail on each surface.

`claim-farmpass-reward`

Registered via registerAction("claim-farmpass-reward", ClaimRewardAction.class). Looks up a RewardBlueprint by id, resolves its default (free) or premium action list based on the type argument, and runs it once per player/reward/type combination (tracked in FarmPassData.claimedRewards() as "<id>_<type>"). See Rewards for the full argument reference.

Cross-server model

Exactly one node per network is configured as the master (config.yml → master: boolean). Only the master's SeasonRotationService is allowed to create or rotate seasons — non-master nodes that find no active season, or find the current season expired, log that they're waiting and clear their cached season instead of creating one. When the master creates or rotates a season it broadcasts a FarmpassUpdatedPacket (channel farmpass, packet id 0x00) over MessagingService; every node (including the master) has SeasonService listening on that exchange, and non-master nodes reload the current season from the database when the packet arrives. Player quest progress and points travel independently of this packet, via AstralSync's own cross-server replication of FarmPassData.

Astral Realms Documentation Help