Skip to content
unreal · item

Item database & inventoryKBVEItemDB

A game-agnostic item database, inventory model, and dropped-item Mass bridge — the data/inventory half to KBVEGameplay's effect half. It loads the shared itemdb artifact into runtime item defs and looks them up by key or ref.

Data half of a pair

Item data stays in the shared itemdb MDX. KBVEItemDB carries it plus the inventory model; KBVEGameplay applies the consumable effects (atlas/icon rendering deferred).

  • Fields — aligned to FKBVEEffectSpec so a game maps item → effect.
  • Persistence — durable local inventory via KBVESQLite.
KBVERegistryPlugin
UE 5.4+Engine
Win64 · Linux · MacPlatforms
KBVELicense

What it gives you

What it ships

Item def

FKBVEItemDef / FKBVEItemFood — runtime item def with identity, type flags, rarity, stacking, prices, tags, and consumable/food effect fields aligned to FKBVEEffectSpec.

Database subsystem

UKBVEItemDatabase (GameInstance subsystem) loads Content/Data/itemdb-data.json through yyjson and the generated proto parser; lookup by key / ref, and PersistCatalogToDb writes the catalog to a read-only SQLite item_def table.

Inventory model

FKBVEInventory / FKBVEInventoryBag / FKBVEInventoryStack plus UKBVEInventoryLibrary (TryAdd / CountItem / FindFirstSlot) — a generic inventory model.

Dropped-item fragment

FKBVEDroppedItemFragment / FKBVEDroppedItemTag — Mass fragment for world-dropped items (key, count, rarity, lifetime, magnet/pickup radius).

Type- + data-driven

Consumables

type_flags classify the consumable — FOOD (0x08) / DRINK (0x10) / POTION (0x20) — and the food: block carries the numbers: heals / restore_mana / restore_energy (instant), regen_per_second + regen_duration (heal-over-time), plus top-level cooldown. A consumer builds an FKBVEEffectSpec from these (instant Restores + Regens, cooldown-gated) and applies it through KBVEGameplay’s UKBVEEffectComponent → IKBVEStatTarget. Type picks the regen target (food → health, drink → mana/stamina); the data fills the magnitudes. An item with a food: block or a food/drink/potion type bit is consumable without needing an explicit consumable: true.

AKBVEDroppedItemActor / UKBVEDroppedItemPool

Dropped items

Pooled, billboarded world-drop system, game-agnostic.

  • AKBVEDroppedItemActor — sphere overlap root + icon/halo UMaterialBillboardComponent
    • rarity UPointLightComponent. Idle bob, then pawn-overlap triggers a homing ease toward the picker; on complete it calls back into the pool. No game types.
  • UKBVEDroppedItemPool (world subsystem) — preallocates InitialPoolSize (64) actors, free-list SpawnDrop / ReleaseDrop, fires OnItemPickedUp(Picker, ItemKey, Count) on homing-complete so the game owns auth + inventory add.
  • IKBVEDroppedItemVisualProvider (icon-provider seam) — game implements GetDroppedItemVisual(ItemKey, FKBVEDroppedItemVisual&) to supply per-item IconMID / HaloMID / RarityColor; registered via SetVisualProvider. Keeps atlas/MID generation game-side while the pool stays generic.

A game wires it once: its item database implements the visual provider, its OnItemPickedUp handler does the authority-gated inventory add, and dropping an item is a single SpawnDrop(ItemKey, Count, Loc).

gen-itemdb-uecpp.mjs

Generated proto types

The item proto (item/itemdb.proto) also feeds a UE C++ emitter, gen-itemdb-uecpp.mjs, whose output is checked in under Public/Generated/:

  • KBVEItemDBProtoTypes.h — one USTRUCT per item-package proto message (FKBVEGenItem, FKBVEGenFoodInfo, FKBVEGenUseEffect, …), topo-ordered so definitions precede use; scalars/enums/nested/repeated map to UE types.
  • KBVEItemDBProtoParse.h — KBVEItemDBProto::Populate(FStruct&, yyjson_val*) per message, reading the camelCase JSON keys the data codegen emits.

So a new proto field regenerates both the struct and its JSON reader — no hand-written parser to drift (the class of bug that silently dropped consumable data). The mirror of the zod generator, emitting UE-native USTRUCTs instead of google::Message (no libprotobuf runtime).

One item type, one parser, one map. UKBVEItemDatabase runs KBVEItemDBProto::Populate(FKBVEGenItem, …) then the shared map KBVEItemMap::FromGen → the curated FKBVEItemDef, which carries IsFood/IsDrink/IsPotion, ConsumeStatuses + ConsumeBuffDuration, and KBVEItem::RarityColor. key + has_img are proto fields, so the proto is the single source of truth with no engine-only injected fields; a new proto field flows through by regenerating, no loader edits. Atlas / icon rendering stays game-side.

FKBVEInventoryStore / UKBVEInventoryStoreSubsystem

Persistence

Durable local inventory via the KBVESQLite plugin — row-per-slot (player_inventory(player_id, bag_ref, slot_idx, item_key, count, durability, flags), WAL), save/load/count/clear by player id, opened at Saved/KBVE/inventory.db.

Two boundaries to respect:

  1. SQLite ⟂ Mass. SQLite is a persistence boundary, not a per-tick datasource: load → seed Mass fragments at spawn/login, mutate fragments on worker threads, flush fragments → SQLite at intervals/logout (game thread / async). A single sqlite3* is not thread-safe; never query it inside the Mass processor loop.
  2. KBVESQLite ⟂ UE SQLiteCore. KBVESQLite is the single sqlite provider for KBVE code (its own vendored sqlite3). Do not also link the engine’s SQLiteCore in the same module — duplicate sqlite3_* symbols crash the build/run. Plugins depending on KBVESQLite declare dependency_plugins: unreal/KBVESQLite.

Questions

Frequently asked

What is the KBVEItemDB plugin?

KBVEItemDB is a game-agnostic runtime module of the KBVERegistry Unreal Engine plugin, providing an item database loader, a generic inventory model, and a dropped-item Mass fragment. It loads the shared itemdb artifact into runtime item defs and looks them up by key or ref.

How does KBVEItemDB relate to KBVEGameplay?

KBVEItemDB is the data and inventory half; KBVEGameplay is the effect half. Item defs carry consumable/food fields aligned to FKBVEEffectSpec, so a consumer builds an effect spec from an item and applies it through KBVEGameplay's UKBVEEffectComponent.

How are consumables modeled in KBVEItemDB?

type_flags classify items as FOOD, DRINK, or POTION, and a food block carries the numbers such as heals, restore_mana, restore_energy, regen_per_second, regen_duration, and cooldown. An item with a food block or a food/drink/potion type bit is consumable without an explicit consumable flag.

Discuss on the forum

Questions, fixes and notes on this page live in the KBVE forum.