mcpField
U
ue5-pcg-building

ue5-pcg-building

github.com/unrealxu创意与媒体53354 次安装9 周前更新
代码仓库

关于 ue5-pcg-building

面向 UE5.6–UE5.8 的 PCG 建筑生成技能，指导开发者设计程序化生成图，涵盖地块筛选、形状语法、运行时调度、输出选择与验证。

主要功能

  1. 01PCG 建筑生成流程
  2. 02地块筛选与变换阶段
  3. 03形状语法模块放置
  4. 04运行时生成与清理
  5. 05静态网格或 Actor 输出
  6. 06调试与验证检查

适用场景

  1. 01规划程序化建筑生成图
  2. 02根据地块输入生成建筑
  3. 03配置有界运行时生成
  4. 04排查语法或生成失败

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/unrealxu/unrealengine5-skills --skill ue5-pcg-building

安装后在 Claude Code 中输入/ue5-pcg-building确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
pcg-building-graph-patterns.md
project-adapter.md
runtime-generation-validation.md
shape-grammar-building-pattern.md

详细介绍

快速开始

  • 定义生成目标：体块塔楼、模块化立面，或基于地块的建筑套件。
  • 定义确定性输入：地块样条线/点、区域标签、风格预设和种子。
  • 定义运行模式：静态烘焙、按需生成，或运行时计划生成。
  • 定义输出模式：优先使用静态网格体实例，仅对交互式/有状态部分生成 Actor。

API 参考点（UE5.6-UE5.8）

  • 运行时触发和半径位于 UPCGComponent：
    • EPCGComponentGenerationTrigger::GenerateAtRuntime
    • bOverrideGenerationRadii、GenerationRadii、SchedulingPolicyClass、SchedulingPolicy
    • GenerateLocal(...)、Cleanup(...)
  • 运行时调度器刷新位于 UPCGSubsystem：
    • UE5.6/UE5.7：RefreshRuntimeGenComponent(...)、RefreshAllRuntimeGenComponents(...)
    • UE5.8：RefreshRuntimeGenExecutionSource(...)、RefreshAllRuntimeGenExecutionSources(...)
    • UE5.8 延迟刷新：DirtyRuntimeGenExecutionSources(...)
    • 通用清理 API：CleanupLocalComponentsImmediate(...)
  • 输出选择参考类：
    • 高数量渲染使用 UPCGStaticMeshSpawnerSettings
    • 交互式/有状态输出使用 UPCGSpawnActorSettings
  • 形状文法参考类：
    • UPCGSubdivisionBaseSettings::GrammarSelection
    • 不要依赖已弃用的文法字段（bGrammarAsAttribute_DEPRECATED、Grammar_DEPRECATED）

图阶段契约

  • 每个阶段都必须明确声明：
    • 输入数据类型（EPCGDataType 或资产源）
    • 核心节点/类（至少两个）
    • 必需参数（种子、标签、范围、半径或风格键）
    • 输出数据类型
    • 调试方法（节点级检查、调试节点，或日志/断言路径）
  • 如果某个阶段无法满足以上五项，则将图设计视为不完整。

工作流

1) 输入

  • 输入数据类型：Actor/样条线/点源。
  • 核心节点/类：UPCGDataFromActorSettings、UPCGGetActorPropertySettings、UPCGCreatePointsSettings。
  • 必需参数：地块标签筛选条件、区域/风格标签、种子来源、源边界。
  • 输出：具有稳定顺序的标准化地块点或样条线数据。
  • 调试方法：在输入阶段后运行 UPCGDebugSettings，并验证点数量和边界。

2) 筛选

  • 输入数据类型：来自输入阶段的点/样条线数据。
  • 核心节点/类：UPCGAttributeFilteringSettings、UPCGDensityFilterSettings、UPCGFilterByTagSettings。
  • 必需参数：坡度范围、排除标签、最小地块面积/宽度、占用约束。
  • 输出：仅包含可建地块/候选项。
  • 调试方法：比较筛选前后的候选项数量，并检查被拒绝项的标签分布。

3) 变换

  • 输入数据类型：经过筛选的可建候选项。
  • 核心节点/类：UPCGCopyPointsSettings、UPCGCreateSplineSettings、UPCGApplyScaleToBoundsSettings。
  • 必需参数：楼层高度、枢轴约定、立面朝向基准、本地轴。
  • 输出：占地变换和逐层变换。
  • 调试方法：检查输出点上的变换轴和楼层索引属性。

4) 文法

  • 输入数据类型：来自变换阶段的分段/样条线/点数据。
  • 核心节点/类：UPCGSubdivideSplineSettings、UPCGSubdivideSegmentSettings、UPCGSelectGrammarSettings。
  • 必需参数：GrammarSelection、模块尺寸限制、基于风格的文法键映射。
  • 输出：解析文法后的模块放置/属性。
  • 调试方法：使用 UPCGPrintGrammarSettings 检查文法解析和令牌验证。
  • 规则：仅使用 GrammarSelection；避免使用已弃用的文法字段。

