Astral Realms Documentation Help

Placeholders

AstralFarmPass registers one root placeholder namespace, farmpass, plus three chainable ComplexPlaceholder types (quest, blueprint, reward) reached through it. For the placeholder syntax itself (%a_b_c%, %a_{b_c}%) see AstralCore's Placeholders.

farmpass_* (root)

FarmPassPlaceholders — requires a Player context (context.context() instanceof Player); resolves to null for a non-player context.

Placeholder

Type

Description

%farmpass_points%

int

The player's current season point balance (FarmPassData.points()), or 0 if no synced data exists yet.

%farmpass_quests%

ItemProvider<QuestInstance>

The player's non-expired quest instances (FarmPassData.quests(), filtered by !quest.expired()), or null if no synced data exists.

%farmpass_rewards%

ItemProvider<RewardBlueprint>

Every loaded reward blueprint from rewards.yml, in no particular player-specific order.

ItemProvider results are meant to back a menu layout's provider: — iterating exposes each element as a quest_* or reward_* placeholder in turn. See Placeholders for ItemProvider chains (%..._size%, %..._at_<n>%, %..._iterator%).

quest_*

A QuestInstance placeholder (namespace quest). Reached via %farmpass_quests% or any menu parameter a quest layout supplies.

Placeholder

Type

Description

%quest_id%

UUID

The quest instance's unique id.

%quest_blueprint%

Blueprint

The QuestBlueprint this instance was rolled from — chain into blueprint_*.

%quest_categoryId%

String

The category id (daily/weekly) this instance belongs to.

%quest_item%

ItemStack

The blueprint's display item, resolved with %required%/%total% injected into the placeholder context (see below). null outside a player context.

%quest_unlocksAt%

Time

The instance's unlock timestamp — chain into time_* (%quest_unlocksAt_format%, %quest_unlocksAt_remaining%, ...).

%quest_unlocked%

boolean

true once System.currentTimeMillis() >= unlocksAt.

%quest_target%

int

The randomly-rolled target amount for this instance.

%quest_progress%

int

The player's current progress toward target.

%quest_expiration%

Time

The instance's expiry timestamp — chain into time_*.

%quest_expired%

boolean

true once System.currentTimeMillis() > expiresAt.

%quest_completed%

boolean

true once progress >= target.

%required%/%total% inside quest_item

Resolving %quest_item% registers two extra placeholders directly on the placeholder container before evaluating the blueprint's display: required (the instance's current progress) and total (its target). These are only meaningful inside that display's own name/lore template — use them as bare %required%/%total%, not chained under quest_:

# quests/simple.yml blueprints: wheat: display: material: "wheat" name: "Wheat Farmer" lore: - "Harvest %required%/%total% wheat to complete this quest."

blueprint_*

A QuestBlueprint placeholder (namespace blueprint). Reached via %quest_blueprint%.

Placeholder

Type

Description

%blueprint_id%

String

The blueprint's key from quests/*.yml (e.g. wheat).

%blueprint_display%

ItemStackWrapper

The blueprint's unresolved display template.

%blueprint_goal%

QuestGoal

The blueprint's gameplay-trigger goal object. See Quests & Goals.

reward_*

A RewardBlueprint placeholder (namespace reward). Reached via %farmpass_rewards%.

Placeholder

Type

Description

%reward_id%

String

The reward's key from rewards.yml.

%reward_requiredPoints%

int

The required-points threshold to unlock this tier.

%reward_display%

ItemStack

The tier's free (default) display item, resolved against the current context — null if the blueprint has no display key.

%reward_premiumDisplay%

ItemStack

The tier's premium display item, resolved against the current context — null if the blueprint has no premium-display key.

%reward_hasDefault%

boolean

true when the blueprint has a non-empty default action list.

%reward_hasPremium%

boolean

true when the blueprint has a non-empty premium action list.

%reward_claimed_free%

boolean

Player-scoped. true if the player has already claimed the free tier (FarmPassData.claimedRewards() contains "<id>_free"). false if no synced data exists.

%reward_claimed_premium%

boolean

Player-scoped. Same check for "<id>_premium".

%reward_available_free%

boolean

Player-scoped. true when the free tier is unclaimed and the player's points meet requiredPoints. Throws if no synced data exists.

%reward_available_premium%

boolean

Player-scoped. Same check for the premium tier.

claimed/available require a next token (free or premium, case-insensitive — parsed by RewardType.parse) and a Player context; both resolve to null without a next token or a non-player context.

Usage: the main menu

quest_*/reward_* placeholders don't appear as free-standing %quest_...% strings in configs — they're produced by iterating %farmpass_quests%/%farmpass_rewards% through a menu layout, and evaluated once per iteration inside that layout's item template. The shipped farmpass-main menu wires the quest grid this way:

# menus/main.yml layouts: quests: taint: "quests" provider: "%farmpass_quests%" items: quest: material: "paper" copy-from: "%parameter_quest_item%" slot: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] taints: - "quests"

For each slot the quests layout renders, AstralCore's LayoutInstance registers the current provider element under a parameter key equal to that element's own placeholder namespace — since QuestInstance's namespace is quest, that's the key quest. %parameter_quest_item% therefore resolves parameter → quest (the current QuestInstance) → item (its own item case), i.e. it's equivalent to %quest_item% evaluated against that instance. The quest item's copy-from pulls that fully-resolved ItemStack — target/progress lore and all — into the slot.

The shipped farmpass-main menu only wires this one quests layout — it defines no layout or item for %farmpass_rewards%. The same provider/parameter pattern applies if a server adds a reward-tier layout: a reward item would read %parameter_reward_...% (or bare %reward_...%, depending on how it's bound), and would typically check %reward_available_free%/%reward_claimed_free% to decide which lore or action to show before firing claim-farmpass-reward.

Last modified: 25 July 2026
RewardsDeveloper API