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.
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/haloUMaterialBillboardComponent- 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.
- rarity
UKBVEDroppedItemPool(world subsystem) — preallocatesInitialPoolSize(64) actors, free-listSpawnDrop/ReleaseDrop, firesOnItemPickedUp(Picker, ItemKey, Count)on homing-complete so the game owns auth + inventory add.IKBVEDroppedItemVisualProvider(icon-provider seam) — game implementsGetDroppedItemVisual(ItemKey, FKBVEDroppedItemVisual&)to supply per-itemIconMID/HaloMID/RarityColor; registered viaSetVisualProvider. 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— oneUSTRUCTper item-package proto message (FKBVEGenItem,FKBVEGenFoodInfo,FKBVEGenUseEffect, …), topo-ordered so definitions precede use; scalars/enums/nested/repeatedmap 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:
- 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. - KBVESQLite ⟂ UE SQLiteCore. KBVESQLite is the single sqlite provider for
KBVE code (its own vendored
sqlite3). Do not also link the engine’sSQLiteCorein the same module — duplicatesqlite3_*symbols crash the build/run. Plugins depending on KBVESQLite declaredependency_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.