Design Document: Generative Building Blueprints

J. Rogers, SE Ohio

1. Executive Summary

To advance from simple, procedurally generated markers to complex, multi-level structures, the Codex Engine will implement a Blueprint System. A Blueprint is a declarative JSON file that defines the rules and components for a specific type of location (e.g., a "Two-Story Tavern" or "Small Farmstead").

This system moves the generative logic from chaotic randomness to a structured, template-based approach. The TacticalGenerator will consume these blueprints to produce persistent, interconnected battle maps for building interiors and dungeon levels, which are then stored as new nodes in the database.

2. Goals & Requirements

• Structured Generation: Ensure a "Farm" generates with a house, a barn, and a coop, not just a random cluster of rooms.

• Verticality: Support for multi-floor buildings and multi-level dungeons.

• Connectivity: A formal system for "Portals" (stairs, ladders, secret doors) that link different map nodes.

• Persistence: The generated grid data and room layouts must be saved to the database so they are not re-generated on every visit.

• Modularity: The system must be extensible, allowing new building or dungeon types to be added simply by creating new JSON blueprint files, without changing Python code.

• AI Integration: The blueprint should serve as a structural guide for AI content generation, providing context for populating rooms with descriptions, NPCs, and items.

3. Core Concept: The Blueprint File

A Blueprint is a .json file stored in a new data/blueprints/ directory. Each file defines one type of structure. The generator will read these files to understand how to construct a location.

Example File Structure:

code Code




data/

└── blueprints/
    ├── buildings/
    │   ├── tavern_two_story.json
    │   ├── farm_small.json
    │   └── temple.json
    └── dungeons/
        └── crypt_standard.json
  

4. Blueprint JSON Schema

The schema defines the components and rules for the generator.

Example: farm_small.json

code JSON

{

  "id": "farm_small",
  "name": "Small Farmstead",
  "description": "A modest farm with a main house and a few outbuildings.",
  "tags": ["rural", "residential"],
  
  "main_building": {
    "blueprint_id": "house_rural_two_floor",
    "name_template": "{owner}'s Farmhouse"
  },
  
  "outbuildings": [
    {
      "blueprint_id": "barn_small",
      "name_template": "Barn",
      "count": 1,
      "placement_rules": {
        "min_dist_from_main": 5,
        "max_dist_from_main": 15
      }
    },
    {
      "blueprint_id": "coop_simple",
      "name_template": "Chicken Coop",
      "count": 1,
      "placement_rules": {
        "min_dist_from_main": 3,
        "max_dist_from_main": 8
      }
    }
  ]
}
  

Example: house_rural_two_floor.json (A component used by the farm)

code JSON

{

  "id": "house_rural_two_floor",
  "name": "Rural Two-Floor House",
  "tags": ["residential"],

  "layout": {
    "grid_size": {"w": 12, "h": 10},
    "floors": 2,
    "room_rules": [
      { "tag": "kitchen", "floor": 1, "placement_hint": "rear", "min_size": 12 },
      { "tag": "living_area", "floor": 1, "placement_hint": "front", "min_size": 20 },
      { "tag": "bedroom", "floor": 2, "count": 2, "min_size": 9 }
    ],
    "portals": [
      { "type": "stairs", "link": [1, 2], "placement_hint": "central" }
    ]
  }
}
  

5. Generation Workflow (Code Logic)

The TacticalGenerator will be the "Caller" that understands these blueprints.

1. Trigger: The user Shift+Clicks a "Building" marker on the Local Map (e.g., "Miller's Farm"). The marker.metadata contains {"blueprint_id": "farm_small"}.

2. Check Persistence: The TacticalGenerator checks if child nodes (interiors) already exist for this marker. If so, it loads them. If not, it proceeds.

3. Parse Blueprint: The generator loads farm_small.json.

4. Generate Compound Node: It understands this is a compound structure. It will generate a grid layout for the "plot" of land.

5. Place Structures:

   • It recursively calls itself to generate the main_building (house_rural_two_floor.json).

   • It creates a new node in the database for Floor 1 of the house.

   • It runs a partitioning algorithm (e.g., Binary Space Partitioning) on the defined grid_size to create rooms that satisfy the room_rules.

   • It creates another node for Floor 2.

   • It creates portal markers (type: "stairs") on both nodes, storing the target_node_id in their metadata to link them.

   • It then places the outbuildings (barn_small, coop_simple) on the main plot grid, creating separate nodes for their interiors if defined.

6. Save Geometry: The final grid data for each floor/building ([[1,1,0], [0,1,0]]) is saved into the geometry_data field of its corresponding node.

7. Return Entry Node: The generator returns the ID of the primary entry point (Floor 1 of the main house). The MapViewer then loads this node.

6. Database Integration

This system leverages the existing nodes and markers tables effectively.

• Nodes: Each floor of a building and each level of a dungeon becomes a separate node record.

  • parent_node_id links the interior map back to the local map it's on.

  • type will be building_interior or dungeon_level.

  • geometry_data stores the generated grid map.

  • metadata stores level-specific details (e.g., lighting, theme).

• Markers:

  • A marker on the Local Map represents the entire compound (e.g., the Farm).

  • Markers inside an interior map are used for portals (stairs, doors) or interactive objects (chests, levers).

  • Portal markers will have metadata like {"target_node_id": 124, "target_coords": [5, 10]}.

7. User Interaction Flow

1. Creation: On the Local Map, the user Shift+Clicks. The NativeMarkerEditor appears.

2. The user selects "Building". A new dropdown appears, populated by scanning the data/blueprints/buildings/ directory.

3. The user selects "Small Farmstead".

4. The editor saves a new marker with metadata: {"blueprint_id": "farm_small"}.

5. Entry: The user Shift+Clicks the new "Small Farmstead" marker.

6. The system triggers the TacticalGenerator, which executes the workflow described above.

7. The view changes to a new BattleMapStrategy renderer, showing the grid for Floor 1 of the farmhouse.

---