Colony Buildings: Tooling and Level Maintainance with Python

The Upgradable Buildings System covers the runtime side of things, but building setup and maintenance was still a manual, technical process:

• ❌ Creating a new building meant hand-creating ~13 assets (maps, level instances, PCG data assets), spawning 4 actors, and wiring dozens of references — all in the correct order
• ❌ Validating a building required an engineer or tech artist to open levels, inspect actors, and cross-check PCG parameters one by one
• ❌ Making changes (adding upgrade levels, updating tags, fixing broken references) was error-prone and impossible to batch
• ❌ Artists couldn't self-serve — every new building or iteration required tech art support

With 16 buildings and growing, these manual workflows were becoming the bottleneck that the PCG system was built to eliminate.

---

I built a suite of Python tools running inside Unreal Engine 5 that gave artists and designers full autonomy over the building pipeline — from initial creation to ongoing maintenance and validation.

1. Level Setup Wizard – one-click building creation

A guided Tkinter dialog that takes a building name (from gameplay tags or custom input) and an upgrade count, then automatically:

• Creates the complete folder structure: persistent base level + non-persistent upgrade sub-levels
• Generates Level Instances and PCG Data Assets for each upgrade
• Spawns and configures all required actors (Building Manager actor, PCG volumes, placeholder actors...)
• Wires up every reference and parameter (upgrade maps array, data asset links, PCG graph parameters)
• Displays a detailed execution report with success/error logs and a checklist of remaining manual steps

What used to be a ~30 minute manual process with a high error rate became a single wizard that runs in under a minute.

2. Building Maintenance – safe iterative operations

A second dialog for post-setup operations on existing buildings, including:

• Regenerate Level Instances — recreates missing instances and updates PCG data
• Update PCG Parameters — refreshes all pcg parameters (trigger, gameplay spawner, and BP_LoadUnload configurations)
• Add New Upgrade Level — extends a building with a new upgrade tier, creating all assets and updating all references

The tool auto-detects the selected building from the Content Browser, shows its current state (maps, instances, PCG assets), and validates the selection before executing.

3. Level Validator – automated correctness checks

A validation orchestrator that runs comprehensive checks across every building:

• Base Level: required actors present (no missing, no duplicates), correct mobility settings
• PCG Parameters: glitch trigger configuration, gameplay spawner data, BP_LoadUnload wiring
• Upgrades: level instance existence, actor contents, main building tag, PCG data asset presence
• Index Gaps: detects missing upgrade levels that would break the system

Results are shown in a categorized, collapsible report dialog with errors, warnings, and per-upgrade breakdowns.

4. Main Map Validator – streaming hierarchy audit

A separate validator that ensures all building levels exist in the main game map's streaming hierarchy. It cross-references every discovered base and upgrade level against the editor world, flagging missing or misconfigured streaming levels.

5. Architecture – built for maintainability

The tooling itself was designed as a clean Python package with:

• building_tools — shared package with centralized BuildingConfig, BuildingNaming conventions, and dataclass models (BuildingInfo, OperationResult) used by all tools
• level_validator — modular validators (base level, PCG parameters, level contents, upgrades) orchestrated by a single entry point
• ui_common — shared Tkinter styling and window utilities for consistent UIs that match Unreal's dark theme
• parallel_menus.py — custom Unreal Editor top-level menu registering all tools for one-click access

Everything tied together through the Unreal Python API, integrated directly into the editor's menu bar.

---

• 🎨 Artists create buildings independently
  The Level Setup Wizard replaced what was a 30-minute, error-prone technical task with a guided flow any artist can run.

• ✅ Levels stay correct automatically
  Validators catch configuration drift, missing actors, broken references, and streaming hierarchy issues before they reach QA.

• ⚡ Maintenance is safe and fast
  Adding upgrade tiers, refreshing parameters, or re-tagging buildings is a single menu click — no more hand-editing dozens of actors.

• 🧱 The system scales
  Centralized naming conventions, configurations, and data models mean the tooling adapts to new maps and building types without code changes.

---