CityEngine建筑规则库实战：从CGA规则到批量生成与团队资产

简介Cityengine建筑规则库是一套面向城市规划、建筑设计与三维场景制作人群的规则资源包内置54个CGA核心规则文件及配套资源通过参数化规则驱动批量生成建筑模型免去逐栋手工建模的重复劳动。RAR压缩包共4061个文件、约395.68MB其中2686张JPG预览图便于快速比对样式971个JS脚本承担交互与辅助逻辑151个PNG贴图配合29组OBJ/MTL三维模型及材质丰富立面细节另有CGB、TXT、XML等用于规则配置与工程说明。已有1647人下载学习。规则库覆盖历史建筑到现代高层、住宅到商业街区等多样风格调整高度、宽度、屋顶、立面等参数即可生成差异化城市景观适用于方案推敲、大场景构建与城市设计可视化。借助日照和视线分析还能辅助规划决策适合希望提升批量建模效率、快速产出城市级三维方案的中高级设计师。1. 为什么我把 CityEngine 建筑规则库当作项目主干而不是建模脚本做城市片区的批量体块时手工建模不是不行但甲方第二天一句“轮廓线修正一下”你就要重新摆几小时。换成维护一个 CityEngine 建筑规则库后地块边界负责形状CGA 规则负责长高、分层、贴窗户、出屋顶参数一变Generate 一次就是新方案。所谓“建筑规则库”本质就是这整套 CGA 规则加贴图资产而不是某个现成的模型集。它能同时服务控规指标验证、三维辅助决策、游戏地块填充和数字孪生底座。适合谁读需要批量生成上百栋不重样建筑、或者想在团队里沉淀三维生成能力的人。规则不难学但有几个理解门槛和隐藏坑下面按我的落地路径展开。2. 拆解 CityEngine 建筑规则库CGA 语法、文件组织与调用链路2.1 规则库的“真身”是 CGA 规则而不是模型文件最初接手规则库时我下意识地找“模型在哪”最后发现整个库只有几份 .cga 文件和一堆贴图。建筑规则库不是模型合集而是一套用 CGACityEngine 的生成语言写出的规则脚本。脚本输入是一个二维面输出是一栋带立面细节的三维建筑。这一步没想清楚后面很容易把规则库用成“素材包”只在找模型不看逻辑。CGA 的核心机制类似“形状语法”一条规则被应用到当前 shape产生新的 shape 后再由下一个规则处理。常用操作就四样extrude 把面拉伸成体comp 按面方向分解立面与顶面split 沿轴切分成段repeat 循环重复某个分段。掌握这四样规则库能覆盖 80% 的建筑外形。StartRule Lot -- extrude(30) comp(f) { front: Facade | top: Roof | side: Facade }逻辑说明StartRule 是规则入口Lot 是初始地块 shape。extrude(30) 沿法线方向拉伸 30 米得到体块comp(f) 按面标签拆开front 是前立面top 是顶面side 是左右侧面。拆完分别交给 Facade 与 Roof这就算完成第一层“长高”。参数说明这里的 30 是硬编码高度项目里通常不会这么写。正式规则库会把 30 换成属性变量比如某个 attr height以便在 Inspector 里拖滑杆。理解这条命令与 comp 的关系是判断规则库结构好坏的第一步。为什么用 CGA 而不是写脚本批量建模常见做法是用 Python 在建模软件里循环复制但 CGA 的好处是“生成参数被显式保留”。改一个层高所有楼重新生成方案阶段做多轮比选这个优势非常关键。并且规则可以打包成 rpk给到不装 CityEngine 的同事用。2.2 规则库的文件组成规则脚本、贴图资产与数据边界一个规范规则库至少要同时管好三块规则脚本、资产资源、数据边界。常见做法是组织成下面的目录结构my_rule_lib/ rules/ main.cga helpers.cga assets/ textures/ window_diffuse.png facade_diffuse.png roof_diffuse.png models/ trim.fbx data/ blocks.shp export/参数说明rules/main.cga 是入口与主角规则链rules/helpers.cga 是被 include 的公共规则放窗框、窗台、空调位这些复用部件assets/textures 是贴图统一目录规则里全部用相对路径引用assets/models 放少量需要外部导入的模型data 是地块边界与控规数据驱动最终生成位置。很多人把纹理下载的 zip 直接塞进 assets/textures 就完事我建议先清理再入库第 3.2 节细讲。CGA 引用资产时用texture(assets/textures/facade_diffuse.png)这样的相对路径端口是工程根目录。不要写成C:\Users\...\foo.png。规则库一旦拷贝给同事或打包成 rpk绝对路径立刻失效。这也是 cityengine 规则库项目里最常见的协作翻车点之一。2.3 跑通最小规则链第一次看到参数驱动体块下面这版我在新项目验证环境时必跑。它足够短能把“shape 长高→分解→切层→上色”全链路打通同时暴露纹理路径、单位、坐标这三个基础问题。操作顺序一般是这样新建或导入一个面图层至少一个闭合多边形地块选中该地块右键 Assign Rule File选择 main.cga点击 Generate在 Inspector 里调节 buildingHeight重新 Generate 看体块变化。attr buildingHeight 24 StartRule Lot -- extrude(buildingHeight) comp(f) { front: Facade | top: Roof | side: Facade } Facade -- split(y) { ~3: Floor }* Floor -- color(#d8d8d8)逻辑说明buildingHeight 是属性参数默认 24 米。Facade 规则用 split(y) 沿着立面局部 Y 轴切分~3表示每层约 3 米带上波浪号是“近似切分”最后一段会自动吸收余数避免出现 0.03 米的残片。星号表示不断重复这段规则直到给的面被切完。参数说明把 ~3 改成 3会严格按 3 米切如果总高 24 米正好切 8 层看起来没差别但换成 25 米的楼就会有一段 1 米不到的残余层。规则库里为了画面稳定我一般保留波浪号除非有明确的模数要求例如幕墙板块必须 1.5 米宽。到这里你已经看到了规则库的调用链路数据面加规则文本Generate 后直接出三维模型接下来就该往里塞真实参数和纹理资产了。3. 从零搭一套 cityengine 规则库参数设计、纹理下载与三段式规则3.1 参数表先行把项目变量抽成属性我见过不少规则库规则写得天花乱坠但所有数字都硬编码在 CGA 里。结果是换一个项目照抄都难。正确做法是先列参数表把“会随项目变的变量”全部扔进 attr。下面是一个常规商住地块的起步参数表。| 参数名 | 默认值 | 作用 | | floorHeight | 3.3 | 标准层层高米 | | numFloors | 12 | 标准层数量 | | podiumHeight | 4.5 | 底层裙楼高度米 | | facadeSetback | 0 | 立面退台米 | | roofType | flat | 屋顶类型flat/gable/hip | | windowWidth | 2.4 | 立面开间参考宽度米 |attr floorHeight 3.3 attr numFloors 12 attr podiumHeight 4.5 attr facadeSetback 0 attr roofType flat attr windowWidth 2.4逻辑说明这些参数声明在规则文件顶部后会出现在 CityEngine 的 Inspector 面板里。用户不用打开 CGA 就能改层高、层数、屋顶类型。这也是建筑规则库作为“产品”而非“脚本”的起点使用界面是参数面板不是代码编辑器。参数说明roofType 用字符串配合下面的 case 做分支默认值要选安全值尤其 numFloors 别设 50否则第一次 Generate 就可能面数爆炸。参数命名用小驼峰中文名进代码会带来路径编码问题。3.2 纹理下载与资产整理贴图该怎么放、怎么命名关于 cityengine 纹理下载网上能找到大量免费或付费贴图包下面说的是怎么让下载资源在规则库里稳定工作。下载解压后不要直接拖进工程先把贴图统一处理成三件套漫反射、法线、高光缺失的可以先留空文件或注释掉对应语句。| 类型 | 命名 | 适用语句 | | 漫反射 | facade_diffuse.png | texture(assets/textures/facade_diffuse.png) | | 法线 | facade_normal.png | set(material.normal, ...) | | 高光/粗糙 | facade_specular.png | set(material.specular, ...) |参数说明法线和 specular 可选先用漫反射跑通。贴图统一放工程根目录 assets/textures 下CGA 里用相对路径。对外部下载的纹理我一般先做三件事改成规范文件名、去掉中文与空格、用图片工具转成 RGB 模式的 PNG 或 JPG。CMYK 的 JPG 在引擎里会显示成黑色这是纹理下载素材最容易翻车的地方。另一个技术细节是尺寸。做方案比选阶段贴图分辨率不要一上来就 2K、4K1K 足够看出效果批量生成时显存压力和生成时间都会友好很多。同类立面共用一个贴图文件比每栋建筑复制一份纹理更节省资源。CityEngine 对同路径贴图会做缓存复用所以规则里引用统一路径而不是分别拷一份到各楼目录。3.3 三段式规则底层裙楼、标准层与屋顶的代码实现下面这段规则把商住综合体最常见的“下商上住”拆成三段底层裙楼、标准层、屋顶。代码较长但每一段都能单独复用。attr floorHeight 3.3 attr numFloors 12 attr podiumHeight 4.5 attr roofType flat StartRule Lot -- extrude(floorHeight * numFloors podiumHeight) comp(f) { front: Facade | top: Roof | side: Facade } Facade -- split(y) { podiumHeight: Podium | ~floorHeight: StandardFloor }* Podium -- color(#f0e8dc) texture(assets/textures/facade_diffuse.png) StandardFloor -- split(x) { ~windowWidth: WindowTile }* WindowTile -- texture(assets/textures/window_diffuse.png) split(x) { 0.3 : WindowFrame | rest : WindowGlass } WindowFrame -- color(#444444) WindowGlass -- color(#99bbdd) Roof -- case roofType flat: color(#666666) case roofType gable: RoofGable(35) else: RoofHip(30)逻辑说明extrude 的高度由两段叠加标准层总高加裙楼高度。Facade 先做纵向 split先切出裙楼 Podium再把剩余立面按约 floorHeight 切成标准层。Podium 规则直接贴商场立面贴图StandardFloor 则横向按 windowWidth 切成若干开间最后在每个开间里分出窗框和玻璃。Roof 用 case 判断 roofType 字符串输出平屋顶、双坡或四坡屋顶。参数说明RoofGable(35) 的 35 是坡屋面角度范围一般 2045podiumHeight 必须小于总高度否则 split(y) 会把整段全部划给 Podium标准层消失。WindowTile 内部用 split(x) 分框和玻璃0.3 是窗框宽度剩余部分放玻璃。调试时先在单个地块上 Generate调 roofType 和 floorHeight 确认三个分支都出形状再铺到上百个地块能少走很多弯路。3.4 批量生成与导出从单栋验证到街区铺开单栋验证通过后进入批量阶段。常见做法是导入 shp 地块边界选中全部分区面指定同一规则文件然后 Generate。注意 shp 里的每个面必须是闭合多边形且坐标系与工程一致。大量自相交面会在 extrude 后产生穿刺体块这个在 GIS 阶段就要清理。导出时选择 File Export Models按目标平台选 FBX/OBJ/gLTF。要勾选导出纹理的选项否则到了游戏引擎里全白模。单位保持米坐标如果需要世界坐标注意 CityEngine 工程位置与目标场景原点的对齐。批量生成上千栋时建议先跑一版低面数方案确认形态和布局满意再开完整细节。有的项目不需要每一栋都独立模型可以考虑把体块合并导出但分栋导出便于后续单独修改。导出前用 Scene 里的 Statistics 面板看总面数超过目标平台预算就要回头简化规则。4. 建筑规则库避坑记录黑贴图、悬空体块与路径报错以下五条是我在落地规则库时实际踩过的坑每条按现象、原因、解决写读过一遍能省下不少排查时间。4.1 生成后建筑一片黑贴图找不到现象规则能跑体块也在但表面全黑或某些窗户区域黑掉Console 里常出现贴图加载失败。原因第一种是贴图路径用了绝对路径工程移到别的目录后失效第二种是外部下载的 JPG 是 CMYK 模式第三种是路径里有中文或空格CGA 解析失败。解决把贴图移入工程 assets/textures并在规则文件里改成相对路径用图片工具批量转成 RGB 的 PNG/JPG文件名统一小写英文字母加下划线。快速定位方法在疑似的规则前临时加color(#ffffff)如果模型变白问题基本在贴图不在几何。4.2 建筑悬空或陷入地表现象批量生成后一排建筑整体浮在地面上方或者首层埋进地形。原因地块 shape 的高程不是 0extrude 只沿 shape 局部坐标法线生长并不会自动找地面。地形起伏大的地方更容易出现基准面不一致。解决进入规则库前先把地块 shape 的高程统一。GIS 阶段用项目坐标系处理在 CityEngine 中选中所有 shape 后手动调整 Z 轴也是一种办法但量大会丢精度。直接在地形项目里CGA 开头可加alignToGround(y)它会让 shape 贴合地形但会明显增加地形相交复杂度和生成时间我默认只在沿山坡排布时用。4.3 立面窗墙比错乱split 与 repeat 的余数陷阱现象同一栋楼里窗户忽宽忽窄个别窗户被纵向拉伸到一层楼高开间分布“随缘”。原因这几乎是规则库新手必踩。split(y) { ~3: Floor }*里的波浪号表示近似切分剩余尺寸会被自动吸收横向split(x) { ~2.4: WindowTile }*同样。受限于立面总宽最后一段可能变成 1.7 米或 3.1 米贴在墙上观感很乱。解决要严格模数时用固定尺寸加兜底split(x) { 2.4: WindowTile | 0.4: Pillar }*参数说明2.4 是开间宽0.4 是窗间墙带星号的 split 会在剩余不足时把最后一段归入 Pillar。这样比拉伸窗户好得多。接受“近似切分”就要接受立面不均想全参数化又不留残段要靠 GIS 端把面宽做成模数这是很多规范立面项目的真相。4.4 生成速度慢到卡死现象几百栋一起 Generate 时长期转圈CPU 单核满载导出后模型面数超出引擎预算。原因规则里 split 和 repeat 层级太深每个开间都生成一扇窗、一个窗框贴图每块都不同缓存失效没有做 LOD 分档。解决先小范围测试确认单栋面数。然后在规则里加细节开关例如attr lod low低模时直接给色块不上窗框attr lod low StandardFloor -- case lod high: split(x) { ~windowWidth : WindowTile }* else: color(#cccccc)参数说明lod 是等级参数批量出方案用 low提交用 high。另外同一个立面材质共用一张贴图避免每扇窗一个文件。CGA 里生成的面数可以在 CityEngine 的 Statistics 面板查到永远不要靠猜。4.5 规则库换电脑就报循环引用错误现象同一套规则库在同事电脑上 Generate 直接报circular reference但本机没报。原因规则 A 调用规则 BB 又调用 A形成环include 文件互相 include 也会这样。团队协作中反复改公共规则时最容易引入。解决给规则库定单向依赖规矩入口 main.cga 只调用 helpers.cgahelpers.cga 不得调用 main.cga公共函数全部下沉到 helpers.cga。排查时看 Console 里的调用栈定位环的起点。这个错误不是玄学而是图结构成环规则停止生成是保护行为。5. 把规则库变成团队资产版本管理、参数边界与性能取舍5.1 用版本管理对抗“删错了回不来”规则库该存什么规则库是纯文本加贴图天然适合版本管理。我现在的习惯是 Git 仓库里跟踪三样东西rules 目录下的 .cga、assets/textures 目录下的贴图、以及一个 README 写明默认参数与纹理来源。工程 .cej 文件虽然也存但因为包含大量生成缓存不建议作为唯一的版本存档。git add rules/*.cga assets/textures/ README.md git commit -m feat: 增加裙楼分段和坡屋顶分支 git diff HEAD -- rules/main.cga逻辑说明第一条把规则脚本与贴图纳入版本控制第二条创建提交第三条查看 main.cga 相对于 HEAD 的改动。.cga 是纯文本diff 能精确看到哪一行参数变了。参数说明rpk 是打包后的规则库可以分发给不装 CityEngine 的人但它不适合放进 Git 做版本对比。打包动作留给发版阶段开发过程以 .cga 为准。这样能避免掉“忘了 .cga 改过什么”的后悔药问题。5.2 参数边界同一套规则库怎么兼容高层与多层把规则库做成团队资产时参数不是“能调就行”要有边界和分支。边界是指在 attr 声明上给出合理默认值并在规则内部用 case 过滤超出范围的输入。分支是指不同建筑高度走不同规则链例如超高层不再细开窗而是切换幕墙段。attr totalHeight 36 Lot -- case totalHeight 50: HighRise() case totalHeight 20: MidRise() else: LowRise()参数说明totalHeight 超过 50 走超高层链20 到 50 走中高层链小于 20 走多层链。每一链可以独立调立面细节。这样一套规则库能服务不同控规地块。这是“cityengine规则库”真正值钱的地方不是放下一个特定形状而是放下一套可推导的生成逻辑。批次不同、指标不同换参数出结果。给参数加注释时写明单位、范围与适用场景比如// 建筑总高单位米有效范围 12~120。不要低估注释对三个月后自己的作用。5.3 性能取向面数、纹理与细节的三角取舍| 立面细节做法 | 相对面数 | 适用场景 | | 窗框用几何体 | 高 | 近景特写 | | 窗框用贴图 | 低 | 中远景批量 | | 阳台用几何体 | 中 | 沿街面 | | 复杂屋顶用贴图 | 低 | 大量体块 |规则库的性能取舍本质是“细节放哪里”。同一个立面几何窗框要 612 个面贴图窗框只需 1 个面。城市级批量生成阳台、雨棚这类装修构件必须控制数量。经验数据仅供参考街区级近景可以接受每栋建筑 500010000 面城市级远景应压到 2000 面以内。用 Statistics 面板盯总面数超了就按第 4.4 节的方式从 high 切 low。6. 批量生成前的验证清单6 个检查点和一次方案对比6.1 六个检查点批量铺开前我固定走六个检查点。第一高程基准所有 shape 的 Z 已统一无悬空。第二纹理路径CGA 里全部相对路径贴图在 assets/textures。第三参数边界层数、层高、屋顶类型在合理范围。第四单栋外观窗墙比和屋顶样式经评审不是“能生成就行”。第五面数统计Statistics 面板确认当前 LOD 在预算内。第六导出预检在单栋上导一次 FBX确认纹理拷贝、坐标单位、命名无异常。这六个都过再批量 Generate。6.2 用随机种子做方案对比规则库的好处是可以快速出多版方案。给规则加一个参数化种子让分风格部件通过随机选择错开便于多方案比选。attr planSeed 1 Lot -- seed(planSeed) extrude(floorHeight * numFloors podiumHeight) comp(f) { front: Facade | top: Roof | side: Facade }逻辑说明seed 函数让后续 rand 系列调用产生确定的随机结果。planSeed 从 1 改到 5建筑高度和立面开间会变化但保持可复现同一个种子在不同机器上结果一致。方案对比时把这组参数截图保存。参数说明建议把种子参数单独放一个项目配置文件不混在业务参数里。这样生成对比时只改种子不影响层高、numFloors 这些业务值。我现在的习惯是批量生成前先用 3 个随机种子出三版对比存档后再正式铺开。规则库不是黑盒它只是一套你能读懂的生成逻辑只要你把参数名、纹理路径和边界条件写清楚后面每次生成都在帮你省时间。希望帮到你。本文还有配套的精品资源点击获取