Loot and random stats

Module PulseInventory. Loot tables say what a chest, an enemy or a quest reward gives; random stats make every dropped sword a little different. Both are deterministic for a seed, so a server can roll once and everybody sees the same result, and tests can check exact outcomes.

Loot tables

A Pulse Loot Table data asset (UPulseLootTable, Primary Asset Type PulseLootTable):

Field Meaning
Entries Items (Item) or other tables (SubTable) with MinCount / MaxCount and a Weight.
bAlways on an entry Always drops, in addition to the weighted rolls (keys, gold).
Conditions on an entry Pulse conditions (see Conditions, costs and rewards): Context Tags (tag query on the tags of the roll), Loot Level (range of Level), Has Item or a quest of the player, … Rolls run on the authority, so only Passed counts.
MinRolls / MaxRolls Number of weighted picks over the other entries.
NothingWeight Weight of “nothing” in every pick.
bAllowDuplicates Whether an entry can be picked twice in the same roll.

Sub tables can nest; a table that would roll itself again (a cycle) is skipped, and nesting stops after 8 levels. A roll with the adjustments of its world logs one warning per roll then; rolls with given adjustments (the simulation) and the exact chances stay silent. Validate Assets reports empty entries and tables that use themselves.

FPulseLootContext context;
context.Level = EnemyLevel;
context.Tags.AddTag(DifficultyTag);
context.Player = Killer;    // conditions about the player read it, may be null
const TArray<FPulseLootDrop> drops = Pulse::Inventory::Loot::RollTable(Table, Seed, context);
Pulse::Inventory::Loot::SpawnLoot(Enemy, drops, Enemy->GetActorTransform(), 80.f, true);

The conditions of an entry get the context of the roll (FPulseLootContext::MakeConditionContext): Player, Tags and Source of the roll, and the loot context itself as extra data (Loot Level reads Level from there).

Blueprint: Roll Loot Table, Give Loot (into an inventory, returns what did not fit) and Spawn Loot (as pickups through the pickup subsystem, spread on a circle). Give and spawn run on the authority. Spawn Loot places each drop completely or not at all: a drop whose pickup cannot be created changes no other pickup.

Tuning: the tuning knob Pulse.Tuning.Inventory.LootAmount of PulseFoundation multiplies the count of every entry a table gives (rounded, at least 1), after the roll, so the same seed picks the same entries on any difficulty. The tags of the loot context are the tags of the knob, its player and source are the player and source; a roll without a player or source in a world is not tuned.

Chances, simulation and adjustments

Loot/PulseLootSimulation.h answers “what does this table give?” without a world, for the loot workshop, specs and balancing tools. Everything is plain value types and deterministic for a seed.

  • Exact chances: Pulse::Inventory::Loot::ComputeChances(Table, Context, Adjustments) computes (does not sample) every item the table can give, through all sub tables. Chance is the chance that the item drops at least once in one roll of the table, ExpectedCount the average count per roll, MinCount / MaxCount the counts of one entry; EmptyChance is the chance of a roll that gives nothing. With one weighted roll, no guaranteed entries and different items the chances and the empty chance add up to 1. Conditions of the entries are checked with the context, cycles and the depth of 8 count as in a roll. bExact is false when a table was too large to count exactly (more than 16 weighted entries without duplicates, many rolls over many such entries, or a count range above 65536): that part is estimated.
  • Dice simulation: Simulate(Table, Context, Adjustments, Rolls = 1000, Seed = 0) rolls the table many times and gives per item the rolls it dropped in (Hits, HitRate) and its smallest, average and largest count in those rolls, plus EmptyRolls and EmptyRate. Roll n is RollTable(Table, GetSimulationSeed(Seed, n), Context, Adjustments), the function the game rolls with, so a simulation never drifts from real rolls and one roll can be repeated.
  • Adjustments: FPulseLootAdjustments is collected once before rolling: tables and items used instead of others (TableReplacements, ItemReplacements), factors of the weights of item entries by item tag (WeightFactors, child tags count, sub table entries and guaranteed entries keep their weight) and the factor of the counts (QuantityFactor, rounded, at least 1). CollectAdjustments(TuningData, Table, Context) fills it from tuning data: the knob Pulse.Tuning.Inventory.LootAmount, the Loot Weight adjustments (FPulseAdjustment_LootWeight: item tag and factor, for every table) and the Swap Asset adjustments of PulseFoundation for every table and item the table reaches (resolved with Pulse::Adjustments::Resolve).

