📐 架构总览

CGA.js 引擎是一个分层架构的 CGA 规则解析与三维生成系统，核心流程为：源代码 → 解析 → AST → 求值 → 几何生成。

⚙️ 解析管线（Pipeline）

从 CGA 源码到三维模型的完整处理流程：

🏗️ 分层设计

🔍 Parser 层详解

Grammar 结构

Grammar 采用 ANTLR4 格式，核心规则包括：

• script — 入口：version、import、attr、const、func、style、rule 的集合
• ruleDef — 规则定义：ident(params)? --> ruleBody
• ruleBody — 规则体：operationChain / conditional / stochastic / assignment
• operation — 操作：simple / comp / split / pushPop / block / tempShape
• expression — 表达式：算术、关系、逻辑、成员访问、数组、条件表达式

关键设计：通用 Block 解析

// Grammar 中的 blockOperation（通用规则）
blockOperation
    : ident ('(' argList? ')')? blockBody (operationSuffix? blockBody)*
    ;

// 以下都被解析为同一个 BlockOperation AST 节点：
setback(1) { front: A | back: B }
offset(1) { inside: A | border: B }
inline("recompose") { A } { B }
myNewFunc(10) { body }  // ← 未来新函数，自动兼容

Parser 回归测试

216 个测试覆盖所有 operation 类型、表达式类型和边缘 case。任何 Grammar 修改都必须通过这些测试。

🧮 Evaluator 层详解

求值上下文（EvalContext）

每个编译请求创建一个独立的求值上下文，包含：

• script — 完整的 CGAScript AST
• globals — 全局变量（attr、const）
• userFuncs — 用户自定义函数
• currentDepth / maxDepth — 递归深度控制（防死循环）
• traceLog — 执行追踪日志（调试用）

Operation 分派

Evaluator 根据 AST 节点类型分派到对应处理器：

evalOperation(op, shape, ctx)
  ├─ SimpleOperation → evalSimpleOperation(name, args, shape, ctx)
  ├─ CompOperation   → evalCompOperation(selector, branches, shape, ctx)
  ├─ SplitOperation  → evalSplitOperation(axis, branches, shape, ctx)
  ├─ PushPopOperation→ evalRuleBody(body, shape, ctx)
  ├─ BlockOperation  → evalBlockOperation(op, shape, ctx)
  └─ TempShapeOperation → evalRuleBody(body, shape, ctx)

📐 Geometry 层详解

Geometry 层是纯函数集合，按功能分为多个目录：

📋 函数注册表（Function Registry）

为了避免 evaluator.ts 成为"千行怪兽文件"，引擎引入了函数注册表机制。

注册 API

// src/runtime/evaluator.ts
export function registerSimpleFunction(
  name: string,
  handler: (shape, argVals, ctx) => Shape[]
);

export function registerBlockFunction(
  name: string,
  handler: (op, shape, argVals, ctx) => Shape[]
);

工作原理

现有内置函数注册位置

目前内置函数仍在 evaluator.ts 的 switch-case 中，但注册表优先于 switch-case。未来新函数建议通过注册表添加。

➕ 添加新函数指南

场景 A：普通函数调用 myFunc(args)

1. 实现几何逻辑

   // src/geometry/operations/create/my-func.ts
   export function myFunc(shape: Shape, height: number): Shape {
     // 纯函数：输入 Shape，返回新 Shape
     return newShape;
   }

2. 注册到引擎

   import { registerSimpleFunction } from '../runtime/evaluator.js';
   import { myFunc } from '../geometry/operations/create/my-func.js';
   
   registerSimpleFunction('myFunc', (shape, args, ctx) => {
     return [myFunc(shape, args[0] as number)];
   });

3. 添加测试

   // tests/parser/operations.test.ts
   { name: 'myFunc', code: 'Lot --> myFunc(10)' }
   
   // tests/functions/my-func.test.ts
   // 验证执行结果

场景 B：Block 形式函数 myFunc(args){body}

1. 实现几何逻辑（同上）
2. 注册 Block Handler

   import { registerBlockFunction } from '../runtime/evaluator.js';
   
   registerBlockFunction('myFunc', (op, shape, argVals, ctx) => {
     // op.bodies: RuleBody[] — block 内的规则体
     const result = myFuncGeometry(shape, argVals[0] as number);
     if (op.bodies.length > 0) {
       return evalRuleBody(op.bodies[0], result, ctx);
     }
     return [result];
   });

3. 添加测试（同上）

📜 Grammar 修改指南

什么时候改 Grammar？

修改 Grammar 的强制流程

1. 备份 — cp -r dist/ dist-backup-xxx/
2. 修改 — grammar/CGAGrammar.g4
3. 重新生成 — npm run generate-parser
4. 更新 AST Builder — src/parser/ast/types.ts + src/parser/visitors/ast-builder.ts
5. 运行回归测试 — npm test（216+ 测试必须全过）
6. 检查 Ambiguity — 观察测试输出中的 [Parser Ambiguity] 警告
7. 运行函数测试 — npm run test:functions
8. 构建 — npm run build
9. 构建验证 — npm run build
10. 生产部署 — ./scripts/deploy.sh prod 1.3.0 或 Admin 后台"构建并发布"

为什么尽量不改 Grammar？

• First-Set 冲突 — 新规则与现有规则的开头部分重叠
• Ambiguity — Parser 在多个路径间犹豫，可能导致错误选择
• 全局影响 — ANTLR4 的决策表是全局编译的，局部改动可能影响整体
• Visitor 不兼容 — 新规则需要 ASTBuilder 实现新的 visit 方法

saspOperation
    : 'splitAndSetbackPerimeter' '(' expression ')' '{' saspBranch '}' '{' saspRemainder '}'

