Configuration

Recap window

recap-interval (default 24h) is the lookback window for the on-demand /ps recap command (see Commands): it computes recap entries from System.currentTimeMillis() - recap-interval up to now. It only applies to that command — the automatic "while you were away" recap shown on login instead uses the player's last-logout timestamp, not recap-interval. See Activity Recaps for both flows.

Shop limits

The effective limit for a player is the highest value among limits.default and every permission node in limits.permissions the player holds — lower-tier permissions don't cap a player who also holds a higher one:

ShopService.create checks this before creating a shop: if the player's current shop count (from the database) is >= the limit, creation is rejected with LIMIT_REACHED (placeholder %limit%) and no dialog opens.

Sign lines

sign is a list of up to 4 component-wrapper lines (MiniMessage/legacy strings, resolved through AstralCore's placeholder wrapper system) rendered onto the shop's wall sign. It refreshes on shop creation, after every buy/sell, and on the periodic sign-refresh tick (see Sign & stock refresh). A 5th line is rejected — a vanilla sign only has 4 lines — and the refresh throws instead of partially updating.

Placeholders resolve through a PlaceholderContainer scoped just to this render: the shop itself under the shop namespace, plus a stock value computed live from the backing container. The shipped file uses:

Any other shop-namespaced field also resolves here — %shop_id%, %shop_owner%, %shop_material%, %shop_type%, %shop_item%, %shop_location%, %shop_townShared%, %shop_townEconomy% — see Shops for what each one carries.

Container & item restrictions

blacklisted-containers is checked in two places:

• Shop creation — sneak-right-clicking a container with an item in hand only opens the creation dialog if the container's type is not in this set.

• Placement near a shop — placing a new container block normally triggers a check that cancels the placement (NO_PERMISSION_PLACE_NEAR) if it's adjacent to a shop the placer doesn't have permission on. Blacklisted container types skip this check entirely — they can be placed next to someone else's shop freely, since they could never become a competing shop themselves.

ignored-items is checked only at creation time: if the item held while sneak-right-clicking a container is in this set, the creation dialog never opens. The shipped list blocks every placeable sign type (a shop can't be stocked with the signs it renders itself onto), chest/trapped_chest/hopper (containers as stock), and item_frame/painting/armor_stand (placeable entities, not stackable block/item stock).

Sign & stock refresh

updates drives ChunkTickTask, the repeating task that refreshes every shop's sign (stock counts, etc.) without waiting for a buy/sell to trigger it:

• The task only exists on a server whose group (AstralPaperAPI.serverInformation().group()) is in enabled-groups — otherwise ShopService never creates or schedules it, and that server gets no periodic refresh at all.

• When it runs, each pass round-robins through the currently loaded chunks of every world in enabled-worlds, ticking up to chunks-per-tick chunks that haven't been processed in the current cycle (tracked per world); once every loaded chunk has been processed the cycle resets. A chunk that throws during processing is still marked processed, so one broken chunk can't stall the rotation. Chunks that unload are evicted from the processed set to avoid unbounded growth.

• enabled-worlds also gates item-display (hologram) spawning on chunk load — ShopService.loadChunk (called from ChunkLoadEvent and once per already-loaded chunk during startup) is a no-op for worlds outside this set. Shop creation, buying, and selling are not restricted to enabled-worlds — only the sign-refresh task and hologram spawning are.

• Fallbacks live in the Updates record's compact constructor: a non-positive interval-ticks or chunks-per-tick, or a missing enabled-worlds/enabled-groups key, silently falls back to 100/20/[world]/[build]. Omitting the whole updates: block does the same, applied one level up in PSConfiguration.