Loot, Inventory and Crafting
LootItemDefinition
LootItemDefinition (ScriptableObject) is the authoritative item descriptor. Fields:
| Field | Type | Default | Notes |
|---|---|---|---|
itemId | string | β | Matches items.id in the DB. |
displayName | string | β | |
databaseItemType | LootDatabaseItemType | β | Determines inventory filter category. |
rarity | ItemRarity | Common | Common (0), Uncommon (1), Rare (2), Epic (3), Legendary (4), Relic (5). All tiers are supported in the live database. Enum values are stable integers serialized by Unity; never reorder. |
sellValue | int | β | |
crafted | bool | β | DB flag for craft-produced items. |
stackable | bool | true | Whether multiple copies share one inventory slot. |
maxStackSize | int | 99 | Max quantity per slot. Ignored when stackable is false; must be at least 1. |
inventoryIcon | Sprite | β | Required. |
worldVisualPrefab | GameObject | null | Optional. Leave empty for inventory-only items (tickets, materials, consumables). When null, the enemy's assigned network-ready pickup prefab is used as the world representation. When assigned, must be a prefab asset from the Project window. |
LootDatabaseItemType.Consumable is a valid type value. LootPersistenceService maps it to the database string "consumable". The existing inventory filter tabs (All Β· Gear Β· Materials) do not filter by this type.
Equipment fields
Equipment items carry additional fields for paper-doll display and 3D attachment:
| Field | Type | Notes |
|---|---|---|
equipmentSlot | LootEquipmentSlot | Required for equipment. Determines the paper-doll slot and authoritative database slot. |
equippedVisualPrefab | GameObject | Client-side model attached to the equipped player and paper-doll preview. Falls back to worldVisualPrefab when null. |
attachmentProfile | EquipmentAttachmentProfile | Reusable bone and transform defaults for this equipment family (e.g. Two-Handed Sword). Required for all equipment slots except Ring and Trinket. |
overrideAttachmentProfile | bool | Use this item's own bone/position/rotation/scale instead of the profile defaults. |
twoHanded | bool | Reserves both hands. Shown in Loot Forge when the MainHand slot is selected. |
attachmentBoneName | string | Optional exact skeleton transform name. Leave empty to use slot-aware hand/head/body aliases. |
equippedLocalPosition | Vector3 | Item-level position override (used when no profile, or overrideAttachmentProfile). |
equippedLocalEulerAngles | Vector3 | Item-level rotation override. |
equippedLocalScale | Vector3 | Item-level scale override. |
classAttachmentOverrides | EquipmentAttachmentClassOverride[] | Per-class bone/position/rotation/scale overrides applied on top of profile defaults. |
Effective values (used by the runtime) are resolved via EffectiveAttachmentBoneNameForClass(classIndex), EffectiveEquippedLocalPositionForClass, EffectiveEquippedLocalEulerAnglesForClass, and EffectiveEquippedLocalScaleForClass β class overrides take precedence over profile values, which take precedence over item-level fields.
Items are authored in Loot Forge (BCE βΆ Loot Forge). LootPersistenceService syncs stackable and maxStackSize to the items database table on server deployment. See Editor Tooling for Loot Forge documentation.
LootEquipmentSlot
LootEquipmentSlot enum values (defined in LootItemDefinition.cs):
| Value | Notes |
|---|---|
| None | Not equippable. |
| Head | |
| Chest | |
| Legs | |
| Feet | |
| Hands | |
| MainHand | When a main-hand item is equipped, the player's built-in starter weapon is hidden. |
| OffHand | |
| Ring | |
| Trinket | |
| Unspecified | Default; serialized last so existing enum indices are stable. |
Equipment pipeline (server-authoritative)
Equipment state lives in PlayerIdentity.Equipment.cs as a partial class extension of PlayerIdentity.
Server flow:
- On
OnStartServer,PlayerIdentityfetchesGET /api/game/equipment/:characterIdusingCROSSWORLDS_GAME_SERVICE_TOKEN. - The response populates
SyncList<EquippedLootState> equippedLootwith one entry per equipped slot. - Stat bonuses from the server response are applied via
CharacterStats.SetEquipmentStatBonuses(str, agi, int, vit). - Clients can call
CmdRefreshEquipment()to trigger a server-side reload.
Client flow:
InventoryBagUIhandles equip/unequip viaPOST /api/inventory/equip.equippedLootis a MirrorSyncList; changes propagate to all clients automatically.- On each change,
RebuildEquipmentVisuals()destroys and recreates all attached equipment models on the local character. - When a main-hand item is equipped, the player's built-in starter weapon is hidden (
SetBuiltInMainHandVisible(false)).
Attachment resolution (client): ResolveEquipmentAnchor finds the skeleton bone named in attachmentBoneName first. If no match, it falls back to slot-aware aliases (e.g. MainHand β RightHand, Hand_R, mixamorig:RightHand, etc.).
Skinned armor: Prefabs assigned to Head, Chest, Hands, Legs, or Feet slots that contain a SkinnedMeshRenderer are treated as skinned armor. At runtime, the visual is parented to the player's root transform (not a bone anchor) and RemapSkinnedArmorBones rebinds each renderer's bone array to matching transforms on the player skeleton by name (case-insensitive). A warning is logged if a renderer has no bones that match the player skeleton; those renderers are left with their original (likely broken) bone references.
EquipmentAttachmentProfile
EquipmentAttachmentProfile (ScriptableObject) stores reusable attachment defaults for a family of equipment (e.g. all two-handed swords). Fields mirror the item-level attachment fields plus twoHanded. Multiple items can share one profile; per-item or per-class overrides layer on top.
Default profiles for standard slots are managed by LootForgeAttachmentDefaults (editor-only). See Editor Tooling for Loot Forge documentation.
World item pickup flow
WorldItem (Mirror NetworkBehaviour) is spawned by the server when an enemy drops loot. The pickup handshake is server-authoritative with client-confirmed persistence:
- Client presses interact β
CmdPickupon server. - Server validates proximity and
_pickedUpstate. On rejection,TargetResetPickupis sent to the client to clear the pending flag. - On acceptance: server sets
_pickedUp = trueand_pendingPickerConnectionId, then callsTargetOnPickedUpon the picker's client. - Gold items (
itemIdstarting with"gold:") are destroyed immediately afterDestroyAfterRewardDispatch. - Non-gold items start a 12-second server timeout (
ResetTimedOutPickup). If the client does not confirm within 12 seconds,_pickedUpis reset and the item becomes available again. - Client receives
TargetOnPickedUpβ callsInventoryManager.PersistWorldPickup(itemId, qty, callback)β sendsPOST /api/inventory/add-item. The response includesstored(quantity actually added) andrejected(quantity that did not fit). - Client calls
CmdCompleteItemPickup(stored)back on the server. - Server validates that the caller matches
_pendingPickerConnectionId, then: - Reports to the quest system via
QuestLocalRuntime.ServerReportfor the confirmed stored quantity. - Decrements
quantitybystored. - Destroys the
WorldItemifquantityreaches zero; otherwise resets pickup state so another player can pick up the remainder.
Inventory manager
InventoryManager runs on the client (#if UNITY_EDITOR || !UNITY_SERVER).
PersistWorldPickup(itemId, qty, callback) β called when a world item is picked up (step 4 above). POSTs { characterId, itemId, quantity } to /api/inventory/add-item with a 10-second timeout. On success, reloads inventory from the server and refreshes InventoryBagUI. Invokes callback(stored) on completion; passes 0 on auth failure or API error.
- Gold (
itemIdstarting with"gold:") does not call this method β the server handles gold directly. - Stackable items fill existing slots of the same item (unequipped, below
maxStackSize) before creating new slots (enforced server-side). - Non-stackable items always create a new slot (enforced server-side).
Inventory UI (client)
InventoryBagUI is a DontDestroyOnLoad singleton that loads its visuals from the InventoryBagView prefab at Resources/Inventory/InventoryWindow. Run BCE βΆ Setup βΆ Rebuild Inventory UI to regenerate the prefab from the approved art assets if it is missing.
Controls:
- B β toggle open/close (blocked if chat or an input field is focused)
- Escape β close when open
- Click a slot β equip/unequip gear, or use consumables
- Hover a slot β shows
ItemTooltipUInear the cursor - Drag the header β repositions the window (clamped to screen bounds via
InventoryWindowDragHandle) - Drag a slot outside the window β deletes the item. Common-rarity items delete immediately. Items of Uncommon rarity or higher show a confirmation dialog before the request is sent.
Filter tabs: All Β· Gear Β· Materials
- Gear β items whose
databaseItemTypecontains weapon, armor, offhand, ring, trinket, or gear. - Materials β items whose type contains "material".
- All β no filter.
The footer shows the character's current gold from PlayerProgressManager.Local.Gold.
Slot visuals: Filled slots display a rarity-colored background tint and a neon-colored Outline component (rarityOutline) on the slot border. The neon color is derived from the item's rarity color. Empty slots use a plain dark background with no outline.
Automatic refresh: InventoryBagUI.Refresh() is called by PlayerProgressManager.ApplyKillReward() on every kill reward response and by ForgeCraftingPanel after a successful craft. Kill loot is inserted directly into the authoritative inventory by the auth server, so this refresh pulls the updated server snapshot β including any dropped items β without the client adding items locally. If a refresh fetch is already in flight when Refresh() is called, the second refresh is queued and fires immediately after the first completes.
API endpoints:
GET /api/inventory/:characterIdβ fetch current inventory (JWT-gated)POST /api/inventory/equipβ toggle equipped state for a slotPOST /api/inventory/saveβ save full inventory state (used after consuming an item)POST /api/inventory/deleteβ delete a single slot bycharacterIdandslot_index(JWT-gated)POST /api/inventory/add-itemβ add an item to inventory (called by the client after picking up a world item; returns{ success, data: { stored, rejected } })
Consumables
Items recognized by ConsumableEffect.IsConsumable(itemId) are consumed on click rather than equipped. ConsumableEffect.Apply() runs on the local player, quantity decrements by one, the slot is cleared if depleted, and the inventory is saved to the server.
ConsumableEffect.TryGetTooltip(itemId, out string tooltip) returns a player-facing description of the item's effect. This is used by inventory and vendor tooltips.
Known consumable effect types and their behavior:
| Effect type | Behavior |
|---|---|
hp_regen | Restores HP gradually over a duration (DoT-style ticks). Stacks are replaced, not added. |
mana_restore | Restores MP immediately via CharacterStats.RestoreMana. No duration. |
resist_void | Reduces Void damage by a percentage for a duration. |
resist_blast | Reduces Blast damage by a percentage for a duration. |
speed | Increases movement speed by a percentage for a duration. |
damage_amp | Increases damage output by a percentage for a duration. |
Item stats in ConsumableEffect (code-verified 2026-08-20):
| Item ID | Effect | Value | Duration |
|---|---|---|---|
flask_hp_minor | hp_regen | 15 HP | 40 s |
flask_mp_minor | mana_restore | 15 MP | instant |
flask_hp_major | hp_regen | 80 HP | 60 s |
flask_void_resist | resist_void | 25% | 90 s |
kit_iron_warden | resist_blast | 25% | 60 s |
Mining materials
The following ore and ingot items are defined in Loot Forge (Assets/Game/Resources/LootForge/Items/) and are yielded by their corresponding gathering node definitions in Node Forge:
| Ore item ID | Ingot item ID | Node definition |
|---|---|---|
ore_bronze | ingot_bronze | bronze_vein |
ore_hell | ingot_hell | hell_vein |
ore_moon | ingot_moon | moon_vein |
ore_silver | ingot_silver | silver_vein |
ore_steel | ingot_steel | steel_vein |
ore_tin | ingot_tin | tin_vein |
Ores are smelted into ingots at the Forge via the SMELT tab. See Editor Tooling for Node Forge and Loot Forge documentation.
GatheringLootTable
GatheringLootTable (ScriptableObject) is a weighted reward table used by gathering nodes. Create one via BCE βΆ Gathering Loot Table in the Asset Create menu.
| Field | Type | Notes |
|---|---|---|
displayName | string | Label shown in the Gathering HUD when the node uses this table. Default: "Random Resource". |
entries | GatheringLootEntry[] | Weighted entry list. Only entries with a valid LootItemDefinition of type Material and weight > 0 participate in rolls. |
Each GatheringLootEntry carries:
| Field | Type | Notes |
|---|---|---|
item | LootItemDefinition | Must have databaseItemType == Material and a non-empty itemId. |
weight | float | Relative probability weight (β₯ 0). |
minimumQuantity | int | Minimum items awarded per roll (β₯ 1). |
maximumQuantity | int | Maximum items awarded per roll (β₯ minimumQuantity). |
TryRoll(out LootItemDefinition item, out int quantity) selects one eligible entry by weighted random and returns a quantity uniformly drawn from [minimumQuantity, maximumQuantity]. Returns false when no eligible entries exist.
A GatheringLootTable is assigned to a GatheringNodeDefinition via the lootTable field (labeled "Weighted Loot Table" in Node Forge). When assigned, the dedicated server rolls the reward; when absent, the node falls back to the bare itemId + itemQuantity fields.
Server-authoritative gathering award flow
When a networked gathering node grants an award, GatheringNodeNetworkState calls GatheringPersistenceService.Award() server-side. The service:
- Resolves
characterIdfrom the connection'sPlayerIdentity. - POSTs to
POST /api/game/gathering/awardusingCROSSWORLDS_GAME_SERVICE_TOKEN(environment variable, 10-second timeout):
``json { "characterId": <int>, "nodeId": "<string>", "itemId": "<string>", "baseQuantity": <int>, "professionId": "<string>", "xpAmount": <int>, "bonusYieldLevel": <int> } ``
professionId is a string: 0 β "woodcutting", 1 β "fishing", all others β "mining".
- On success, the server sends
TargetAwardResultto the client with the confirmeditem_id,storedquantity,skill_level,skill_xp,leveled_up, and whetherbonus_yieldwas applied.
- The client
AfkGatheringStation.OnAwardRequestCompletedhandler: - Calls
ProfessionManager.ApplyAuthoritativeState()to update the local profession cache from the server-confirmed values. - Reloads inventory via
InventoryManager.LoadInventory(). - Displays a chat message and pulses the Gathering HUD.
The server response carries:
| Field | Type | Notes |
|---|---|---|
success | bool | Whether the award was stored. |
error | string | Human-readable reason on failure. |
data.item_id | string | Item actually stored. |
data.stored | int | Quantity accepted into inventory. |
data.rejected | int | Quantity rejected (inventory full). |
data.bonus_yield | bool | Whether a bonus yield was applied. |
data.skill_level | int | Profession level after the award. |
data.skill_xp | int | Profession XP after the award. |
data.leveled_up | bool | Whether this award caused a level-up. |
Offline/solo mode: When NetworkClient is not active, AfkGatheringStation rolls rewards locally using GatheringLootTable.TryRoll() and posts the item directly to POST /api/inventory/add-item. Bonus yield (20% chance to double quantity) applies only to Common or Uncommon items when the player's profession level is at or above bonusYieldLevel.
Sources: GatheringPersistenceService.cs, GatheringNodeNetworkState.cs, AfkGatheringStation.cs.
Vendors
NetworkVendor (Mirror NetworkBehaviour, INPCInteractable) is a world NPC placed in scenes. When the local player is within VendorProfile.interactionRadius units, the interaction prompt appears; pressing the interact key opens the vendor shop.
VendorProfile (ScriptableObject) defines the vendor's content:
| Field | Type | Notes |
|---|---|---|
vendorId | string | Unique identifier matched on the auth server. |
displayName | string | Shown as the shop title. Default: "Merchant". |
subtitle | string | Optional line shown below the vendor name in the shop window and hover tooltip. Default: empty. |
buysItems | bool | Whether the vendor has a Sell tab. |
interactionRadius | float (0β20) | Detection radius in world units, clamped to β₯ 1 at runtime. |
stock | VendorStockEntry[] | Items the vendor sells. |
Each VendorStockEntry references a LootItemDefinition item and carries a buyPrice (minimum 1 gold).
Buy flow: client calls RequestBuy(itemId, 1) β CmdBuy on server validates proximity and request β VendorPersistenceService POSTs { characterId, vendorId, itemId, quantity } to /api/game/vendors/buy β result returned to client via TargetVendorResult.
Sell flow: client calls RequestSell(slotIndex, 1) β CmdSell on server validates that buysItems is true, the slot exists (index 0β23), is unequipped, the item has sellValue > 0, and the player is within proximity β POSTs { characterId, vendorId, slotIndex, quantity } to /api/game/vendors/sell.
After a transaction: InventoryManager.LoadInventory() reloads from the server, InventoryBagUI.Refresh() and PlayerProgressManager.Local.Refresh() are called.
Server sync: VendorPersistenceService.SyncProfile() is called OnStartServer for each NetworkVendor. It POSTs { vendorId, displayName, buysItems, stock } to /api/game/vendors/definitions using the CROSSWORLDS_GAME_SERVICE_TOKEN server environment variable, retrying up to 3 times on failure (3-second gap between retries, after an initial 2-second delay to allow Loot Forge item rows to be written first).
VendorShopUI is a client-side DontDestroyOnLoad singleton created on first use. It provides Buy and Sell tabs; the shop title shows the vendor's displayName with the subtitle displayed below it when non-empty. The Escape key closes the shop window.
VendorHoverUI shows the vendor name and subtitle (when non-empty) in a screen-space overlay when the player's cursor is over a vendor. The subtitle renders in smaller gold-tinted text below the name.
Sources: NetworkVendor.cs, VendorShopUI.cs, VendorProfile.cs, VendorPersistenceService.cs.
Crafting
Crafting takes place at the Forge (prefab_forge) in the Hub scene.
ForgeNPC
ForgeNPC (Assets/Game/Networking/ForgeNPC.cs) is a purely client-side MonoBehaviour placed on the prefab_forge GameObject. It is not a Mirror NetworkBehaviour; crafting API calls happen inside ForgeCraftingPanel.
Key fields:
professionIdβ the profession used for this forge (default 2 = Mining).interactRangeβ proximity radius to show the E-prompt (default 3.5 units).promptHeightβ height of the world-space billboard prompt above the forge (default 3 units).
When the local player (PlayerIdentity.Local) enters interactRange, a world-space "[E] Craft" billboard appears. Pressing E while no TMP_InputField is focused opens ForgeCraftingPanel. The billboard is parented independently of the forge model hierarchy to avoid scale inheritance.
ForgeCraftingPanel
ForgeCraftingPanel (Assets/Game/UI/ForgeCraftingPanel.cs) is the crafting UI. It auto-instantiates from Resources/Forge/ForgeWindow.prefab at scene load (RuntimeInitializeOnLoadMethod(AfterSceneLoad)) and persists across scenes (DontDestroyOnLoad). ForgeCraftingPanel.Instance provides global access.
On Open(), the panel moves to the front of the canvas, restores any saved drag position, and fetches the character's available recipes from the server using AuthManager.CharacterId and AuthManager.Token. The panel has two tabs:
- SMELT β raw gathering materials β refined materials (e.g. ore β ingot, log β plank).
- CRAFT β refined materials β gear and consumables.
After a successful craft, the inventory is reloaded (InventoryManager.LoadInventory()) and InventoryBagUI.Refresh() is called. If the crafting action caused the profession to level up, the new level is shown in the status bar.
The panel is draggable (via ForgeWindowDragHandle) and can be closed with the Γ button or the Escape key (while no input field is focused).
Rebuild the prefab if missing: BCE βΆ Setup βΆ Rebuild Forge Crafting UI.
RecipeRowUI
RecipeRowUI (Assets/Game/UI/RecipeRowUI.cs) renders one server-provided recipe row. Each row shows:
- Rarity badge β color-coded strip on the left edge.
- Item icon β sourced from
LootItemCatalog. - Name and required level (dimmed when the recipe is locked).
- Ingredients β listed as
quantityΓ name; ingredients the player lacks are shown in red. - Craft time.
- CRAFT button β disabled (and row partially transparent) when the recipe is locked or any ingredient is insufficient.
Hovering a row triggers ItemTooltipUI for the result item.
Recipes and ingredients database
Recipes and ingredients are stored in the recipes and recipe_ingredients database tables. See Database Schema.
Related: Database Schema Β· Editor Tooling Β· Enemies, Waves & Bosses Β· Heroes and Classes