📐 架构总览

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. Beta 部署 — ./scripts/deploy.sh beta
10. 手动验证 — 在 beta.cgajs.com 测试
11. 生产部署 — ./scripts/deploy.sh prod 1.3.0

为什么尽量不改 Grammar？

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

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

🚀 部署架构

Beta ↔ Prod 隔离

引擎采用双环境隔离部署策略：

API 根据请求的 Host Header 路由到对应引擎：

if host contains "beta":
    cli = "/www/wwwroot/beta-engine/cli-wrapper.cjs"
else:
    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. ./scripts/deploy.sh beta                     ← Beta 部署
7. beta.cgajs.com 手动验证                      ← 确认
8. ./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. ./scripts/deploy.sh beta
10. beta.cgajs.com 验证
11. ./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))