Systems

Shops

Two independent shop systems:

  • Shops (config/shops/*.json): global shops with a progression currency, reputation and quest gating, gacha-style cases with quality rolls and pity, weekly cooldowns and a stats tab.
  • Private shops (config/privateshop/*.json): shops paid with a physical item (for example rusty gears), with categories, restock timers, item exchanges and arbitrary reward actions.

Both are loaded from every mod/pack that has the folder under its assets.


Regular shops: config/shops/*.json

A file contains a shops array. A shop without shopId is skipped; a later pack with the same id replaces the earlier one.

{
  "shops": [
    {
      "shopId": "trial-warden",
      "nameKey": "albase:trial-warden-name",
      "encounterId": "albase:encounter:hollowtrials",
      "currency": "albase:voidshards",
      "reputationKey": "albase:trialwarden",
      "freeItemBorderColor": "#A78BFA",
      "purchaseSound": "albase:sounds/trial-acceptance",
      "localization": {
        "currencyName": "albase:trial-currency-name",
        "currencyColor": "#A78BFA",
        "purchased": "albase:trial-shop-purchased"
      },
      "runeCurrencies": [
        { "runeId": "void-echo", "nameKey": "albase:rune-void-echo-currency", "color": "#A78BFA" }
      ],
      "items": [ ],
      "cases": { }
    }
  ]
}

How a shop is opened

  • An NPC with "shopId": "<id>" in its questgiver behavior shows a shop button (NPCs).
  • Action openshop with the shop id as the single argument (also usable as a dialogue trigger, e.g. "trigger": "openshop trial-warden").

A buy request is accepted only while a living quest giver that hosts this shopId stands within 16 blocks of the player.

Shop fields

FieldDefaultDescription
shopIdrequiredUnique id (case-insensitive)
nameKeynoneLang key of the shop name
eventIdnoneSeasonal event id (config/seasonalevents). The shop opens only while that event is active; otherwise the player gets an "event inactive" error. The window shows the end time
currencydefaultProgression currency key spent on items (for example albase:voidshards). Stored by the progression system, not as an item
reputationKeynoneReputation id (NPC scope) used for the player's reputation in this shop: the shop-level reputation, rank name and next-rank progress, and what per-item requiredReputation is compared with
encounterIdnoneLinks the shop to an encounter: pity, case progression, ranks, boss stats (the Stats tab) and progressive buff data come from that encounter
runeCurrencies[]noneRune currencies shown in the header: runeId, nameKey (falls back to albase:rune-{runeId}-currency), color (falls back to the shop currency colour)
freeItemBorderColornoneBorder colour for items with cost: 0 and no costItem
purchaseSoundnoneSound on a successful purchase (per-item purchaseSound wins)
caseTheme / caseDurationnone / 0Defaults for the case-opening animation (void, desert, halloween, ...). Items can override; 0 = built-in length
localizationnonePer-shop UI text, see below
casesnoneQuality weights, pity and progression for case items, see below
requiredQuestIdnoneQuest the player must have completed to open the shop or buy from it (checked on the server; a message is shown otherwise)
requiredReputation0Minimum reputation (from reputationKey) to open the shop or buy from it (checked on the server; a message is shown otherwise)

Item fields

Items are matched by itemCode, so every itemCode in one shop must be unique.

FieldDefaultDescription
itemCoderequiredAn action-item id (item configs, see Items), a plain item/block code, or a virtual code starting with case: for cases
nameKey / displayNamenoneLang key / plain text (a value containing a domain prefix such as albase:... is treated as a lang key)
customIconKeynoneIcon key (item:domain:code draws a game item); falls back to a case: icon for case items
cost0Price. 0 = free
costCurrencyshop currencyCurrency of this item; a shop can sell for several currencies
costItem / costItemCountnone / 0Pay with physical items taken from the inventory (and refunded if the purchase fails)
requiredReputation0Minimum reputation (from reputationKey)
maxPurchases0Per-player cap; 0 or -1 = unlimited
weeklyCooldownHours0Hours between two purchases of the item (despite the name, any number of hours)
requiredCompletedQuests + requiredCompletedQuestIds0 / noneThe player must have completed at least N of the listed quests. With a cooldown, only completions since the last purchase (or, before the first one, within the last cooldown period) count
requiredQuestsLangKeynoneReplaces the generic "complete N quests" line (args: required, done; <key>-done for the completed line)
isHiddenUntilUnlockedfalseHide the item until the quest requirement is met
fixedQuality0For action items: quality tier to apply (1-based). 0 = roll the item's normal quality
stackSize1Only used to compute the per-item price for Disenchant; a purchase always gives one item
bundleItemsnoneGive all these plain item/block codes at once instead of itemCode (a whole set for one price); the purchase fails if any code does not exist
runeCurrencynoneReward rune-case currency instead of an item: runeId, minAmount, maxAmount, notifyLangKey
bonusDropnoneFor rune-currency cases: a chance to get an item instead, see below
caseTier0Tier (1-4) of a case: item; selects quality weights, progression and pity
casePoolnoneItem codes the case can give (action-item ids)
caseRaritiesnoneRarity-based case (events), see below. Fills casePool automatically
randomCaseTiers[]noneTier is rolled on purchase: { "caseTier": 1, "weight": 50, "casePool": [...] } (casePool optional; otherwise taken from the shop's case with that tier)
caseOpenCurrency / caseOpenCurrencyAmountnone / 1Progression currency added on every open of this case (for example pity shards)
caseOpenSound / caseTickSound / caseResultSoundnoneSounds: on opening / for each reel slot passing the marker / when the reel stops
purchaseSound, caseTheme, caseDurationnonePer-item overrides

Items without case: prefix, runeCurrency, randomCaseTiers or bundleItems are given directly: a registered action item (with quality rolled or fixedQuality applied), otherwise a plain item or block. Purchase checks run in this order: reputation, maxPurchases, quest requirement, cooldown, currency, costItem.

Case rarities (caseRarities)

Used by event cases without item qualities: one rarity is picked by weight, then one of its items uniformly.

"caseRarities": [
  { "id": "candy", "weight": 400, "color": "#FB923C", "minQuantity": 8, "maxQuantity": 16,
    "items": [ "alegacyevents:halloweencandy-candycorn", "alegacyevents:halloweencandy-caramelapple" ] },
  { "id": "common", "weight": 595, "color": "#B8C0CC", "items": [ "alegacyattire:clothes-head-halloween-pumpkin-grin" ] }
]

color tints the result; minQuantity/maxQuantity set the stack size of plain items (default 1).

Bonus drop in rune cases (bonusDrop)

On each open of a rune-currency item, a bonus item may drop instead of the runes. The chance starts at baseChance, grows by chancePerMiss after every open without an item, stops at maxChance and resets on a drop. pools[] (caseTier, weight, items) are picked by weight and open as an item case of that tier. rare[] (item, chance) are jackpots rolled first at a fixed chance; they do not touch the counter.

"bonusDrop": {
  "baseChance": 0.2, "chancePerMiss": 0.06, "maxChance": 0.5,
  "pools": [ { "caseTier": 1, "weight": 30, "items": [ "albase:duat-burial-wraps", "albase:duat-scarab-amulet" ] } ],
  "rare": [ { "item": "albase:altar-temporal", "chance": 0.002 } ]
}

Cases block (cases)

FieldDescription
qualityWeightsTier number to an array of weights, one per quality (tier "1": [85, 10, 4, 1])
qualityIdsQuality ids (from the quality config) for positions 1..N. Without it the trial set is used: trial-dim, trial-shimmer, trial-radiant, trial-abyssal
qualityNameKeysLang keys for the quality names in the case window
pityGuarantees: radiantOpens (15) and abyssalOpens (50) for the trial set, or qualityOpens ({ "2": 6, "3": 8 }: quality position to opens without it before it is guaranteed, replaces the two fields). pityDefinitionPrefix: pity id = prefix + tier (without it {shopId}-case-tier{tier})
progressionPer tier, bonus to the chances for every open. Trial set: shimmeringPerOpen/shimmeringCap, radiantPerOpen/radiantCap, abyssalPerOpen/abyssalCap. Generic form: perOpen and cap arrays by quality position (position 0 ignored)

See Quality & Reroll for the qualities themselves. Real example (Duat shop):

"cases": {
  "pity": { "pityDefinitionPrefix": "albase:duat-case-tier", "qualityOpens": { "2": 6, "3": 8 } },
  "qualityWeights": { "1": [80, 17, 3], "2": [80, 17, 3] },
  "progression": { "1": { "perOpen": [0, 2, 1], "cap": [0, 20, 15] } },
  "qualityNameKeys": [ "albase:duat-quality-weathered", "albase:duat-quality-gilded", "albase:duat-quality-sunforged" ],
  "qualityIds": [ "duat-weathered", "duat-gilded", "duat-sunforged" ]
}

Texts (localization)

localization overrides the interface texts for one shop. Without it, the texts come from a pack file config/gui/shop.json (the same field names, merged field by field across packs, so a pack may set only some of them), then from built-in English defaults. Main fields:

  • Names and colours: shopTitle, reputationLabel, currencyName, currencyColor, and currencyNames / currencyColors (maps: currency key to name / hex colour, for shops with several currencies).
  • Messages: purchased ({0} item, {1} price), notEnoughShards, locked, confirmBody, confirmTitle, confirmBuy, confirmCancel, buyButton.
  • Header and ranks: nextRankText, masteryText, trialsCompletedText, challengesHeader.
  • Case window: caseOpeningTitle, caseOpeningDefaultTitle, caseOpeningHint, caseTierLabelPrefix, and tooltip texts tooltipContents, tooltipChances, tooltipOpened, tooltipShimmering, tooltipRadiant, tooltipAbyssal, tooltipGuarantee, tooltipRadiantLabel, tooltipAbyssalLabel.
  • Stats tab: tabShop, tabStats, statsTitle, statsEmpty, statsColBoss, statsColTier, statsColKills, statsColTime, statsColDeathless, statsTimeMin.
  • Item rows: currencyShort, itemLocked, itemPurchased, itemRepLocked, itemRepNeeded, itemRepRequired, itemFree.

Values are usually lang keys. The config/gui/shop.json loader reads all of the above except currencyColor, currencyNames, currencyColors, itemRepNeeded and itemFree, which work only inside a shop's own localization.

Commands

/avq shop reset [playerName] <shopId> <itemCode>

Requires the give privilege. Resets the purchase count and cooldown of one item for a player. There is no shop reload command; regular shops are read at server start.


Private shops: config/privateshop/*.json

One config object per file (not a wrapper). Open with the action openprivateshop and the shop id, or the dialogue trigger openprivateshop <shopId>:

{ "id": "openprivateshop", "args": ["albase:treasurer"] }

Without an id in the trigger, the NPC's own privateshopId (a top-level key of the entity's attributes, e.g. "privateshopId": "albase:treasurer") is used, then the NPC's code. The shopkeeper must stay alive and in range while the player buys, otherwise the purchase is rejected.

{
  "id": "albase:innkeeper",
  "titleLangKey": "albase:innkeeper-shop-title",
  "currencyItemCode": "game:gear-rusty",
  "categories": [ { "id": "ale", "titleLangKey": "albase:innkeeper-cat-ale" } ],
  "items": [
    {
      "id": "rye-ale",
      "titleLangKey": "item-ciderportion-rye",
      "iconItemCode": "game:woodbucket",
      "cost": 8,
      "category": "ale",
      "maxPurchases": 2,
      "restockHours": 144,
      "discountItem": { "code": "game:woodbucket", "amount": 1, "discountedCost": 5, "consume": true, "requireEmpty": true },
      "rewards": [ { "action": "givecontainer", "args": ["game:woodbucket", "game:ciderportion-rye", "1"] } ],
      "soundAsset": "game:sounds/effect/cashregister"
    }
  ]
}

Shop fields

FieldDefaultDescription
idrequiredShop id (for example albase:treasurer)
titleLangKeynoneWindow title
currencyItemCodenoneItem players pay with (taken from the whole inventory)
categories[]noneTabs: id, titleLangKey. Items without category go to the first tab
items[]emptyFixed items
customAllowance, customMaxAreasnoneDynamic-quantity entries that add land-claim allowance (m3) / extra claim areas
customItems[]noneDynamic-quantity entries, including item exchanges
discountAttributenonePlayer attribute holding a percent discount (10 = 10% off, clamped 0..100). The price is rounded up and never below 1
surveyAttributenonePlayer attribute holding the quiz score. Until it reaches the threshold every item is locked ("survey")
surveyQuizIdnoneQuiz offered to the player when the survey is not passed (see Quiz); starting it clears the score attribute
surveyPassedThreshold1Score needed (at least 1)
surveyAllowanceBonus0Land allowance added once, the first time the survey is passed
surveyRewardNotifyKeynoneMessage shown for that bonus

Item fields

FieldDefaultDescription
idrequiredStable id (used by the buy packet and the purchase records)
titleLangKey, subtitleLangKey, tooltipLangKeynoneTexts
iconItemCode, iconUcontentsnoneIcon item and, for containers, the liquid code inside (taken from the first reward when not set)
quantityautoQuantity shown/given; auto-detected from rewards when unset
cost0Price in currencyItemCode
categoryfirst tabCategory id
rewards[]noneActions run on purchase, in quest-action format { "action": "giveitem", "args": [...] } (the key here is action, whereas quest action lists use id). When present, addAllowance/addMaxAreas are ignored
addAllowance, addMaxAreas0Legacy shortcuts: add land-claim m3 allowance / extra areas
maxPurchases0Purchases per player; 0 = unlimited
restockHours0Game hours after which the purchase counter resets; 0 = the cap is permanent
cooldownHours0Game hours between two purchases
requiredQuestnoneQuest that must have been completed
requiredReputationnone{ "id": "...", "scope": "npc", "min": N }
requiredItemnone{ "code": "...", "amount": 1 }: must be in the inventory, not consumed
discountItemnoneIf the player carries code x amount, the price becomes discountedCost (min 1). consume (default true) takes the item on purchase; requireEmpty counts only stacks without liquid contents
soundAsset, notifyLangKey, confirmBeforeBuy, tooltipLangKeynone / falseFeedback and a confirmation dialog

Dynamic entries (customAllowance, customMaxAreas, customItems[])

The player types a quantity; the window shows the live price.

FieldDefaultDescription
id, titleLangKey, hintLangKeynoneTexts (hint: {0} unit size, {1} cost per unit)
unitSize1One unit = this many m3 / areas, or this many input items for exchanges
costPerUnit0Price per unit in currencyItemCode (may be 0)
defaultQuantity, minQuantity, maxQuantity1, 1, 0Quantity bounds (0 = unlimited)
inputItemCode, outputItemCodenoneTurns the entry into an item exchange: each unit consumes unitSize inputs and gives outputPerUnit outputs
outputPerUnit0Outputs per unit; 0 = same as unitSize (1:1)
extraInputItemCode, extraInputPerUnitnone, 1Second input consumed per unit (for example coal next to steel bits)
soundAsset, notifyLangKeynoneFeedback. Notify args: {0} units, {1} total cost; for exchanges {0} input consumed, {1} output given, {2} extra input, {3} total cost

The real forge exchange (albase:warlord-forge) turns 20 steel bits plus 1 coal into one steel ingot for free.

Commands

/avq privateshop reload
/avq privateshop list
/avq privateshop info <shopId>

All need the give privilege. reload re-reads every config/privateshop file.

Press ESC to close