ZOA Loot System

ILootTableDefinition

interface

The read side of an authored table: weighted entries, guaranteed drops, an affix pool, and classification tags.

• LootTableId Id { get; }
• string DisplayName { get; }
• IReadOnlyList<LootEntry> Entries { get; }
• IReadOnlyList<LootEntry> GuaranteedDrops { get; }
• IReadOnlyList<AffixId> AffixPool { get; }
• IReadOnlyList<string> Tags { get; }

ILootTableRegistry

interface

Id-keyed store of table definitions. The roller resolves through it, so a table can be authored, generated, or built in code without the roller caring which.

• void Register(ILootTableDefinition table)
• void Unregister(LootTableId tableId)
• bool TryGet(LootTableId tableId, out ILootTableDefinition table)
• IReadOnlyCollection<ILootTableDefinition> GetAll()
• event Action<ILootTableDefinition> TableRegistered
• event Action<LootTableId> TableUnregistered

ILootRoller

interface

The single rolling entry point for the pool model. One call takes a table id, a roll count, and a luck modifier and returns everything that dropped.

• LootDropResult Roll(LootTableId tableId, int rollCount = 1, float luckModifier = 1.0f)

LootRoller

class

Default roller. Emits guaranteed drops first, then performs rollCount weighted picks, scaling weights by the luck modifier only for entries at Rare or above. Takes an optional seed for determinism.

• LootRoller(ILootTableRegistry tableRegistry, int? seed = null)

ILootContainerService

interface

Owns container registration, availability, opening, and exhaustion. Also the save seam: states can be enumerated and restored wholesale.

• void RegisterContainer(LootContainerDefinition containerDef)
• LootDropResult OpenContainer(LootContainerId containerId, string entityId)
• bool IsContainerAvailable(LootContainerId containerId)
• ContainerState GetContainerState(LootContainerId containerId)
• IReadOnlyCollection<ContainerState> GetAllContainerStates()
• bool RestoreContainerState(ContainerState state)
• event Action<LootContainerId, string> ContainerOpened
• event Action<LootContainerId> ContainerExhausted

ContainerState

class

Per-container runtime state: availability, who opened it last, when, and whether it is exhausted. Handed out as clones so a caller cannot mutate service state by accident.

• LootContainerId ContainerId { get; set; }
• bool IsAvailable { get; set; }
• string LastOpenedBy { get; set; }
• double LastOpenedTime { get; set; }
• bool IsExhausted { get; set; }

LootEntry

class

One row of a table. Item id, selection weight, quantity range, rarity tier, and an optional condition id list.

• string ItemDefinitionId { get; set; }
• float Weight { get; set; }
• int MinQuantity { get; set; }
• int MaxQuantity { get; set; }
• LootRarity Rarity { get; set; }
• List<string> Conditions { get; set; }

LootDropResult

class

What a roll produced: a list of LootDropItem records, each with an item id, a quantity, a rarity, and the affix ids the roller stamped on it.

• List<LootDropItem> Items { get; set; }

LootTableBuilder

class

Fluent construction of a LootTableDefinition in code. The path bootstraps and tests use when there is no asset to author against.

• LootTableBuilder AddEntry(string itemId, float weight, int minQuantity, int maxQuantity, LootRarity rarity = LootRarity.Common)
• LootTableBuilder AddGuaranteedDrop(string itemId, int quantity, LootRarity rarity = LootRarity.Common)
• LootTableBuilder WithAffixPool(List<AffixId> affixIds)
• LootTableBuilder AddTag(string tag)
• LootTableDefinition Build()

AffixDefinition

class

Describes an affix: prefix, suffix, or implicit, with a list of AffixStatMod records, a rarity, tags, and a stackability flag. Data only; this package never applies it.

• AffixId Id { get; set; }
• AffixType AffixType { get; set; }
• List<AffixStatMod> StatModifications { get; set; }
• LootRarity Rarity { get; set; }
• bool IsStackable { get; set; }

LootRarity

enum

Common, Uncommon, Rare, Epic, Legendary, Mythic. The roller only branches on it for the luck modifier, which applies from Rare upward.

LootInteractionMode

enum

DropStyle grants everything silently on open with no panel. BrowseStyle opens an inventory panel and grants only what the player takes.

ILootContentSource

interface

The strategy that decides what a LootInteractable yields. Implementations are pure data adapters: they resolve contents and never publish to the objective or grant buses themselves.

• string InteractableId { get; }
• string DisplayName { get; }
• bool CanOpen { get; }
• LootDropResult Resolve(string collectorEntityId)
• bool TryProvideBrowseInventory(out InventoryComponent inventory)
• void OnBrowseClosed()

LootInteractable

component

The world-placed loot surface. Implements IZOACloseable so the interact key toggles a browse panel open and closed, and exposes replay entry points the network shims drive.

• LootInteractionMode Mode { get; set; }
• ILootContentSource Source { get; }
• bool IsOpen { get; }
• bool TryOpen(GameObject collector)
• bool TryClose()
• void SetContentSource(ILootContentSource source)
• static event Action<LootInteractable, GameObject, LootContainerId, LootDropResult> Granted

