Overview

AstralFarmPass is the seasonal battle-pass plugin for AstralRealms. A season is a calendar month: every month deals a fresh set of daily and weekly quests, players advance them through normal gameplay to earn points, and spend those points unlocking the free and premium tiers of the reward ladder from the /pass menu.

Quests are generated deterministically from the month, a configured salt and the loaded blueprint files — no database, no master node, no coordination. Every server derives the same quests, with the same targets and the same identifiers. Only what a player did with those quests is stored, and that travels through AstralSync.

Core concepts

Concept	Summary
Season	The current calendar month in the configured time zone, identified by its `YearMonth` (`2026-08`). Rolling into a new month re-generates every quest and resets every player's pass.
Quest blueprint	One `blueprints/**.yml` file — a display item, a quest goal, a `goal-value` range the target is rolled in, optional completion requirements, and an optional availability window.
Quest instance	A blueprint dealt to a slot of the current month: a deterministic id, a rolled target, and an `unlocksAt`/`expiresAt` window. Identical on every server.
Quest type	`DAILY` or `WEEKLY` — each maps to a `categories` entry in `config.yml` that sets how many quests per batch, how often a batch is dealt, how long it lives, and how many points completing one awards.
Points	Per-player, per-season currency (`FarmPassPlayerData.points()`), earned by completing quests and spent claiming reward tiers. Never negative.
Reward tier	An entry in `rewards.yml` gated behind a `required-points` threshold, with a free (`default-actions`) and a premium (`premium-actions`) track, each claimed separately.

Architecture at a glance

plugins/AstralFarmPass/
├── config.yml       ← time zone, seed salt, value rounding, premium permission, categories
├── messages.yml     ← player-facing strings
├── rewards.yml      ← the reward ladder (free + premium tracks)
├── blueprints/      ← one YAML file per possible quest; sub-folders are scanned too
│   ├── daily/
│   └── weekly/
└── menus/                        ← not written out automatically; see Configuration
    ├── main.yml              ← `farmpass-main`, opened by /pass
    └── pass-weekly_quest.yml ← `pass-weekly_quest`, the month's weekly quests

How the pieces fit together

BlueprintService loads every YAML file under blueprints/ (recursively) into a sorted registry of QuestBlueprints and prints a fingerprint — a hash of everything that influences generation. Two servers that don't print the same fingerprint will not deal the same quests. See Quests & Goals.
QuestService generates the whole month up-front from Seeds: the blueprint pool of each quest type is shuffled once for the month and dealt period by period, and each slot's target is rolled inside the blueprint's goal-value range. Nothing is persisted — the same inputs re-derive the same output on every server and after every restart. See Seasons & Generation.
EventService registers a listener for every entry of EventAdapterRegistry (20 events), turns each one into a QuestGoalContext, and runs it against every active quest. A goal that recognises the event returns the progress it is worth; when a quest reaches its target, the type's reward points are credited and quest-completed is sent. See Quests & Goals.
MultiKillService batches same-tick kills per player and raises PlayerMultiKillEvent, which is what lets a quest ask for several mobs killed in a single swing.
rewards.yml defines the point-gated ladder; the /pass menu claims a tier with the claim-farmpass-reward action. See Rewards.
FarmPassSnapshotAdapter persists and cross-server syncs FarmPassPlayerData through AstralSync, stamping the season it was saved under so a player who was offline over a rollover is reset on join.

Requirements

Dependency	Required	Notes
Paper 1.21+	Yes	`api-version: '1.21'`; built against Paper/Purpur 1.21.10.
AstralCore	Yes	Plugin bootstrap (`AstralPaperPlugin`), configuration, menus, actions, requirements, placeholders.
AstralVote	Yes	`depend`; fires `PlayerVoteEvent`, consumed by `player-vote`.
AstralScrolls	Yes	`depend`; fires `ScrollCompletedEvent`, consumed by `player-scroll`.
AstralTower-Bridge	Yes	`depend`; fires `TowerFinishedEvent`, consumed by `player-tower`.
AstralShop	Yes	`depend`; fires `ShopSellEvent`, consumed by `shop-sell`.
AstralSync	Runtime	Not in `plugin.yml` `depend`, but required: all player state is held and replicated as a `FarmPassPlayerData` snapshot.

There is no database and no messaging channel — both were removed once generation became deterministic. Nothing about a season is written anywhere.

Registered surfaces

Everything AstralFarmPass#onEnable registers:

Surface	Name	Notes
Action	`claim-farmpass-reward`	Claims one track of one reward tier. Registered on the plugin's own registry (`registerAction`), so it resolves in AstralFarmPass configs only.
Command	`/pass` (alias `/farmpass`)	Opens the main menu; `reload` and `points` subcommands.
Placeholder namespace	`%farmpass_…%`	`season`, `points`, `rewards`, `quests_<TYPE>`, `all_<TYPE>`.
Sync adapter	`farmpass:data`	`FarmPassSnapshotAdapter`, backing `FarmPassPlayerData`.
Menus	`farmpass-main`, `pass-weekly_quest`	Loaded from `menus/`; the bundled copies are not written out on first start.
Listeners	one per `EventAdapterRegistry` entry	Registered at `MONITOR` priority through `ReflectionUtils.forceRegisterEvent`; cancelled events are skipped.
Listener	`MultiKillService`	Batches same-tick kills and fires `PlayerMultiKillEvent`.

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

Cross-server model

Every node generates the same season independently. What must match across the network is the generation input: time-zone, seed-salt, the categories block and the blueprint files — the fingerprint logged at startup is there to check exactly that. Player progress, points and claimed rewards are the only things that travel, through AstralSync's replication of FarmPassPlayerData.

Astral Realms Documentation Help