A roll without adjustments (RollTable(Table, Seed, Context), Roll Loot Table) collects the adjustments of its world (CollectAdjustments(WorldContext, Table, Context)), so swaps and loot weights of a difficulty, an event or an area apply to every chest, enemy and harvest. Pass the adjustments yourself to roll many times with the same ones.

Preview per level: build one FPulseTuningData per difficulty level (a source with the preset of the level), call CollectAdjustments for each and compare the chances of the levels.

const FPulseLootAdjustments hard = Pulse::Inventory::Loot::CollectAdjustments(HardData, Table, Context);
const FPulseLootChances chances = Pulse::Inventory::Loot::ComputeChances(Table, Context, hard);
const FPulseLootSimulation simulation = Pulse::Inventory::Loot::Simulate(Table, Context, hard, 1000, 42);

Loot tables in the editor

Loot tables open in the config workshop of the Pulse Editor Kit (tree and graph of the entries, details, validation, notes), with a preview of PulseGameplay on the right. The buttons of the difficulty levels of Pulse Difficulty (Base is the table as it is) switch to a level: its adjustments are collected with CollectAdjustments without a world, the same way a roll in a game collects them. Source level sets Level of the loot context for the conditions Loot Level; conditions about a player do not pass in the preview.

Loot (tab of a table):

  • Entries and chances: every entry of the table and, indented below a sub table, its entries, through every sub table as a roll walks them (a cycle or a table deeper than 8 is marked and not followed). An item row shows the counts after the quantity factor, the weight and the chance of one weighted pick, the chance that the item drops in one roll of its own table and in one roll of the whole table. A swapped item or table shows as “original → replacement” in the warning color, an entry whose conditions do not pass is faint.
  • Chances per level: a column per level next to Base, a row per item with its chance per roll and its average count, and the chance of an empty roll; cells that differ from Base are marked. The line below it is the knob Pulse.Tuning.Inventory.LootAmount on every level.
  • Adjustments of the level (with a level picked): what the level changes compared with Base, each value before (faint) and after (bright): the count factor, the weight factor of each item tag (Loot Weight), every table and item swap; below each Swap Asset the before and after panel of PulseFoundation.
  • Where used: the loot tables that roll the table as a sub table, and other assets that name it, with a button that opens them. Items list the loot tables that drop them the same way.

Dice Simulation (the live test tab): rolls (1000 by default), seed and level, then Simulate rolls the table with Simulate (roll n is RollTable with GetSimulationSeed(Seed, n)). The table lists per item the hits, the hit rate, the exact chance, the difference (marked beyond three standard deviations of the hit rate, at least one percent) and the count of the rolls it dropped in, smallest to largest with the average (“5-10, Ø 7.45”); the last row is the empty rolls against the exact empty chance. A table wider than the tab scrolls sideways.

Loot entries have a card wherever they show: the title is the item or “Table ", the summary "1-3 x Iron Ore, weight 5" (or "always"), the tree of the workshop and the Stack view show the chance of one pick. The Effect panel of a **Loot Weight** adjustment lists the tables with items of its tag.

The rules behind the preview are pure functions of the editor module (Pulse::Inventory::Loot::Editor: GetPickChance, BuildTree, CompareLevels, CompareSimulation, RunSimulation, DescribeChanges, FindLevelSwaps, FindUsages, FindTablesWithItemTag). Spec: PulseGameplay.Editor.LootWorkshop.

Random stats

  • Put Random Stats (FPulseItemTrait_RandomStats) on an item definition: possible stats (Pulse.Stat.* tag of the stat register, range, weight, whole numbers), how many (MinStats / MaxStats) and optional rarity tiers (Pulse.Rarity.*, weight, extra stats, value multiplier).
  • When the item is created by a loot roll (bRollRandomStats on the entry) or by Pulse::Inventory::RollInstanceTraits, it gets the instance trait Rolled Stats (FPulseItemTrait_RolledStats): the rarity and the rolled values. Items with random stats drop one by one, every item with its own stats.
  • FPulseItemTrait_RolledStats::GetStat(Tag) sums a stat (child tags included).

The inventory does not know what a stat does. Other modules map stat tags to effects, for example PulseInventoryEffects to attribute bonuses while equipped and PulseCombatInventory to damage modifiers.

Cheats

Command Does
PulseLootRoll <table> [seed] [drop] Rolls a table, prints the items with their stats and puts them into the inventory (or drops them in front of the player)

PulseGameplay plugin documentation.

This site uses Just the Docs, a documentation theme for Jekyll.