Project Scaffold

Project Scaffold

"The first hour of a new project should be about design, not folder creation."

---

The Problem

You have decided to use PGX. You have 13 systems, each expecting Data Assets for configuration. A typical game project needs:

• A save configuration per domain (inventory, progression, settings, profile)
• Audio channel definitions (master, music, SFX, dialogue, ambient, UI)
• Game flow states and transition rules
• Loading screen contexts
• PSO warm-up configurations
• Data Registry definitions
• Event handler registrations

Creating each of these by hand means: right-click in the Content Browser, select the correct type from a long menu, name it, configure its properties, repeat. For a medium-complexity project, this is 20-40 assets in 10-15 folders.

Nobody enjoys this work. It is mechanical, error-prone, and consumes the time you should be spending on game-specific design decisions. And because it is boring, it is the work most likely to be done carelessly — wrong folder, wrong name, missing configuration, forgotten dependency.

---

The Solution

Project Scaffold automates the entire process through a three-phase UI.

Phase A: Template Selection

Four built-in templates, each designed for a different starting point:

Game Project Quickstart — The full setup. Creates ~25 items: folder structure for all major systems, core Data Assets pre-configured with sensible defaults, Blueprint base classes ready for extension. This is the "I'm starting a new game project and want everything ready" template.

System Data Setup — Configuration only. Creates the Data Asset hierarchy without the Blueprint classes. For teams that already have their own class architecture and just need PGX's data-driven configuration.

Blueprint Architecture — Class hierarchy only. Creates the Blueprint subclasses of PGX's base classes (character, game mode, player controller, HUD) without the system configuration. For teams that want to start with gameplay code and add system configuration later.

Content Pack — A minimal starter for content-focused teams. Creates the folder structure and a few key assets, leaving most configuration for later.

Each template card in the UI shows its name, description, estimated item count, and the categories it covers. You select one and move to configuration.

Phase B: Configuration

The configuration phase presents:

Variable inputs — Templates define variables (project name, target platforms, game genre). These variables are substituted into folder names, asset names, and default property values. Validation runs live: variable format is checked, path validity is verified, duplicates are detected, and dependency chains are validated.

Hierarchy tree — A checkbox tree showing every item the template will create: folders, Data Assets, Blueprint classes. Parent-child propagation means checking a parent checks all its children; unchecking a child does not uncheck the parent (mixed state). This gives you fine-grained control: you can accept the template's full structure or surgically exclude items you don't need.

Validation panel — Real-time feedback on the current configuration. Four validation rules run continuously:

• Variable format (naming conventions, valid characters)
• Path validity (parent directories exist or will be created)
• Duplicate detection (no collisions with existing project assets)
• Dependency checking (if item B depends on item A, unchecking A flags B)

Validation errors are blocking — you cannot proceed to Phase C with unresolved errors. Warnings are advisory.

Phase C: Plan Review and Execution

Before anything is created, you see the complete build plan:

• Topologically sorted operation list (folders first, then Data Assets, then Blueprints — respecting dependency order)
• KPI chips showing total items, estimated operations, and expected asset count
• JSON export of the full plan for archival or review

When you execute, every operation runs inside a single editor transaction. This means:

• Ctrl+Z undoes everything — one undo reverts the entire scaffold operation
• Idempotent execution — running against an existing project skips items that already exist
• JSON audit trail — a log file records exactly what was created, when, and by which template

---

Custom Templates

The four built-in templates cover common starting points, but the template system is extensible. A template is a data structure that defines:

• Variables with types and default values
• A hierarchy of items (folders, Data Assets, Blueprints)
• Dependencies between items
• Default property values (with variable substitution)

---

Architecture Decisions

Why a three-phase UI?

Because the worst outcome is creating the wrong thing. Phase A narrows the scope. Phase B lets you customize within that scope. Phase C lets you review before committing. Each phase gate prevents the most common scaffolding errors: wrong template, wrong configuration, unwanted items.

Why transactional execution?

Because the second-worst outcome is creating half the right thing. If the scaffold fails midway — maybe a path conflict or a permission error — partial state is worse than no state. Running inside a single transaction means either everything succeeds or nothing changes.

Why topological sort?

Because Data Assets can reference other Data Assets. A save configuration might reference audio channels. An event handler might reference game flow states. Creating assets in the wrong order means some references cannot be resolved at creation time. Topological sorting ensures dependencies are created before dependents.

Why JSON audit?

Because scaffolding is a one-time operation that has long-term consequences. If six months later you wonder "why does this folder exist?" or "who created this asset?", the audit trail answers. The JSON log is human-readable and machine-parseable, making it useful for both developers and automation tools.

---

What It Does Not Do

• It does not generate C++ source code. Scaffold creates UE5 assets (Data Assets, Blueprints, directories), not compilation units.
• It does not modify existing assets. If an asset already exists at a target path, it is skipped.
• It does not enforce project structure after creation. You are free to reorganize, rename, or delete scaffolded content.
• It does not replace the Content Browser. For individual asset creation, the Content Browser's PGX integration (58+ entries) remains the right tool.

---

Workflow

1. Open the Scaffold panel from the PGX toolbar
2. Select a template (or build a custom one)
3. Fill in variables, adjust the hierarchy tree, resolve validation issues
4. Review the build plan
5. Execute
6. Verify in the Content Browser
7. If unhappy: Ctrl+Z

Total time: under 2 minutes for a full game project scaffold.

---

Resumen en Espanol

Project Scaffold automatiza la creacion de estructuras de proyecto a traves de una UI de tres fases. Fase A: seleccion entre 4 plantillas integradas (Game Project Quickstart, System Data Setup, Blueprint Architecture, Content Pack). Fase B: configuracion de variables con validacion en tiempo real, arbol de jerarquia con propagacion padre-hijo y deteccion de duplicados/dependencias. Fase C: revision del plan de construccion ordenado topologicamente, exportacion JSON, y ejecucion transaccional. Todo se ejecuta dentro de una sola transaccion del editor — Ctrl+Z deshace la operacion completa. El trail de auditoria JSON registra exactamente que se creo, cuando y con que plantilla. La ejecucion es idempotente: ejecutar contra un proyecto existente salta los items que ya existen. Tiempo total: menos de 2 minutos para un scaffold completo de proyecto de juego.