5）输出

  • 输入数据类型：已解析语法的放置结果。
  • 核心节点/类：UPCGStaticMeshSpawnerSettings、UPCGSpawnActorSettings、UPCGCreateTargetActor。
  • 必需参数：
    • 静态路径：网格选择器、实例打包器、ISM/HISM 策略。
    • Actor 路径：Actor 类、生成属性、状态/交互要求。
  • 输出：已渲染的建筑，以及可选的交互式建筑元素。
  • 调试方法：按图层/标签拆分输出，并验证每层的数量。
  • 默认策略：优先使用 Static Mesh Spawner；仅在需要有状态行为时使用 Spawn Actor。

6）验证

  • 输入数据类型：最终生成结果和运行时生成状态。
  • 核心节点/类：UPCGDebugSettings、UPCGComponent、UPCGSubsystem。
  • 必需参数：预期单元格边界、每次更新的最大生成预算、导航/碰撞预期。
  • 输出：通过/失败信号和修复操作。
  • 调试方法：分阶段检查重叠、对导航的影响、每个单元格的生成时间，以及确定性回放。

约束

  • 除非需要注明特定版本，否则主流程须兼容 UE5.6-UE5.8。
  • 运行时生成必须显式设置：
    • GenerationTrigger = GenerateAtRuntime
    • 显式设置 GenerationRadii（不要依赖隐式默认值）
    • 显式设置 SchedulingPolicyClass，确保调度器行为可预测
  • 数量较大时优先采用 ISM/HISM 风格的输出；避免为每个小部件生成重量级 Actor。
  • 明确指定运行时生成边界，避免在整个世界范围内不受控地重新生成。
  • 预期进行运行时生成时，避免隐式依赖仅限编辑器的数据。
  • 将 World Partition 边界视为运行时范围的硬性约束。

故障处理

  • 症状：没有建筑生成。
    • 定位：输入阶段的输出数量、源边界、地块标签。
    • 修复：验证源 Actor/样条线的导入和地块筛选标签；确认候选集非空。
  • 症状：编辑器预览中有输出，但运行时没有。
    • 定位：GenerationTrigger 和运行时半径/调度设置。
    • 修复：设置 GenerateAtRuntime、半径覆盖值和有效的调度策略。
  • 症状：运行时更新重新生成的区域过大。
    • 定位：运行时半径和生成源移动。
    • 修复：缩小生成/清理半径并收紧源边界。
  • 症状：规则收缩后仍残留过时的生成部件。
    • 定位：清理路径和本地组件生命周期。
    • 修复：触发带有移除组件行为的清理，并在需要时强制执行本地清理。
  • 症状：运行时生成期间出现严重卡顿。
    • 定位：每个单元格的点数、Actor 生成数量、每次更新的工作量。
    • 修复：降低每个单元格的复杂度，限制 Actor 生成数量，并将非交互部件改为静态网格实例。
  • 症状：使用相同种子进行确定性回放时结果不一致。
    • 定位：上游点排序不稳定或随机分支未使用种子。
    • 修复：在随机选择前规范化排序，并将每条随机路径绑定到显式种子输入。
  • 症状：立面语法解析失败或生成空模块。
    • 定位：语法解析日志和模块令牌映射。
    • 修复：验证语法字符串、模块字典和线段尺寸约束。
  • 症状：出现重叠和碰撞问题。
    • 定位：筛选阈值和最终放置约束。
    • 修复：在输出阶段前添加间距/坡度筛选和占用拒绝。
  • 症状：生成建筑周围的导航网格质量下降。
    • 定位：生成输出上的碰撞配置文件和影响导航的标志。
    • 修复：拆分影响导航和不影响导航的输出，并仅在必要时重建导航网格。
  • 症状：修改参数后运行时更改未生效。
    • 定位：调度器刷新流程。
    • 修复：请求刷新已修改组件或所有运行时组件的运行时调度器。

运行时调度器运维

  • 当一个运行时组件的样式、半径或调度输入发生变化时，使用组件刷新。
  • 当许多运行时组件的样式或全局规则发生变化时，使用全局刷新。
  • 当边界缩小时或分区所有权发生变化时，立即进行本地清理。
  • 清理后，仅对受影响的运行时范围触发本地重新生成。

UE5.6-UE5.8 兼容性说明

  • 上述核心运行时触发器和语法 API 在 UE5.6-UE5.8 中保持稳定。
  • UE5.8 新增了非破坏性手动编辑和复杂元数据属性值；跨版本图表应将这些功能视为可选的 UE5.8 能力，而非必需项。
  • 子系统的头文件路径差异：
    • UE5.6 通常使用 Public/PCGSubsystem.h
    • UE5.7/UE5.8 使用 Public/Subsystems/PCGSubsystem.h，并包含 Subsystems/PCGSubsystem.h
  • UE5.8 弃用了以组件命名的调度器刷新调用。在 UE5.8 代码中使用基于 IPCGGraphExecutionSource 的 API；仅在 UE5.6/5.7 分支中保留基于组件的调用。

升级处理

  • 当架构需要自定义 C++ PCG 元素或扩展引擎插件时，升级处理。
  • 当城市规模的生成必须与 World Partition 流送策略集成时，升级处理。
  • 当生成的布局必须与存档/加载或多人游戏权威规则同步时，升级处理。

评论

支持 Markdown