Skip to content
Mirror
Clone

Clone over HTTPS

No sign-in. Pulls work; pushes go upstream to the monorepo.

Download .tar.gz

Protocol buffer schemas shared by KBVE services, games and sites.

Last changed in19476db91on

429 lines16.1 KB
APIRaw
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
}