LootDelivery

class

The static fan-out every granter raises through. One event, one canonical inventory subscriber, and per-subscriber exception isolation on publish.

• static event Action<Grant> Granted
• static void Raise(in Grant grant)
• readonly struct Grant(string itemDefinitionId, int quantity, GameObject collector, string collectorEntityId, string sourceLabel)

LootGrantInventoryAdapter

component

The single grant-to-inventory router. Subscribes to LootDelivery.Granted and ItemPickup.Granted, resolves the player inventory, and calls TryAddQuantity. One per scene, ensured idempotently.

• static LootGrantInventoryAdapter EnsureInScene(Transform parent = null)

ZOALootSceneInstaller

component

Scene-root bootstrap at execution order -9300. Registers the registry, roller, and container service, registers the authored tables and containers listed on it, and ensures the grant adapter. Unregisters its own instances on destroy.

• void EnsureRegistered()
• ILootTableRegistry TableRegistry { get; }
• ILootRoller Roller { get; }
• ILootContainerService ContainerService { get; }

LootDropper

component

The chance-model counterpart to LootRoller. Resolves independent per-entry drop chances and publishes the result; it never spawns the physical container itself.

• IReadOnlyList<ResolvedDrop> DropFromTable(LootDropTableDefinition table, Vector3 position, string sourceIdOverride = null)
• IReadOnlyList<ResolvedDrop> DropWaveLoot(Vector3 position, int waveNumber)
• IReadOnlyList<ResolvedDrop> DropEnemyLoot(Vector3 position, string agentTypeId)
• void SetRandom(ILootRandom random)
• void SetEventBus(IFoundryEventBus bus)
• event Action<Vector3, string, IReadOnlyList<string>, IReadOnlyList<int>> OnLootResolved

ILootRandom

interface

Random source the dropper consumes. UnityEngineLootRandom is the production default; SeededLootRandom wraps System.Random for deterministic tests.

• float NextValue()
• int NextInt(int minInclusive, int maxInclusive)

LootDroppedEvent

struct

Readonly struct published on the messaging bus when a dropper resolves a non-empty set. Carries the world position, a source id, and parallel arrays of item ids and quantities.

• Vector3 Position
• string SourceId
• string[] ItemDefinitionIds
• int[] Quantities

ILootBrowseUiSurface

interface

The seam between loot and whatever hosts the browse panel. Loot declares the contract and resolves it from the registry; the equipment package's inventory screen registers itself as the implementation, so the dependency never runs the other way.

• void OpenBrowse(InventoryComponent inventory, string title)
• void CloseBrowse(InventoryComponent inventory)
• event Action<InventoryComponent> BrowseClosed
• bool IsBrowseOpen { get; }

BrowsableLootBuilder

class

Turns a concrete item set into a browsable loot pile: ensure a configured inventory on a host, fill it with real GameDatabase items, and wrap it in a BrowseStyle LootInteractable. The path corpse loot and demo piles share.

• static InventoryComponent EnsureLootInventory(GameObject host, InventoryDefinition definitionOverride = null)
• static int PopulateFromDatabase(InventoryComponent inventory, int rolls, int maxStackCap = 3)
• static LootInteractable AttachBrowsableInteractable(...)
• static LootInteractable BuildDatabaseLootPile(...)

RewardContainerProp

component

A lootable container registered as a world prop. Adds Locked gating, id-addressed actuation, optional self-fill on first open, and Depleted bookkeeping on top of a sibling LootInteractable.

• LootInteractable Loot { get; }
• void SetLocked(bool locked)
• override string Kind => "reward_container"

LootTableDefinitionAsset

asset

The pool-model authoring asset, created from Assets > Create > Tools > ZOA > Loot > Loot Table. Holds a stable table id, a roll count, the weighted entry list, the guaranteed list, and an affix id pool. Tags come from DefinitionBase rather than a local field.

• string TableId
• int Rolls
• IReadOnlyList<SerializedLootEntry> Entries
• IReadOnlyList<SerializedLootEntry> GuaranteedDrops
• IReadOnlyList<string> AffixPool
• LootTableDefinition ToRuntimeDefinition()

LootContainerDefinitionAsset

asset

Pairs a container id with a table reference and a lifecycle policy: max items per open, respawn seconds, one-time-only, and an optional key id. Created from Assets > Create > Tools > ZOA > Loot > Loot Container.

• string ContainerId
• LootTableDefinitionAsset Table
• int MaxItems
• float RespawnTimeSeconds
• bool OneTimeOnly
• string RequiresKey
• LootContainerDefinition ToRuntimeDefinition()

LootDropTableDefinition

asset

The chance-model table, created from Assets > Create > ZOA > Gameplay > Loot Drop Table. Each entry carries its own DropChance in zero to one, so several entries can resolve in a single drop. Consumed by LootDropper, never by LootRoller.

• string TableId { get; set; }
• IReadOnlyList<LootDropEntry> Entries
• int EntryCount
• void AddEntry(LootDropEntry entry)
• void ClearEntries()