Systems
Bounty Board
A mercenary job board with server-generated contracts, player-posted contracts, PvP bounties, a community reward fund and a reputation shop. Everything is data: the engine loads config/bounty/** from every mod/pack domain. Contracts are shown in a board GUI (tabs Server, Players, Mine, Fund, plus the shop) and tracked by the quest system as runtime quests.
The framework supplies the engine and GUI; the board block that opens it lives in the server mod (albase:bounty in alegacy_patches, which calls OpenBoardFor). The framework itself has no block or item that opens the board.
Config files
All paths are relative to assets/<domain>/config/bounty/. Property names are matched case-insensitively; the shipped files use PascalCase.
| File | Purpose | Merging across packs |
|---|---|---|
pools.json | Targets, demand and reward ranges | The first file found sets scalar fields (ranges, reputation key, sound); later files only add targets and fund item bands |
rarities.json | Array of rarity tiers | Arrays concatenate |
seasonal/*.json | One season per file | All collected |
player-tasks.json | Player-posted contract limits | Last domain wins |
pvp.json | Player-vs-player bounties | Last domain wins |
fund.json | Reward fund | Last domain wins |
shop.json | Reputation shop | Categories merge by Id (items append); Enabled: false in any file disables the shop |
The config is read once at server start. /avq reload does not reload it - restart the server after editing. If there are no rarities the board stays empty and a warning is logged.
The number of server contracts one player may hold at once (MaxActiveServerContracts) is 2 and has no file entry, so it is not configurable from packs.
Rarities (rarities.json)
An array. One rotation per rarity: when RefreshHours of world-calendar time have passed, all unclaimed server contracts of that rarity are removed and a fresh batch is generated. Contracts a player already accepted survive the rotation.
[
{
"Id": "common",
"Weight": 40,
"MaxActivePerPlayer": 1,
"RefreshHours": 30,
"ContractsPerRotationRange": [4, 14],
"RewardMultiplier": 1.0,
"DemandMultiplier": 1.0,
"ExpireDaysMin": 12,
"ExpireDaysMax": 18,
"ColorHex": "#8E8E8E"
}
]| Field | Default | Description |
|---|---|---|
Id | required | Rarity id; referenced from targets, fund tags and /bountydiag |
Weight | 1 | Present in the shipped files but not used by the generator: every rarity rotates on its own timer |
MaxActivePerPlayer | 1 | Present in the shipped files but not enforced; the real limit is 2 server contracts per player in total |
RefreshHours | 24 | Hours between rotations |
ContractsPerRotation | 1 | Contracts per rotation |
ContractsPerRotationRange | none | [min,max], rolled each rotation; overrides ContractsPerRotation |
RewardMultiplier | 1.0 | Scales rewards |
DemandMultiplier | 1.0 | Scales demand (not applied when the target sets an explicit demand range) |
ExpireDays | 0 | Lifetime in days (0 = never). If only this is set, it varies by +/-20% |
ExpireDaysMin, ExpireDaysMax | 0 | Random lifetime range; takes precedence over ExpireDays |
ColorHex | none | GUI accent #RRGGBB |
The shipped set is common, rare, epic, legendary (multipliers 1, 2, 3.5, 5). The id common is special: seasonal templates are only mixed into common contracts.
Pools (pools.json)
Contract kinds
| Kind | Meaning | Pool lists |
|---|---|---|
kill_entity | Kill N creatures (a tag: prefix targets an entity tag) | KillTargets / KillTargetEntries |
gather_item | Hand in N items | GatherTargets / GatherTargetEntries |
break_block | Break N blocks | BlockTargets / BlockTargetEntries |
complete_encounter | Finish an encounter (demand always 1) | CompleteEncounterTargets / EncounterTargetEntries |
kill_player | PvP bounty, only from players | not generated |
A kind is only offered when its pool has at least one valid entry. Plain lists (KillTargets etc.) are codes; the *Entries lists hold weighted objects and replace the plain list when present. Wildcards (game:log-*) are allowed and resolved to a concrete code on generation. Targets the server cannot track are skipped; for break_block water/lava/fire/air are rejected, for kill_entity players, traders, villagers, boats, carts, armor stands and dummies are rejected.
Encounter targets are written encounterId or encounterId|difficulty.
Target entries
{
"Code": "game:locust-corrupt",
"Weight": 3,
"AllowedRarities": ["rare", "epic", "legendary"],
"RewardMultiplier": 1.2,
"Demand": [25, 40],
"DemandByRarity": { "rare": [15, 20], "epic": [25, 35], "legendary": [40, 50] }
}| Field | Default | Description |
|---|---|---|
Code | required | Entity / item / block code, wildcard allowed |
Kind | pool's kind | Override the kind, so a target in one list can generate another kind |
Weight | 1 | Relative pick weight |
AllowedRarities | all | Rarities this target may appear in |
RewardMultiplier | 1.0 | Extra multiplier on the reward |
Demand | pool range | [min,max] for this target |
DemandByRarity | none | Per-rarity range; wins over Demand |
TargetName | resolved | Lang key or text shown as the target name |
ExcludedTargetCodes | none | Codes skipped when a wildcard Code expands (game:log-resin-*) |
Scalar fields
| Field | Default | Description |
|---|---|---|
KillDemand, GatherDemand, BlockDemand | [5,30], [5,32], [10,64] | Default demand per kind, multiplied by the rarity DemandMultiplier unless the entry has its own range |
CompleteEncounterDemand | [1,1] | Always forced to 1 when rolling |
RewardCurrencyKey | none | Currency key paid out (no currency reward when empty) |
RewardCurrencyAmount | [5,20] | Base currency range |
RewardReputationKey | none | Reputation key granted on completion; it is also the currency of the board shop |
RewardReputationAmount | [0,0] | Base reputation range |
CompleteEncounterReputationAmount | [5,15] | Reputation range for encounter contracts |
RewardItems | [] | Minted item rewards: ItemCode, Weight, Amount, AmountByRarity, ScaleAmount (default true), AllowedRarities |
RewardItemBonusChance | 0.25 | Chance to add a minted item on top of a fund reward |
RewardItemEmptyFundChance | 1.0 | Chance of a minted item when the fund holds nothing |
MaxFundItemRewards | 1 | Fund stacks pledged per contract |
FundItemBands | [] | Rarity restriction by item code, see Fund |
CompleteSound | sounds/tutorialstepsuccess | Sound when a contract is completed |
Reward formula
Each reward amount is base roll x rarity RewardMultiplier x target RewardMultiplier x demand factor, where the demand factor is min(3, 1 + log10(demand)). Reputation is minted. Currency (if the fund is enabled) is only paid up to what the fund holds. A contract that ends up with no reward at all is discarded, so an empty fund with no RewardItems and no reputation yields an empty board.
Duplicates are avoided: two identical contracts are never offered at the same time.
Seasonal contracts (seasonal/*.json)
Independent of the seasonal events system: this one switches on the calendar month of the world.
{
"Id": "autumn",
"Months": ["September", "October", "November"],
"Templates": [
{
"Kind": "gather_item",
"Target": "game:mushroom-*",
"TargetName": "alegacyvsquest:bounty-mushroom",
"Demand": [6, 24],
"Weight": 3,
"RewardMultiplier": 1.2
}
]
}Months uses English month names. While a season is active, roughly half of the common contracts are drawn from its templates (the rest, and the fallback if a template cannot be tracked, come from the normal pools). Template fields: Kind, Target (wildcards and tag: allowed for kills), Demand (default [10,30]), Weight, RewardMultiplier, TargetName. The contract carries the season id as a tag. Shipped seasons: spring, summer, autumn, winter.
Reward fund (fund.json)
The fund is a shared pool that pays for server contracts. Players donate items or currency in the Fund tab; the generator pledges stacks out of it when it creates a contract, and returns unclaimed pledges when a rotation drops the contract.
| Field | Default | Description |
|---|---|---|
Enabled | true | With the fund off, currency rewards are minted without limit and no items are drawn |
DonationEnabled | true | Allow donations |
SkipGenerationWhenEmpty | false | Skip generating a contract when the fund cannot cover its reward |
DonationSlotCount | 8 | Slots in the donation window |
Donations can be tagged with a rarity (moderators can retag too), so valuable items wait for a contract of that rarity. Items without a tag follow FundItemBands from pools.json:
"FundItemBands": [
{ "Match": "steel", "AllowedRarities": ["epic", "legendary"], "Weight": 3 }
]Match is a case-insensitive substring of the item code, or a wildcard pattern when it contains *; the first matching band wins; unmatched items are eligible everywhere. Higher Weight makes banded items win their rarities more often. Player gather contracts also pay a board fee into the fund (see below).
Player contracts (player-tasks.json)
Players post their own jobs from the Players tab, escrowing the reward in a chest-like window.
| Field | Default | Shipped | Description |
|---|---|---|---|
Enabled | true | true | Allow posting |
MaxActivePostsPerPlayer | 3 | 3 | Open + accepted posts per author (0 = unlimited) |
MaxActiveClaimsPerPlayer | 5 | 5 | Player contracts one player may hold at once |
MaxDemand | 64 | 0 | Cap on demand (0 = no cap) |
AllowedKinds | gather, break, kill | kill_entity, gather_item, kill_player | Kinds players may post |
PostCooldownHours | 1 | 1 | Wait between two posts |
ExpireDays | 7 | 0 | Fixed lifetime; used when the player does not pick one |
ExpireDaysMin, ExpireDaysMax | 30, 360 | 1, 1000 | A player-chosen duration is clamped into this range; 0 chosen = no expiry |
RewardSlotCount | 4 | 4 | Escrow slots in the post window |
MaxTitleLength, MaxDescriptionLength | 64, 256 | same | Text limits |
AuthorTaxPercent | 0.1 | 0.1 | Share (0-1) of handed-in items for a gather contract that goes to the fund instead of the author |
A post needs a trackable target, a demand within limits, and a non-empty escrow (at most RewardSlotCount stacks). The author collects handed-in items (gather) or the claimer collects the escrow when the contract is fulfilled.
PvP bounties (pvp.json)
A kill_player contract is created through its own flow (the generic post form refuses that kind).
| Field | Default | Shipped | Description |
|---|---|---|---|
Enabled | true | true | |
RequireKnownProfile | true | true | The target must exist in the player profile database |
MaxActivePerTarget | 1 | 1 | Open PvP bounties on one player (0 = unlimited) |
PerAuthorTargetCooldownHours | 48 | 48 | Same author, same target |
TargetCooldownHours | 4 | 4 | Global wait after a bounty is posted on a target |
PostCooldownHours | 24 | 24 | Between two PvP posts of one author |
ExpireDays | 14 | 0 | Lifetime; clamped to the player-task min/max |
Reputation shop (shop.json)
A shop tab on the board that sells items for the reputation RewardReputationKey from pools.json (the shop does nothing if that key is empty).
{
"Enabled": true,
"PurchaseSound": "game:sounds/player/coin1",
"RestockDays": 500,
"Categories": [
{
"Id": "provisions",
"NameKey": "alegacypatches:bounty-shop-provisions",
"RequiredReputation": 0,
"ColorHex": "#4ADE80",
"Items": [
{ "Id": "prov_bread", "ItemCode": "game:bread-spelt-perfect", "Cost": 20, "StackSize": 4, "MaxPurchases": 5 }
]
}
]
}| Field | Default | Description |
|---|---|---|
Enabled | true | |
PurchaseSound | game:sounds/player/coin1 | Played to the buyer |
RestockDays | 500 | In-game days before each player's purchase counters reset (0 or less = never) |
Categories[].Id | required | Merge key across packs |
Categories[].NameKey | none | Lang key of the tab |
Categories[].RequiredReputation | 0 | Reputation needed to see and buy in the category |
Categories[].ColorHex | none | Accent colour |
Items[].Id | required | Unique; also the purchase counter key |
Items[].ItemCode | required | Item or block given |
Items[].NameKey | item name | Optional name override |
Items[].Cost | 0 | Reputation spent (it is deducted) |
Items[].StackSize | 1 | Stack given per purchase |
Items[].MaxPurchases | -1 | Per player, -1 = unlimited |
Items[].RequiredReputation | 0 | Extra gate on top of the category |
The shipped shop has several categories gated by reputation; see alegacy_patches/assets/alegacypatches/config/bounty/shop.json. Spending is logged as a "Bounty shop" purchase.
Admin commands
/bountydiag requires the controlserver privilege.
| Command | Description |
|---|---|
/bountydiag generate <count> | Dry run on a scratch board (max 500): reports contracts by kind and rarity and any invalid targets. Does not touch the real board |
/bountydiag fund list | Fund stacks with their rarity tags and how many reserves are pledged |
| `/bountydiag fund retag <pattern> <rarity\ | any>` |
Use generate after editing pools: it is the quickest way to see that targets are trackable.
Notes
- Real examples:
alegacy_patches/assets/alegacypatches/config/bounty/(pools with Duat/Hollow Trials encounter targets, four rarities, four seasons, shop). The test mod has a minimalpools.jsoninvsquest.Tests/TestMod/assets/vsquesttestmod/config/bounty/. - Contract names use lang keys such as
alegacyvsquest:bounty-*; the board texts are in the framework lang files. - Accepting a contract registers a runtime quest;
/avq reloadre-registers claimed contracts.