🚀 部署架构

生产部署流程

Beta 测试站已下线，当前采用直接构建并发布到生产的单环境策略：

API 统一使用生产引擎：

cli = "/www/wwwroot/cgajs-engine/cli-wrapper.cjs"
    cli = "/www/wwwroot/cgajs-engine/cli-wrapper.cjs"

部署流程（前端+引擎同步）

🧪 测试体系

三层测试金字塔

部署脚本中的强制检查

scripts/deploy.sh 在部署前自动运行 Parser 回归测试和函数测试，任何失败都会阻断部署：

Step 1/4: Running parser regression tests... ✅
Step 2/4: Running function tests... ✅
Step 3/4: Building engine... ✅
Step 4/4: Deploying to beta/prod... ✅

📋 标准工作流速查

添加新函数（不改 Grammar）

1. geometry/operations/[category]/my-func.ts    ← 几何实现
2. registerSimpleFunction('myFunc', handler)     ← 注册
3. tests/parser/operations.test.ts              ← Parser 测试
4. tests/functions/ 或 tests/e2e/               ← 功能测试
5. npm test + npm run test:functions            ← 验证
6. npm run build                                 ← 构建引擎
7. ./scripts/deploy.sh prod 1.3.0               ← 直接部署到生产

修复 Parser Bug（需要改 Grammar）

1. 修改 grammar/CGAGrammar.g4
2. npm run generate-parser
3. 更新 src/parser/ast/types.ts
4. 更新 src/parser/visitors/ast-builder.ts
5. npm test（必须 216/216 通过）
6. 检查 Ambiguity 警告
7. npm run test:functions
8. npm run build
9. npm run build
10. ./scripts/deploy.sh prod 1.3.0

// 典型用法：建筑主体 → 立面分割 → 屋顶
Lot -->
  extrude(rand(10,20))
  comp(f) { top: Roof | side: Facade }

Facade -->
  split(y) { ~1: Floor }*

Roof -->
  roofGable(30)
  texture("roof.jpg")

// 基于Scope的自适应缩放
Adaptive -->
  alignScopeToAxes(y)
  s(scope.sx * 0.9, scope.sy, scope.sz * 0.9)
  center(xz)

// 砖墙材质UV设置
BrickWall -->
  setupProjection(0, scope.sx, scope.sy)
  projectUV(0)
  tileUV(0, scope.sx / 0.5, scope.sy / 0.3)
  texture("brick.jpg")

// 随机楼层高度
FloorHeight -->
  floor(rand(3.0, 4.5) * 10) / 10

// 从列表随机选材质
PickMaterial -->
  listRandom("brick.jpg;concrete.jpg;wood.jpg;")
  texture(listRandom("brick.jpg;concrete.jpg;wood.jpg;"))

// 按面积自适应细节
Detail -->
  case geometry.area > 50 : HighDetail
  else : LowDetail

// 动态加载适配窗户
Window -->
  insert(assetFitSize(assets, scope.sx * 0.8))

// 散布树木到地面
Ground -->
  scatter(surface, 50)
  insert("tree.obj")

// 高度驱动的颜色渐变
ColorByHeight -->
  color(colorRamp("height", geometry.height / 50))

📊 CGA.js 能力评估与增强路线图

本报告基于 CityEngine 2025.1 官方 CGA Reference 对 CGA.js 引擎进行系统评估，明确当前解析/求值能力、与官方的差距、以及可作为差异化竞争力的独特能力。

1. 与 CityEngine 2025.1 的覆盖对比

估算方式：coverage = (fully + 0.5 × partial) / total。

2. 重点函数/特性跟踪（Top 15）

这些函数在真实 CityEngine 规则中使用频率高，且在 web/Three.js 引擎中可实现：

3. 不建议在浏览器引擎中实现的能力

以下能力需要重型 GIS、CAD 解析或精确浮点语义，超出当前引擎定位：

4. CGA.js 独有的竞争力

相比 CityEngine 桌面版，本引擎原生具备以下差异化能力：

5. 布尔 CSG 方案：three-bvh-csg（已接入）

已正式接入 three-bvh-csg 替换原有的 bbox 近似布尔运算：

• 实现位置：src/geometry/operations/boolean/csg.ts。
• 库版本：three@0.164.1 + three-bvh-csg@0.0.17 + three-mesh-bvh@0.7.8。
• API：Evaluator.evaluate(brushA, brushB, ADDITION | SUBTRACTION | INTERSECTION)。
• 标签保留：通过 geometry.groups 记录 bool.A / bool.B 来源，结果 re-index 后恢复 label:* 标签，供后续 comp(f) 选择。
• 非流形 fallback：CSG 抛异常时自动回退到原 bbox 裁剪逻辑，保证复杂输入不崩溃。

6. 解析器增强路线图

以下 5 项可在现有 ANTLR Grammar + Evaluator 架构上增量实现，使引擎在 web 场景下超越 CityEngine：

7. 已落地实施清单

1. 接入 three-bvh-csg：替换简化布尔，支持真正的 union/subtract/intersect 并保留标签。
2. 补齐 Top 5 缺失函数：comp 数组选择器、split noAdjust/u-v、label、deleteTags、setTagsFromEdgeAttrs。
3. JSON 数据绑定 import：web API 数据可直接绑定到 CGA 属性。
4. 远程/版本化 import：pkg: URL 让 marketplace 具备模块仓库能力。
5. LOD 注解：@LOD(min, max) 按当前 LOD 过滤规则，支撑大规模场景简化生成。

8. 近期已落地能力（v1.3.x）

最近一次迭代完成了 5 项核心增强，显著缩小了与 CityEngine 的几何与工程能力差距：