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 itsquestgiverbehavior shows a shop button (NPCs). - Action
openshopwith 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
| Field | Default | Description |
|---|---|---|
shopId | required | Unique id (case-insensitive) |
nameKey | none | Lang key of the shop name |
eventId | none | Seasonal 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 |
currency | default | Progression currency key spent on items (for example albase:voidshards). Stored by the progression system, not as an item |
reputationKey | none | Reputation 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 |
encounterId | none | Links the shop to an encounter: pity, case progression, ranks, boss stats (the Stats tab) and progressive buff data come from that encounter |
runeCurrencies[] | none | Rune currencies shown in the header: runeId, nameKey (falls back to albase:rune-{runeId}-currency), color (falls back to the shop currency colour) |
freeItemBorderColor | none | Border colour for items with cost: 0 and no costItem |
purchaseSound | none | Sound on a successful purchase (per-item purchaseSound wins) |
caseTheme / caseDuration | none / 0 | Defaults for the case-opening animation (void, desert, halloween, ...). Items can override; 0 = built-in length |
localization | none | Per-shop UI text, see below |
cases | none | Quality weights, pity and progression for case items, see below |
requiredQuestId | none | Quest the player must have completed to open the shop or buy from it (checked on the server; a message is shown otherwise) |
requiredReputation | 0 | Minimum 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.
| Field | Default | Description |
|---|---|---|
itemCode | required | An action-item id (item configs, see Items), a plain item/block code, or a virtual code starting with case: for cases |
nameKey / displayName | none | Lang key / plain text (a value containing a domain prefix such as albase:... is treated as a lang key) |
customIconKey | none | Icon key (item:domain:code draws a game item); falls back to a case: icon for case items |
cost | 0 | Price. 0 = free |
costCurrency | shop currency | Currency of this item; a shop can sell for several currencies |
costItem / costItemCount | none / 0 | Pay with physical items taken from the inventory (and refunded if the purchase fails) |
requiredReputation | 0 | Minimum reputation (from reputationKey) |
maxPurchases | 0 | Per-player cap; 0 or -1 = unlimited |
weeklyCooldownHours | 0 | Hours between two purchases of the item (despite the name, any number of hours) |
requiredCompletedQuests + requiredCompletedQuestIds | 0 / none | The 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 |
requiredQuestsLangKey | none | Replaces the generic "complete N quests" line (args: required, done; <key>-done for the completed line) |
isHiddenUntilUnlocked | false | Hide the item until the quest requirement is met |
fixedQuality | 0 | For action items: quality tier to apply (1-based). 0 = roll the item's normal quality |
stackSize | 1 | Only used to compute the per-item price for Disenchant; a purchase always gives one item |
bundleItems | none | Give 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 |
runeCurrency | none | Reward rune-case currency instead of an item: runeId, minAmount, maxAmount, notifyLangKey |
bonusDrop | none | For rune-currency cases: a chance to get an item instead, see below |
caseTier | 0 | Tier (1-4) of a case: item; selects quality weights, progression and pity |
casePool | none | Item codes the case can give (action-item ids) |
caseRarities | none | Rarity-based case (events), see below. Fills casePool automatically |
randomCaseTiers[] | none | Tier is rolled on purchase: { "caseTier": 1, "weight": 50, "casePool": [...] } (casePool optional; otherwise taken from the shop's case with that tier) |
caseOpenCurrency / caseOpenCurrencyAmount | none / 1 | Progression currency added on every open of this case (for example pity shards) |
caseOpenSound / caseTickSound / caseResultSound | none | Sounds: on opening / for each reel slot passing the marker / when the reel stops |
purchaseSound, caseTheme, caseDuration | none | Per-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)
| Field | Description |
|---|---|
qualityWeights | Tier number to an array of weights, one per quality (tier "1": [85, 10, 4, 1]) |
qualityIds | Quality ids (from the quality config) for positions 1..N. Without it the trial set is used: trial-dim, trial-shimmer, trial-radiant, trial-abyssal |
qualityNameKeys | Lang keys for the quality names in the case window |
pity | Guarantees: 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}) |
progression | Per 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, andcurrencyNames/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 textstooltipContents,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
| Field | Default | Description |
|---|---|---|
id | required | Shop id (for example albase:treasurer) |
titleLangKey | none | Window title |
currencyItemCode | none | Item players pay with (taken from the whole inventory) |
categories[] | none | Tabs: id, titleLangKey. Items without category go to the first tab |
items[] | empty | Fixed items |
customAllowance, customMaxAreas | none | Dynamic-quantity entries that add land-claim allowance (m3) / extra claim areas |
customItems[] | none | Dynamic-quantity entries, including item exchanges |
discountAttribute | none | Player attribute holding a percent discount (10 = 10% off, clamped 0..100). The price is rounded up and never below 1 |
surveyAttribute | none | Player attribute holding the quiz score. Until it reaches the threshold every item is locked ("survey") |
surveyQuizId | none | Quiz offered to the player when the survey is not passed (see Quiz); starting it clears the score attribute |
surveyPassedThreshold | 1 | Score needed (at least 1) |
surveyAllowanceBonus | 0 | Land allowance added once, the first time the survey is passed |
surveyRewardNotifyKey | none | Message shown for that bonus |
Item fields
| Field | Default | Description |
|---|---|---|
id | required | Stable id (used by the buy packet and the purchase records) |
titleLangKey, subtitleLangKey, tooltipLangKey | none | Texts |
iconItemCode, iconUcontents | none | Icon item and, for containers, the liquid code inside (taken from the first reward when not set) |
quantity | auto | Quantity shown/given; auto-detected from rewards when unset |
cost | 0 | Price in currencyItemCode |
category | first tab | Category id |
rewards[] | none | Actions 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, addMaxAreas | 0 | Legacy shortcuts: add land-claim m3 allowance / extra areas |
maxPurchases | 0 | Purchases per player; 0 = unlimited |
restockHours | 0 | Game hours after which the purchase counter resets; 0 = the cap is permanent |
cooldownHours | 0 | Game hours between two purchases |
requiredQuest | none | Quest that must have been completed |
requiredReputation | none | { "id": "...", "scope": "npc", "min": N } |
requiredItem | none | { "code": "...", "amount": 1 }: must be in the inventory, not consumed |
discountItem | none | If 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, tooltipLangKey | none / false | Feedback and a confirmation dialog |
Dynamic entries (customAllowance, customMaxAreas, customItems[])
The player types a quantity; the window shows the live price.
| Field | Default | Description |
|---|---|---|
id, titleLangKey, hintLangKey | none | Texts (hint: {0} unit size, {1} cost per unit) |
unitSize | 1 | One unit = this many m3 / areas, or this many input items for exchanges |
costPerUnit | 0 | Price per unit in currencyItemCode (may be 0) |
defaultQuantity, minQuantity, maxQuantity | 1, 1, 0 | Quantity bounds (0 = unlimited) |
inputItemCode, outputItemCode | none | Turns the entry into an item exchange: each unit consumes unitSize inputs and gives outputPerUnit outputs |
outputPerUnit | 0 | Outputs per unit; 0 = same as unitSize (1:1) |
extraInputItemCode, extraInputPerUnit | none, 1 | Second input consumed per unit (for example coal next to steel bits) |
soundAsset, notifyLangKey | none | Feedback. 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.