feat(bevy_npc): add agnostic NPC plugin with proto-based data model (#7998)

* feat(bevy_npc): add agnostic NPC plugin with proto-based data model

New bevy_npc package mirroring npcdb.proto as the source of truth.
Includes NpcRegistry for O(1) lookup by ULID/slug, ECS components
(NpcId, NpcSlug, NpcCombatStats, NpcBundle), a resolve system that
hydrates NpcSlug entities into full NpcBundle, and optional serde
support for JSON loading.

* refactor(bevy_npc): switch to prost codegen matching bevy_items pattern

Replace hand-written Rust types with prost-generated structs from
npcdb.proto. Adds build.rs (gated behind BUILD_PROTO env var),
NpcDb registry with ProtoNpcId hash keys, and from_bytes/from_json
loaders. Drops ECS components and resolve system — games compose
their own components on top of the registry, same as bevy_items.

Author: h0lybyte

Cargo.lock

@@ -22,6 +22,7 @@ members = [
 	'packages/rust/bevy/bevy_cam',
 	'packages/rust/bevy/bevy_kbve_net',
 	'packages/rust/bevy/bevy_items',
+	'packages/rust/bevy/bevy_npc',
 ]
 
 [profile.dev]

Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bevy_npc"
+authors = ["kbve", "h0lybyte"]
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.94"
+license = "MIT"
+description = "Proto-driven NPC definitions for Bevy games — compiles npcdb.proto into typed Rust structs with a searchable registry."
+homepage = "https://kbve.com/"
+repository = "https://github.com/KBVE/kbve/tree/main/packages/rust/bevy/bevy_npc"
+keywords = ["bevy", "npc", "gamedev", "protobuf", "plugin"]
+categories = ["game-development", "game-engines"]
+
+[dependencies]
+bevy = { version = "0.18", default-features = false, features = [
+    "bevy_state",
+] }
+prost = { version = "0.14", features = ["derive"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+[build-dependencies]
+prost-build = "0.14"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

packages/rust/bevy/bevy_npc/Cargo.toml

@@ -0,0 +1,40 @@
+use std::fs;
+use std::path::PathBuf;
+
+fn main() {
+    if std::env::var("BUILD_PROTO").is_err() {
+        println!("cargo:warning=Skipping protobuf compilation (BUILD_PROTO not set)");
+        return;
+    }
+
+    let manifest_dir = PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap());
+
+    // Walk up to the workspace root (4 levels: bevy_npc → bevy → rust → packages → root)
+    let workspace_root = manifest_dir
+        .ancestors()
+        .nth(4)
+        .expect("Cannot find workspace root");
+    let proto_root = workspace_root.join("packages/data/proto");
+
+    assert!(
+        proto_root.exists(),
+        "Proto root not found at: {}",
+        proto_root.display()
+    );
+
+    let npc_proto = proto_root.join("npc/npcdb.proto");
+    let out_dir = manifest_dir.join("src/proto");
+    fs::create_dir_all(&out_dir).unwrap();
+
+    prost_build::Config::new()
+        .out_dir(&out_dir)
+        .type_attribute(".npc", "#[derive(serde::Serialize, serde::Deserialize)]")
+        .compile_protos(
+            &[npc_proto.to_str().unwrap()],
+            &[
+                proto_root.join("npc").to_str().unwrap(),
+                proto_root.to_str().unwrap(),
+            ],
+        )
+        .expect("Failed to compile npcdb.proto");
+}

packages/rust/bevy/bevy_npc/build.rs

@@ -0,0 +1,52 @@
+//! # bevy_npc
+//!
+//! Proto-driven NPC definitions for Bevy games.
+//!
+//! This crate compiles `npcdb.proto` into typed Rust structs via `prost` and
+//! wraps them in a searchable [`NpcDb`] Bevy resource. It is game-agnostic —
+//! any game can load the same proto NPC registry and query it by slug, ULID,
+//! type flags, rarity, or creature family.
+//!
+//! ## Loading from JSON
+//!
+//! ```rust,ignore
+//! use bevy::prelude::*;
+//! use bevy_npc::{BevyNpcPlugin, NpcDb};
+//!
+//! fn load_npcs(mut commands: Commands) {
+//!     let json = include_str!("path/to/npcdb.json");
+//!     let db = NpcDb::from_json(json).expect("Failed to parse NPC JSON");
+//!     commands.insert_resource(db);
+//! }
+//! ```
+//!
+//! ## Loading from proto binary
+//!
+//! ```rust,ignore
+//! let bytes = include_bytes!("path/to/npcs.binpb");
+//! let db = NpcDb::from_bytes(bytes).expect("Failed to decode NPC registry");
+//! ```
+
+mod proto;
+mod registry;
+
+// Re-export all proto-generated NPC types
+pub use proto::npc::*;
+
+// Re-export registry types
+pub use registry::{NpcDb, ProtoNpcId};
+
+use bevy::prelude::*;
+
+/// Bevy plugin that registers the [`NpcDb`] resource.
+///
+/// The resource is initialized empty. Games should populate it during
+/// startup by calling [`NpcDb::from_json`], [`NpcDb::from_bytes`],
+/// or [`NpcDb::from_proto`] and inserting it via [`Commands::insert_resource`].
+pub struct BevyNpcPlugin;
+
+impl Plugin for BevyNpcPlugin {
+    fn build(&self, app: &mut App) {
+        app.init_resource::<NpcDb>();
+    }
+}

packages/rust/bevy/bevy_npc/src/lib.rs

@@ -0,0 +1,109 @@
+// This file is @generated by prost-build.
+/// ULID - 26 character Crockford Base32 encoded string
+/// Pattern: \[0-9A-HJKMNP-TV-Z\]{26}
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct Ulid {
+    #[prost(string, tag = "1")]
+    pub value: ::prost::alloc::string::String,
+}
+/// GUID - 32 character hex string (no dashes)
+/// Pattern: \[a-f0-9\]{32}
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct Guid {
+    #[prost(string, tag = "1")]
+    pub value: ::prost::alloc::string::String,
+}
+/// UUID - Standard UUID format
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct Uuid {
+    #[prost(string, tag = "1")]
+    pub value: ::prost::alloc::string::String,
+}
+/// 2D Vector (int)
+#[derive(Clone, Copy, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct Vec2i {
+    #[prost(int32, tag = "1")]
+    pub x: i32,
+    #[prost(int32, tag = "2")]
+    pub y: i32,
+}
+/// 2D Vector (float)
+#[derive(Clone, Copy, PartialEq, ::prost::Message)]
+pub struct Vec2f {
+    #[prost(float, tag = "1")]
+    pub x: f32,
+    #[prost(float, tag = "2")]
+    pub y: f32,
+}
+/// 3D Vector
+#[derive(Clone, Copy, PartialEq, ::prost::Message)]
+pub struct Vec3 {
+    #[prost(float, tag = "1")]
+    pub x: f32,
+    #[prost(float, tag = "2")]
+    pub y: f32,
+    #[prost(float, tag = "3")]
+    pub z: f32,
+}
+/// Quaternion rotation
+#[derive(Clone, Copy, PartialEq, ::prost::Message)]
+pub struct Quat {
+    #[prost(float, tag = "1")]
+    pub x: f32,
+    #[prost(float, tag = "2")]
+    pub y: f32,
+    #[prost(float, tag = "3")]
+    pub z: f32,
+    #[prost(float, tag = "4")]
+    pub w: f32,
+}
+/// Transform (position + rotation + scale)
+#[derive(Clone, Copy, PartialEq, ::prost::Message)]
+pub struct Transform {
+    #[prost(message, optional, tag = "1")]
+    pub position: ::core::option::Option<Vec3>,
+    #[prost(message, optional, tag = "2")]
+    pub rotation: ::core::option::Option<Quat>,
+    #[prost(message, optional, tag = "3")]
+    pub scale: ::core::option::Option<Vec3>,
+}
+/// Timestamp wrapper
+#[derive(Clone, Copy, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct Timestamp {
+    #[prost(int64, tag = "1")]
+    pub seconds: i64,
+    #[prost(int32, tag = "2")]
+    pub nanos: i32,
+}
+/// Generic result wrapper
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct Result {
+    #[prost(bool, tag = "1")]
+    pub success: bool,
+    #[prost(string, tag = "2")]
+    pub message: ::prost::alloc::string::String,
+    #[prost(int32, tag = "3")]
+    pub code: i32,
+}
+/// Key-value pair for dynamic properties
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct KeyValue {
+    #[prost(string, tag = "1")]
+    pub key: ::prost::alloc::string::String,
+    #[prost(oneof = "key_value::Value", tags = "2, 3, 4, 5")]
+    pub value: ::core::option::Option<key_value::Value>,
+}
+/// Nested message and enum types in `KeyValue`.
+pub mod key_value {
+    #[derive(Clone, PartialEq, ::prost::Oneof)]
+    pub enum Value {
+        #[prost(string, tag = "2")]
+        StringValue(::prost::alloc::string::String),
+        #[prost(int64, tag = "3")]
+        IntValue(i64),
+        #[prost(double, tag = "4")]
+        FloatValue(f64),
+        #[prost(bool, tag = "5")]
+        BoolValue(bool),
+    }
+}

packages/rust/bevy/bevy_npc/src/proto/kbve.common.rs

@@ -0,0 +1,3 @@
+pub mod npc {
+    include!("npc.rs");
+}