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.

FilePurposeMerging across packs
pools.jsonTargets, demand and reward rangesThe first file found sets scalar fields (ranges, reputation key, sound); later files only add targets and fund item bands
rarities.jsonArray of rarity tiersArrays concatenate
seasonal/*.jsonOne season per fileAll collected
player-tasks.jsonPlayer-posted contract limitsLast domain wins
pvp.jsonPlayer-vs-player bountiesLast domain wins
fund.jsonReward fundLast domain wins
shop.jsonReputation shopCategories 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"
  }
]
FieldDefaultDescription
IdrequiredRarity id; referenced from targets, fund tags and /bountydiag
Weight1Present in the shipped files but not used by the generator: every rarity rotates on its own timer
MaxActivePerPlayer1Present in the shipped files but not enforced; the real limit is 2 server contracts per player in total
RefreshHours24Hours between rotations
ContractsPerRotation1Contracts per rotation
ContractsPerRotationRangenone[min,max], rolled each rotation; overrides ContractsPerRotation
RewardMultiplier1.0Scales rewards
DemandMultiplier1.0Scales demand (not applied when the target sets an explicit demand range)
ExpireDays0Lifetime in days (0 = never). If only this is set, it varies by +/-20%
ExpireDaysMin, ExpireDaysMax0Random lifetime range; takes precedence over ExpireDays
ColorHexnoneGUI 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

KindMeaningPool lists
kill_entityKill N creatures (a tag: prefix targets an entity tag)KillTargets / KillTargetEntries
gather_itemHand in N itemsGatherTargets / GatherTargetEntries
break_blockBreak N blocksBlockTargets / BlockTargetEntries
complete_encounterFinish an encounter (demand always 1)CompleteEncounterTargets / EncounterTargetEntries
kill_playerPvP bounty, only from playersnot 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] }
}
FieldDefaultDescription
CoderequiredEntity / item / block code, wildcard allowed
Kindpool's kindOverride the kind, so a target in one list can generate another kind
Weight1Relative pick weight
AllowedRaritiesallRarities this target may appear in
RewardMultiplier1.0Extra multiplier on the reward
Demandpool range[min,max] for this target
DemandByRaritynonePer-rarity range; wins over Demand
TargetNameresolvedLang key or text shown as the target name
ExcludedTargetCodesnoneCodes skipped when a wildcard Code expands (game:log-resin-*)

Scalar fields

FieldDefaultDescription
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
RewardCurrencyKeynoneCurrency key paid out (no currency reward when empty)
RewardCurrencyAmount[5,20]Base currency range
RewardReputationKeynoneReputation 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
RewardItemBonusChance0.25Chance to add a minted item on top of a fund reward
RewardItemEmptyFundChance1.0Chance of a minted item when the fund holds nothing
MaxFundItemRewards1Fund stacks pledged per contract
FundItemBands[]Rarity restriction by item code, see Fund
CompleteSoundsounds/tutorialstepsuccessSound 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.

FieldDefaultDescription
EnabledtrueWith the fund off, currency rewards are minted without limit and no items are drawn
DonationEnabledtrueAllow donations
SkipGenerationWhenEmptyfalseSkip generating a contract when the fund cannot cover its reward
DonationSlotCount8Slots 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.

FieldDefaultShippedDescription
EnabledtruetrueAllow posting
MaxActivePostsPerPlayer33Open + accepted posts per author (0 = unlimited)
MaxActiveClaimsPerPlayer55Player contracts one player may hold at once
MaxDemand640Cap on demand (0 = no cap)
AllowedKindsgather, break, killkill_entity, gather_item, kill_playerKinds players may post
PostCooldownHours11Wait between two posts
ExpireDays70Fixed lifetime; used when the player does not pick one
ExpireDaysMin, ExpireDaysMax30, 3601, 1000A player-chosen duration is clamped into this range; 0 chosen = no expiry
RewardSlotCount44Escrow slots in the post window
MaxTitleLength, MaxDescriptionLength64, 256sameText limits
AuthorTaxPercent0.10.1Share (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).

FieldDefaultShippedDescription
Enabledtruetrue
RequireKnownProfiletruetrueThe target must exist in the player profile database
MaxActivePerTarget11Open PvP bounties on one player (0 = unlimited)
PerAuthorTargetCooldownHours4848Same author, same target
TargetCooldownHours44Global wait after a bounty is posted on a target
PostCooldownHours2424Between two PvP posts of one author
ExpireDays140Lifetime; 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 }
      ]
    }
  ]
}
FieldDefaultDescription
Enabledtrue
PurchaseSoundgame:sounds/player/coin1Played to the buyer
RestockDays500In-game days before each player's purchase counters reset (0 or less = never)
Categories[].IdrequiredMerge key across packs
Categories[].NameKeynoneLang key of the tab
Categories[].RequiredReputation0Reputation needed to see and buy in the category
Categories[].ColorHexnoneAccent colour
Items[].IdrequiredUnique; also the purchase counter key
Items[].ItemCoderequiredItem or block given
Items[].NameKeyitem nameOptional name override
Items[].Cost0Reputation spent (it is deducted)
Items[].StackSize1Stack given per purchase
Items[].MaxPurchases-1Per player, -1 = unlimited
Items[].RequiredReputation0Extra 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.

CommandDescription
/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 listFund 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 minimal pools.json in vsquest.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 reload re-registers claimed contracts.

Press ESC to close