Skip to content
unreal · npc

NPC database & Mass bridgeKBVENPCDB

A game-agnostic NPC database plus Mass Entity bridge. It loads the shared npcdb artifact into runtime NPC defs, exposes ref lookup, and spawns Mass entities from db data. One runtime module of the KBVERegistry plugin, beside the itemdb loader.

Data stays in MDX

NPC data lives in the shared npcdb MDX and codegens to npcdb-data.json; the plugin owns only the load and Mass bridge. A game calls the spawner to create data-driven NPC entities.

  • Depends on — KBVEYYJson.
  • Sprite — optional KBVENPCSprite render module.
KBVERegistryPlugin
UE 5.4+Engine
Win64 · Linux · MacPlatforms
KBVELicense

What it gives you

Details

NPC database

UKBVENpcDatabase, a GameInstance subsystem, loads Content/Data/npcdb-data.json into FKBVENpcDef records; lookup by ref.

Runtime NPC def

FKBVENpcDef / FKBVENpcStats carry identity, stats, level, type flags, family, faction, abilities, tags, aggro range, and first-strike.

Mass fragment

FKBVENpcFragment / FKBVENpcTag carry the NPC's db identity into the entity world.

Spawner

UKBVENpcSpawner (World subsystem) SpawnNpcEntity(Def, LevelOverride) creates a Mass entity with the NPC fragment and tag; the game adds its own fragments.

Render module

KBVENPCSprite module

The KBVERegistry plugin also ships a KBVENPCSprite render module for billboarded pixel-art NPC sprites in the 3D world (data/Mass stay in the KBVENPCDB module; this only draws):

  • UKBVENpcSpriteDef — UDataAsset: atlas + sprite material + grid (columns = animation frames, rows = view directions front/side/back), fps, world size, pivot.

  • UKBVENpcSpriteRenderSubsystem — SpawnSprite / UpdateSprite / SetSpriteCell / DespawnSprite by handle; one HISM per def, CPU Y-locked camera billboard, atlas cell driven by per-instance custom data (offset/scale UV; right view is the side row mirrored via negative U scale).

  • FKBVENpcSpriteAtlasMapper — builds or fills a UKBVENpcSpriteDef from the generated npcdb sprite atlas (FKBVEGenSpriteAtlas), keyed by the NPC Ref.

The sprite material is authored in-editor — see the module README for the custom-data contract.

Questions

Frequently asked

What does the KBVENPCDB plugin do?

It loads the shared npcdb codegen artifact (npcdb-data.json) into FKBVENpcDef records via the UKBVENpcDatabase subsystem, offers lookup by ref, and spawns Mass entities carrying FKBVENpcFragment from that db data.

Where does NPC data come from?

NPC data stays in the shared npcdb MDX and is codegen'd to npcdb-data.json. The plugin owns only the load and Mass bridge; it does not author NPC data itself.

What is the KBVENPCSprite module?

A render module that draws billboarded pixel-art NPC sprites in the 3D world. UKBVENpcSpriteDef defines the atlas and grid, FKBVENpcSpriteAtlasMapper builds one from an npcdb sprite atlas, and UKBVENpcSpriteRenderSubsystem spawns, updates, and despawns sprite handles with one HISM per def.

Discuss on the forum

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