# PCG-01｜Aipcg：让 Agent 学习已有项目

资料核验：2026-10-10。分析对象是 AIPCG 编辑器插件及相关学习资料。仓库 HEAD `3a30b79706e99fbb0dc92aeab8f1eceb68406f15`，工作区有未提交变化；实际分析文件以 [副本哈希清单](<../../sources.html#ref-95b2ead5e34c0e>) 定位，不能只用 HEAD 重建全部行为。

![Aipcg 控制与数据架构图](<../../图表/PCG-01_架构.svg>)

## 1. 项目目标与交付对象

项目把自然语言场景需求转成结构化场景、布局、几何与建筑数据，再导入 Unreal Editor，通过 PCG（程序化内容生成）图生成可编辑地图。PCG 图负责下游场景构建；上游 Python 已经选择建筑位置、朝向和资产。

最终交付可能包括运行目录、JSON、分类图、CSV、DataTable、地图与质量报告。分类 PNG 是确定性程序栅格化的中间数据，不是当前链路里图像生成模型的直接产物。地图存在也不代表视觉效果和所有约束已经验收。

## 2. 演进路线与版本边界

用户资料描述过 Houdini 与 UE 协同、Python／PCG、模型 API 与 3D 生成、Codex 单 Agent 等路线。这些属于 Aipcg 自身演进，不能混成同一当前实现，也不能和学习资料 V2.0 的版本号等同。

本章当前调用链以复制的 C++／Python 文件为依据；运行案例以 2026-10-02 历史目录为依据。当前 policy 的布局尝试上限为 2，历史 manifest 记录为 5；必须在各自运行背景下理解。视觉审计在当前复制 policy 中为关闭状态，不能把存在相关代码称为默认启用。

## 3. 目录职责地图

| 入口 | 职责 | 先回答的问题 |
|---|---|---|
| `AIPCGEditorModule.cpp` | 编辑器按钮、进程与结果轮询 | 谁启动任务，何时认为地图就绪？ |
| `demo02_image_pipeline/run.py` | 场景与布局生成、阶段编排 | 请求、运行目录和状态怎样交接？ |
| `world.py`／`coordinates.py` | 世界数据与单位转换 | 像素与厘米如何对应？ |
| `raster.py`／`natural_geometry.py` | 分类图与几何处理 | 哪些结果由代码计算？ |
| `village_layout_experiment.py` | 建筑放置与约束 | 怎样使用真实包围盒？ |
| `plan_demo02_buildings_texture.py` | 规划、审计与导出适配 | CSV 与 plan 是否一致？ |
| `import_demo02_unreal.py` | DataTable、PCG、地图导入保存 | 导入状态能证明什么？ |

副本入口：[代码学习总览](<../../sources.html#ref-2655b311ab2b9c>)、[源码目录](<../../sources.html#ref-e4e51c90dbc28d>)、[Agent 项目导读](<../../模板/Aipcg项目导读.md>)。原始学习资料是导航，具体函数与配置仍要打开代码确认。

## 4. 沿一条生成链路阅读

编辑器发起任务，外部 Python 建立运行目录并更新进度；Codex 生成受结构约束的 scene／layout；程序计算道路、水域、地块和建筑放置；资产元数据提供真实尺寸与引用；CSV 交给 Unreal DataTable；Terrain、Buildings、Vegetation 图构建场景；导入完成后写出状态，C++ 轮询发现 `ue_map_ready`。

数据流与控制流要分开看。`scene.json` 和 `layout.json` 是内容描述；进度与结果文件控制用户界面状态。导入失败可能已有部分资产写入，并不自动回滚整次任务。`save_assets([])` 等保存行为还需要结合 UE 实际语义检查，学习任务没有调用引擎修改资产。

## 5. 关键数据格式与坐标

| 数据 | 下游用途 | 关键检查 |
|---|---|---|
| scene／layout JSON | 场景语义与空间计划 | schema、数量、类型、规则 |
| 分类 PNG | 地形与空间类别 | 尺寸、编码、像素方向 |
| 资产 CSV | 网格与包围盒 | 真实资产路径、尺寸、轴心 |
| buildings plan／CSV | 建筑实例 | 标识、厘米、Yaw、Scale、一致性 |
| DataTable／PCG 图 | 引擎场景 | 字段绑定、图依赖、实际执行 |
| manifest／audit | 定位与验收 | 版本、参数、检查范围、失败 |

代表设置为 1024×1024 图片对应 20000 cm 宽世界，即每像素 `19.53125 cm`。当前坐标函数使用图片向下与世界 Y 增大一致的约定：`X=(PixelX−512)×19.53125`，`Y=(PixelY−512)×19.53125`；函数也支持另一方向，必须记录参数。

本次实际调用复制的纯坐标函数，`(768,256)` 得到 `(5000,−5000) cm`，逆变换还原原像素。建筑 Pixel 坐标代表包围盒中心，World 坐标代表模型轴心，两者还需旋转和中心偏移，细节见 PCG-02。

## 6. 模型、算法、引擎的分工

模型提出结构化场景与布局，确定性代码实现可检查的空间规则，引擎提供真实资产事实并构建场景。算法包括道路／河流曲线平滑、闭合轮廓平滑、扫描线填充、连通分组、深度传播、候选选择和碰撞审计。算法名称不能替代实现目的；例如碰撞检查要说明参与比较的是哪个空间范围、是否包含间距。

建筑算法根据资产包围盒计算旋转后的占用，位置不是只根据视觉图像中心决定。容量 witness 说明某地块能容纳至少若干候选，不保证最终每块都放置该数量。地形 PCG 生成动态网格，建筑 PCG 实例化规划结果，植被图按自己的采样与噪声规则工作。

## 7. 状态、依赖与验证

完成状态至少区分模型输出成功、规划导出成功、引擎导入与保存成功、几何验收、视觉验收。单项报告通过不能替代后续项。依赖包括 Codex CLI、项目提示和 schema、Python 工具、UE 插件、真实资产 DataTable、模板地图和 PCG 子图。

因此复制 Python 文件可以学习算法，却不能宣称获得完整可运行 UE 工程。本章副本用于离线分析，不包含所有二进制资产与 UE 环境。历史只读核验中出现过资产读取成功但 commandlet 退出码异常，也应保留为结果边界。

## 8. 历史结果与本次检查

历史 buildings.csv 有 23 行；历史地图报告记载 Buildings 23 个静态网格实例、Terrain 6 个动态网格组件、Vegetation 631 个静态网格实例，并标记地图核验通过。这些数字描述该历史报告，不是本次重新启动 UE 的结果。

本次 [数据核对](<../../检查记录/Aipcg数据核对.json>) 复查坐标、plan／CSV 数值与资产引用，23 行均一致。已有产物从旧文档路径移动到 `Output/test`，登记后的副本入口是 [历史运行](<../../sources.html#ref-38216c9572f8ae>)。图节点资料见 [PCG 参数快照](<../../sources.html#ref-d542173626a72b>)。

## 练习与验收

选择“解释一个建筑的位置”任务，读入口、坐标、资产包围盒、plan、CSV 与报告。追踪一个 `AssetKey`，解释图片中心怎样变成 WorldX／WorldY；指出地图实例统计来自哪次运行。提交项目导读和字段追踪表。每条架构连线都应能返回具体调用代码或数据交接证据。

![项目学习思维导图](<../../图表/PCG-01_思维导图.svg>)

配套 18 页演示稿。源码与运行状态为本地只读分析；没有执行在线生成、UE 导入或地图保存。