Protocol buffer schemas shared by KBVE services, games and sites.
Last changed in19476db91on
syntax = "proto3";
package kbve.map.v1;
import "kbve/common/v1/color.proto";
import "kbve/common/v1/extension.proto";
import "kbve/common/v1/math.proto";
import "kbve/map/v1/layout.proto";
import "kbve/type/v1/id.proto";
// World object archetype — gameplay role, not physical shape.
// Use sub_kind for the specific variant (e.g. "oak", "coal", "furnace").
enum WorldObjectType {
WORLD_OBJECT_TYPE_UNSPECIFIED = 0;
// Harvestable / gatherable nodes (tree, rock, flower, mushroom, crystal, water)
WORLD_OBJECT_TYPE_RESOURCE_NODE = 1;
// Loot / storage containers (crate, chest, barrel)
WORLD_OBJECT_TYPE_CONTAINER = 2;
// Crafting stations (workbench, furnace, anvil)
WORLD_OBJECT_TYPE_CRAFTING_STATION = 3;
// Decorative / utility props (statue, pillar, sign, campfire, etc.)
WORLD_OBJECT_TYPE_PROP = 4;
// Light sources — distinct for rendering/lighting system
WORLD_OBJECT_TYPE_LIGHT = 5;
// Navigation / movement
WORLD_OBJECT_TYPE_PORTAL = 6;
WORLD_OBJECT_TYPE_BARRIER = 7;
// Gameplay markers
WORLD_OBJECT_TYPE_NPC_MARKER = 8; // Where an NPC stands
WORLD_OBJECT_TYPE_TRIGGER = 9; // Boss activation, quest zone, cutscene, spawn area
// World structures
WORLD_OBJECT_TYPE_SETTLEMENT = 10; // City / outpost / bazaar (zone-level safe area)
WORLD_OBJECT_TYPE_BUILDING = 11; // Individual structure (inn, tavern, smithy)
WORLD_OBJECT_TYPE_ARENA = 12; // Boss encounter room
WORLD_OBJECT_TYPE_LANDMARK = 13; // Story / lore point of interest
// Escape hatch
WORLD_OBJECT_TYPE_CUSTOM = 100;
}
// Subtype for WORLD_OBJECT_RESOURCE_NODE — what resource the node yields
enum ResourceType {
RESOURCE_TYPE_UNSPECIFIED = 0;
RESOURCE_TYPE_WOOD = 1;
RESOURCE_TYPE_STONE = 2;
RESOURCE_TYPE_FLOWER = 3;
RESOURCE_TYPE_MUSHROOM = 4;
RESOURCE_TYPE_CRYSTAL = 5;
RESOURCE_TYPE_WATER = 6;
RESOURCE_TYPE_ORE = 7; // sub_kind further specifies: coal, iron, gold, etc.
}
// Subtype for WORLD_OBJECT_CONTAINER
enum ContainerType {
CONTAINER_TYPE_UNSPECIFIED = 0;
CONTAINER_TYPE_CRATE = 1;
CONTAINER_TYPE_CHEST = 2;
CONTAINER_TYPE_BARREL = 3;
}
// Subtype for WORLD_OBJECT_CRAFTING_STATION
enum CraftingStationType {
CRAFTING_STATION_TYPE_UNSPECIFIED = 0;
CRAFTING_STATION_TYPE_WORKBENCH = 1;
CRAFTING_STATION_TYPE_FURNACE = 2;
CRAFTING_STATION_TYPE_ANVIL = 3;
}
// How a structure's footprint occupies the grid. RECTANGULAR uses
// footprint_width × footprint_height; HEX_FLOWER claims centre + 6 axial
// neighbours (hex-grid games only); EXPLICIT uses footprint_cells.
enum FootprintShape {
FOOTPRINT_SHAPE_UNSPECIFIED = 0;
FOOTPRINT_SHAPE_RECTANGULAR = 1;
FOOTPRINT_SHAPE_HEX_FLOWER = 2;
FOOTPRINT_SHAPE_EXPLICIT = 3;
}
// Where the placement cost is paid from.
enum CostSource {
COST_SOURCE_UNSPECIFIED = 0;
COST_SOURCE_FACTION_TREASURY = 1; // Shared faction/empire stockpile
COST_SOURCE_OWNER_INVENTORY = 2; // Placing unit's personal inventory
COST_SOURCE_FREE = 3; // No cost (admin / cheats / narrative grant)
}
// Click-interaction kind for landmarks / buildings. Discriminator for
// the per-kind specs below (ShrineSpec / ShopSpec / DungeonSpec /
// QuestGiverSpec). UNSPECIFIED / NONE = inert object, no interaction.
enum InteractionKind {
INTERACTION_KIND_UNSPECIFIED = 0;
INTERACTION_KIND_NONE = 1;
INTERACTION_KIND_SHRINE = 2;
INTERACTION_KIND_SHOP = 3;
INTERACTION_KIND_QUEST_GIVER = 4;
INTERACTION_KIND_DUNGEON = 5;
INTERACTION_KIND_NPC_DIALOG = 6;
}
// Service a structure offers to nearby units. Service seekers read
// ServiceCapability.kind and pick the highest priority provider.
enum ServiceKind {
SERVICE_KIND_UNSPECIFIED = 0;
SERVICE_KIND_FOOD = 1;
SERVICE_KIND_SLEEP = 2;
SERVICE_KIND_HEALING = 3;
SERVICE_KIND_TRAINING = 4; // Skill / XP grinding station
SERVICE_KIND_TELEPORT = 5; // Fast-travel endpoint
SERVICE_KIND_STORAGE = 6; // Shared stockpile accessor
SERVICE_KIND_MERCHANT = 7; // Buy/sell stall
SERVICE_KIND_BANKER = 8; // Personal bank access (OSRS-style)
SERVICE_KIND_WATCH = 9; // A town's lookout: sights its enemies for its guardians
}
// An item cost line — item_ref cross-links to the itemdb's canonical ref.
message IngredientSpec {
string item_ref = 1; // itemdb ref slug (e.g. "timber", "stone-block")
int32 amount = 2;
}
// A service a structure provides to nearby units.
message ServiceCapability {
ServiceKind kind = 1;
int32 priority = 2; // Tie-breaker — higher priority providers win
int32 capacity = 3; // Bed count (SLEEP), slot count (TRAINING), etc.
}
// A tender requirement — the structure needs a qualified worker within
// footprint_radius hexes (or sheltered inside) to function.
message TenderSpec {
string profession_ref = 1; // Skill / profession slug (e.g. "farmer", "lumberjack")
int32 footprint_radius = 2; // Grid distance from root; 0 = root cell only
bool required = 3; // If true, production halts without a tender
}
// A structure that radiates territorial / faction control around itself.
message TerritoryEmitterSpec {
int32 radius = 1; // Grid distance from root cell
}
// One recipe on a production structure — inputs consumed, outputs produced
// on a cycle. pulls_from_treasury=true draws inputs from the faction
// treasury instead of the structure's local ledger.
message ProductionRecipeSpec {
repeated IngredientSpec inputs = 1;
repeated IngredientSpec outputs = 2;
float cycle_secs = 3;
bool pulls_from_treasury = 4;
}
// Automatic surplus export — anything above `floor` ships to the treasury.
message SurplusExportSpec {
string item_ref = 1;
int32 floor = 2;
}
// Timed no-input production (e.g. passive fishing).
message PassiveProductionSpec {
string output_item_ref = 1;
int32 output_amount = 2;
float cycle_secs = 3;
string destination = 4; // "local" or "treasury"
}
// Cooldown-gated ranged attack — universal tower/turret/outpost behaviour.
message RangedAttackSpec {
float cooldown_secs = 1;
float range = 2;
int32 shots_per_volley = 3;
int32 ammo_per_volley_cost = 4;
float damage_per_shot = 5;
float spread_half_angle_rad = 6;
float projectile_speed = 7;
float projectile_lifetime = 8;
string projectile_ref = 9; // itemdb / projectile slug
int32 ammo_capacity = 10; // Local ammo pool size; restocked from stockpile
}
// Cadence-based unit spawner — Goblin Cave, Barracks, dungeon spawner,
// MUD mob den. Consumes cost_per_spawn from a local buffer of size storage_cap.
message PopulationSpawnSpec {
string spawn_entity_ref = 1;
int32 cadence_turns = 2;
optional IngredientSpec cost_per_spawn = 3;
int32 storage_cap = 4;
}
// Periodic hostile raid emitter — Bandit Camp, dungeon boss timer.
message RaidSpec {
int32 cadence_turns = 1;
int32 party_size = 2;
string party_unit_ref = 3;
string target_kind = 4; // "faction_capital" | "nearest_settlement" | "random_wild"
}
// Single step in an upgrade tier progression (Market → Trade House → Guild).
message UpgradeSpec {
string next_def_ref = 1; // ref of the upgraded WorldObjectDef
repeated IngredientSpec costs = 2;
}
// Full tier progression chain for a building.
message UpgradeChainSpec {
repeated UpgradeSpec tiers = 1;
}
// Turn-cadenced shrine grant. Anchored to WorldClock.TurnIndex so the
// shrine acts like passive production rather than a wall-clock cooldown.
// Bonus fires when (`territory_active` AND shrine is inside player
// territory) OR (`king_visit_active` AND the King's root hex == shrine
// hex), gated by `cadence_turns` between grants.
message ShrineSpec {
int32 cadence_turns = 1; // turns between grants (3–4 typical)
int32 reward_coin = 2;
repeated IngredientSpec reward_items = 3;
bool territory_active = 4; // grants while inside player territory
bool king_visit_active = 5; // grants while King is on shrine hex
optional string xp_skill_ref = 6;
optional int32 xp_amount = 7;
optional string buff_ref = 8;
optional float buff_duration_secs = 9;
}
// Shop offer — one tradable item line.
message ShopOffer {
string item_ref = 1; // itemdb ref
int32 buy_price = 2; // coin cost to buy from the shop
optional int32 sell_price = 3; // coin paid if player sells the item TO the shop
optional int32 stock = 4; // -1 = infinite, 0+ = finite
optional int32 restock_seconds = 5; // 0 = no restock
}
// A merchant landmark / building's stock list.
message ShopSpec {
repeated ShopOffer inventory = 1;
}
// Dungeon entry — clicking the landmark transitions to the named scene.
message DungeonSpec {
string scene_ref = 1; // scene slug to load
optional int32 min_player_level = 2;
optional int32 party_size_max = 3;
optional string difficulty = 4; // "normal" | "hard" | "legendary"
optional string entry_quest_ref = 5; // gates entry to a quest progression
}
// Quest-giver landmark — offers one or more quest scrolls on click.
message QuestGiverSpec {
repeated string quest_refs = 1;
optional string greeting_dialogue_ref = 2;
}
// Passive radius effect emitted by a living landmark / building.
// Bonus kind keys are gameplay slugs ("production", "movement_speed",
// "hp_regen", "mana_regen") so new aura types add without touching
// proto. multiplier is applied to the named stat for entities inside
// the radius.
message AuraSpec {
int32 radius = 1;
string bonus_kind = 2;
float multiplier = 3;
}
// A world object definition (archetype / template)
message WorldObjectDef {
kbve.type.v1.Ulid id = 1;
string ref = 2;
string name = 3;
optional string description = 4;
WorldObjectType type = 5;
optional string sub_kind = 6; // Free-form variant (e.g. "coal", "oak", "ruby")
// Typed subtypes — use the one matching the archetype in `type`
optional ResourceType resource_type = 37;
optional ContainerType container_type = 38;
optional CraftingStationType crafting_station_type = 39;
// Visual
optional string model_ref = 7;
optional string icon = 8;
optional float scale = 9; // Visual size multiplier
repeated kbve.common.v1.Color palette = 10; // Color palette for procedural visuals
optional string img = 25; // Image / sprite path
// Interaction
optional bool interactable = 11; // Can player click/interact
optional bool destructible = 12; // Can be destroyed / harvested
optional int32 harvest_time_ms = 14; // Time to harvest in milliseconds
reserved 13, 15, 16, 17;
reserved "loot_item_ref", "tool_required", "skill_level", "skill_type";
// Resource properties (for harvestable objects)
optional int32 harvest_yield = 26; // Amount gathered per harvest action
optional int32 max_amount = 27; // Maximum resource capacity
optional int32 initial_amount = 28; // Starting amount (defaults to max_amount)
// Structure properties (for buildable / placed structures)
optional int32 max_health = 29; // Hit points
optional int32 footprint_width = 30; // Grid cells wide
optional int32 footprint_height = 31; // Grid cells tall
optional bool blocks_placement = 32; // Prevents placing other objects here
optional float construction_time_secs = 33; // Time to build in seconds
repeated BuildCost build_costs = 34; // Resources needed to construct
// Spawn hints (archetype-level defaults)
optional float spawn_weight = 35; // Relative spawn probability (0.0–1.0)
optional int32 spawn_count = 36; // Target count per zone
// Physics
optional float collision_radius = 18;
optional float collision_height = 19;
optional bool blocks_movement = 20;
optional bool occludes_player = 21; // Semi-transparent when between camera and player
// Respawn
optional int32 respawn_time_secs = 22;
optional int32 respawn_variance = 23;
// Extensions
repeated kbve.common.v1.Extension extensions = 24;
// Metadata
optional string credits = 40;
optional bool drafted = 41;
// Placement constraints ────────────────────────────────────────────────
// Biome whitelist — entry values are Biome enum numeric values. Empty =
// any biome (but BIOME_OCEAN is conventionally rejected by placement).
repeated int32 allowed_biomes = 42;
optional bool spawns_fully_built = 43; // Skip construction phase
optional bool requires_in_territory = 44; // Placement restricted to faction territory
optional FootprintShape footprint_shape = 45;
repeated kbve.common.v1.Vec2I footprint_cells = 46; // Used when footprint_shape = EXPLICIT
optional CostSource cost_source = 47;
// Universal capabilities ───────────────────────────────────────────────
repeated ServiceCapability services = 48;
optional TenderSpec tender = 49;
optional TerritoryEmitterSpec territory = 50;
repeated ProductionRecipeSpec recipes = 51;
repeated SurplusExportSpec surplus = 52;
optional PassiveProductionSpec passive_production = 53;
// Gameplay behaviours (universal) ──────────────────────────────────────
optional RangedAttackSpec ranged_attack = 54;
optional PopulationSpawnSpec population_spawn = 55;
optional RaidSpec raid = 56;
optional UpgradeChainSpec upgrade_chain = 57;
// Click interaction (landmark / shrine / shop / dungeon / quest-giver) ─
// `interaction` is the discriminator; populate the matching spec block
// (`shrine` for SHRINE, `shop` for SHOP, etc.). `interaction_cooldown_secs`
// gates reuse on a per-instance basis. `aura` is independent of
// interaction and runs as long as the landmark is alive. `faction`
// identifies the landmark's allegiance ("neutral" | "hostile" |
// "player" | named faction slug) — drives combat/aggression rules.
optional InteractionKind interaction = 58;
optional ShrineSpec shrine = 60;
optional ShopSpec shop = 61;
optional DungeonSpec dungeon = 62;
optional QuestGiverSpec quest_giver = 63;
optional AuraSpec aura = 64;
optional string faction = 65;
// Empire / city / culture wiring (added with the Faction/Settlement layer).
// `faction` (above) stays as a slug for legacy use; `faction_ref` is the
// canonical pointer to a Faction record. `settlement_ref` tags a structure
// as belonging to a Settlement's roster (used by district / siege logic).
optional string faction_ref = 66;
optional string settlement_ref = 67;
optional string district_ref = 68;
optional string culture_ref = 69;
optional string religion_ref = 70;
optional string dialogue_tree_ref = 71; // Upgrade for QuestGiverSpec / NPC dialog
optional float interaction_cooldown_secs = 72;
// Ongoing periodic effects emitted by the placed object (campfire heal ring,
// hazard burn, totem buff). Independent of interaction — active while alive.
repeated PlacedEffect placed_effects = 73;
optional string profession_action_ref = 74;
optional int32 harvest_weight = 75;
// How a walk-in building is put together, for a BUILDING row a game raises
// tile by tile. See layout.proto.
optional BuildingLayout layout = 76;
// A settlement's buildings and open ground, for a SETTLEMENT row.
optional SettlementLayout settlement_layout = 77;
// A kind of bridge, for a BUILDING row whose sub_kind is "bridge".
optional BridgeSpec bridge = 78;
// A kind of place, for a SETTLEMENT row whose sub_kind is "tier".
optional PlaceTier place_tier = 79;
}
// A periodic status effect emitted by a placed world object. `status` is a
// StatusEffectKind slug (e.g. "regen", "burning"); `range` 0 = on-tile only
// (hazard), >=1 = surrounding ring radius (aura). `period_ticks` is the sim
// cadence between applications.
message PlacedEffect {
string status = 1;
optional int32 magnitude = 2;
optional int32 period_ticks = 3;
optional int32 range = 4;
}
// Resource cost for constructing a structure
message BuildCost {
string resource_type = 1; // e.g. "wood", "stone", "metal"
int32 amount = 2;
}
// A placed instance of a world object in a zone
message WorldObjectPlacement {
string object_def_ref = 1; // Reference to WorldObjectDef
optional kbve.common.v1.Vec3F position = 2;
optional kbve.common.v1.Vec2I grid_pos = 3; // For tile-based placement
optional float rotation_y = 4; // Y-axis rotation in degrees
optional float scale_override = 5; // Override object def scale
optional int64 seed = 6; // Per-instance randomization seed
}