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.

View sourceConsumablesDropped itemsPersistence

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.
KBVEItemDBPlugin
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 via UE Json; lookup by key / ref. Mirrors the chuckItemDB pattern.

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 — extracted from chuck’s chuckDroppedItemActor / chuckDroppedItemPool and made 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.

The chuck-specific Cast<AchuckCoreCharacter> + ServerAddItemByKey pickup path becomes: provider feeds visuals, OnItemPickedUp delegate feeds the inventory.

chuck now consumes this directly — UchuckItemDB implements IKBVEDroppedItemVisualProvider (maps key → atlas icon MID + rarity halo) and hosts the OnItemPickedUp handler (HandleDroppedItemPickedUp → authority-gated ServerAddItemByKey); AchuckCoreCharacter::BeginPlay registers the DB as the pool’s provider + pickup sink once, and ServerDropSlot just calls SpawnDrop(ItemKey, Count, Loc). chuck’s old chuckDroppedItemActor / chuckDroppedItemPool are deleted.

gen-itemdb-uecpp.mjs

Generated proto types

The same itemdb.binpb descriptor that feeds the zod generator also feeds a UE C++ emitter (packages/data/codegen/gen-itemdb-uecpp.mjs, run via nx run astro-kbve:sync:itemdb-uecpp). It writes, into 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. Both loaders run KBVEItemDBProto::Populate(FKBVEGenItem, …) then the single shared map KBVEItemMap::FromGen → the curated FKBVEItemDef:

  • plugin UKBVEItemDatabase and chuck UchuckItemDB both store + return FKBVEItemDef (chuck retired its FchuckItemDef / FchuckItemFood / EchuckItemRarity / chuckItem::RarityColor — deleted chuckItemTypes.h).
  • FKBVEItemDef absorbed chuck’s needs: IsFood/IsDrink/IsPotion, ConsumeStatuses
    • ConsumeBuffDuration, and KBVEItem::RarityColor. chuck consumers (consume, inventory slot, item info, drop visuals) read it directly.
  • key + has_img are now proto fields (itemdb.proto) so the generated type is a true superset — the proto is the single source of truth, no engine-only injected fields. The old hand-written FJsonObject / yyjson key-reads in both loaders are gone; a new proto field flows everywhere by regenerating, no loader edits.

UchuckItemDB still owns chuck’s atlas / icon-MID / rarity-halo rendering on top of the shared FKBVEItemDef.

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: packages/unreal/KBVESQLite.

Questions

Frequently asked

What is the KBVEItemDB plugin?

KBVEItemDB is a game-agnostic 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.

Elsewhere

Related

KBVEGameplayThe effect half — applies the consumable effects an item def describes.KBVESQLiteThe SQLite provider KBVEItemDB uses for durable inventory persistence.KBVEZstdCompression plugin in the same Unreal plugin family.