Astral Realms Documentation Help

Rewards

rewards.yml is the pass's ladder: an ordered list of tiers, each gated behind a points threshold, each with a free and a premium track that are claimed separately. Players spend nothing — points are a threshold, not a currency: claiming a tier does not lower the total, so reaching 45 000 points unlocks every tier below it.

rewards.yml format

rewards: - id: "reward_2" required-points: 2000 display: copy-from: "%stacksuppliers_ce_icons:coins%" name: "<primary_color><bold>Palier 2" lore: - " <text_color>Récompense : <#d5d5d5><bold>2.500<white>%img_icons:coins%" premium-display: copy-from: "%stacksuppliers_ce_icons:coins%" name: "<primary_color><bold>Palier 2" lore: - " <text_color>Récompense : <#d5d5d5><bold>5.000<white>%img_icons:coins%" default-actions: - "[console] eco give %player_name% default 2500" - "[message] <success>Vous obtenez <#d5d5d5><bold>2.500<white>%img_icons:coins% <#80ed99>!" premium-actions: - "[console] eco give %player_name% default 5000" - "[message] <success>Vous obtenez <#d5d5d5><bold>5.000<white>%img_icons:coins% <#80ed99>!"

Field

Type

Required

Description

id

String

Yes

Tier identifier. It is what [claim-farmpass-reward] names and what claims are recorded under, so it must be unique and stable — changing it makes every previous claim of that tier claimable again.

required-points

int

Yes

Points the player must have reached to claim either track.

display

ItemStackWrapper

No

The free track's icon.

premium-display

ItemStackWrapper

No

The premium track's icon.

default-actions

PaperActionList

No

What the free track hands out.

premium-actions

PaperActionList

No

What the premium track hands out.

The list order is the order the menu lays the tiers out — RewardsConfiguration keeps it as written and only ever looks a tier up by id.

A tier may have no default-actions at all, in which case only the premium track gives something; the menu draws an empty slot on the free row for those (%reward_hasDefault% is what it checks).

Tracks and claim tracking

RewardType has two values, FREE and PREMIUM. Each track of each tier is claimed independently and recorded in FarmPassPlayerData.claimedRewards() as "<id>_<free|premium>" — so reward_2_free and reward_2_premium are two separate claims.

The premium track is gated by the premium-permission from config.yml (farmpass.premium by default). Leaving that key empty opens the premium track to everyone.

Claims are wiped with everything else at the season rollover.

claim-farmpass-reward

Claims one track of one tier for the executing player.

Arg

Type

Description

id

String

Tier id, one token. Placeholder-aware — the menu passes %parameter_reward_id%. An unknown id throws.

type

String

free or premium, case-insensitive. Placeholder-aware. Anything else throws.

actions: - "[claim-farmpass-reward] %parameter_reward_id% free"

The action is registered on the plugin's own registry (registerAction), so it resolves in AstralFarmPass's own configuration — its menus and rewards.yml — and not in other plugins' configs.

Claim flow

In order:

  1. The type and id are parsed and the tier looked up; an unknown id or type throws.

  2. The player's FarmPassPlayerData is resolved. If their snapshot is not loaded, the action silently does nothing.

  3. Already claimed on that track → reward-already-claimed, stop.

  4. Points below required-points → reward-not-unlocked, carrying %points% = how many are missing, stop.

  5. Premium track without premium-permission → reward-premium-only, stop. The menu already hides the premium row from players without it, but an action is reachable from wherever it is configured, so it checks rather than trusting the icon.

  6. The claim is recorded, then the track's action list runs.

Recording before running is deliberate: a double click must not hand the reward out twice, and a tier with nothing on this track still counts as claimed so the menu can tick it off. It also means a failing action list does not un-claim the tier.

Points are never deducted.

Placeholders

Under the reward namespace, as fed to the menu by %farmpass_rewards%:

Placeholder

Resolves to

%reward_id%

The tier id.

%reward_requiredPoints%

Its threshold.

%reward_display%/%reward_premiumDisplay%

The two icons (null when the tier omits one).

%reward_hasDefault%/%reward_hasPremium%

Whether that track has a non-empty action list.

%reward_claimed_free%/%reward_claimed_premium%

Whether the viewer already claimed that track.

%reward_available_free%/%reward_available_premium%

Whether the viewer can claim it now — not claimed and enough points. Note this does not test the premium permission.

See Placeholders for the full namespace.

The shipped farmpass-main menu drives three layouts (rewards_free, rewards_all, rewards_premium) off the same %farmpass_rewards% provider, so the three rows stay aligned page by page: the free track on row 1, the claim row on row 2, the premium track on row 4. Each row picks its icon with view-requirements on %parameter_reward_claimed_…%/%parameter_reward_available_…%, and the claim row runs the action then refreshes all three layouts:

actions: - "[claim-farmpass-reward] %parameter_reward_id% free" - "[claim-farmpass-reward] %parameter_reward_id% premium" - "[refresh-layout] rewards_all" - "[refresh-layout] rewards_free" - "[refresh-layout] rewards_premium"

Running both claims from one click is safe: whichever one is not applicable stops on its own check.

Earning and adjusting points

Points come from completing quests — the reward of the quest's category — and can be adjusted by staff with /pass points. They never go below 0, and %farmpass_points% exposes the current total.

Further reading

Last modified: 25 September 2026
Seasons & GenerationPlaceholders