# Xeed → UE / TouchDesigner 本机渲染桥

日期：2026-10-03。策略：`proposed`。当前交付是参数契约、网站校验接口、本机适配器和 TD 回调模板。未安装引擎，未生成 UE/TD 工程，未验证实际渲染。测试中的引擎回复均为受控测试替身；真实 HTTP 测试仅在本机 `dry-run` 下进行。

## 1. 数据与画面分开

```text
Xeed 网站 / 教学模型（拥有状态变化逻辑）
  → 浏览器明确点击发送
  → 127.0.0.1:4888 本机桥（精确来源许可 + 本次会话配对码）
  → UE 127.0.0.1:30010 或 TD 127.0.0.1:9980
  → 已经制作好的视觉工程
```

网站 `GET /api/render-bridge` 返回契约与默认样例；`POST /api/render-bridge` 校验、回传参数，结果是 `contract-only`，**不会向任何引擎发送**。接口只使用 Web `Request`、`Response` 和流，适用于当前 Cloudflare Workers 项目。云端服务中的 `localhost` 指云端机器，不是你的 Mac；因此本机桥由你的浏览器直接访问，不能把云端接口当作本机端口代理。[Cloudflare Request 文档](https://developers.cloudflare.com/workers/runtime-apis/request/)

三种成功结果必须区别：

| 结果 | 实际完成 | 尚未证明 |
|---|---|---|
| `contract-only` | 网站验证参数 | 本机桥启动、引擎收件、渲染 |
| `dry-run` | 浏览器/测试端向本机桥发送，桥校验并回传同一帧 | UE/TD 接收或渲染 |
| `engine-http-ack` | 引擎回调返回相同 sequence 的应用确认 | 画面正确、帧率、网页视频输出 |

所有回执都有 `renderedVerified:false`。`/v1/status` 不主动探测引擎，只报告配置、忙碌状态、上次回执和错误；历史回执不能作为持续在线的证据。

## 2. 先在本机完成 dry-run

需要 Node ≥ 22.13。项目根目录操作；核心文件没有依赖你电脑的绝对路径。

Mac 终端：

```sh
cp -n config/render-bridge.env.example .env.render-bridge.local
node --env-file=.env.render-bridge.local --experimental-strip-types scripts/render-bridge/server.mjs
```

Windows PowerShell：

```powershell
if (-not (Test-Path .env.render-bridge.local)) {
  Copy-Item config/render-bridge.env.example .env.render-bridge.local
}
node --env-file=.env.render-bridge.local --experimental-strip-types scripts/render-bridge/server.mjs
```

保留 `XEED_BRIDGE_TARGET=dry-run`。在**运行桥的这台电脑**打开 `http://127.0.0.1:4888/`，点击显示按钮，复制临时配对码。在网站的引擎连接面板填写端口 `4888` 和配对码，连接后发送一帧。得到 `dry-run` 且返回相同 sequence 和参数，才算本机往返成功。码只保存在进程内，每次启动不同，停止进程立即失效；网站不应把它保存为公共配置。

端口冲突时修改 `XEED_BRIDGE_PORT`，网站端同步填相同端口。网站端不能指定引擎 URL、函数名或对象路径，桥固定发送到 `127.0.0.1`；不绑定 `0.0.0.0`，不做公网转发。

`.env.render-bridge.local` 被现有 `.env*` 规则忽略，只属于这一台设备。Mac/PC 各自填写端口、引擎对象和来源；代码、契约、模板通过 Git 同步，`.toe`、`.tox`、UE 项目大型素材通过共享存储同步。

## 3. TouchDesigner：建立接收端

1. 在自己的 TD 工程建立一个 Base COMP，例如 `xeed_bridge`。在里面创建 Web Server DAT、Callbacks DAT 和一个名为 `xeed_channels` 的 Table DAT。
2. Web Server DAT 的 `Local Address` 填 **127.0.0.1**，`Port` 填 **9980**。不要留空 Local Address：官方说明空值监听全部接口。把 Callbacks DAT 参数指向上面的回调 DAT。[Web Server DAT](https://derivative.ca/UserGuide/Web_Server_DAT)
3. 将项目 `scripts/render-bridge/td_callbacks.py` 的内容导入该回调 DAT。回调只接受 `POST /xeed/frame`、有限参数和本机 TD 令牌；它把通过验证的数值写入 `xeed_channels`，保存整帧到 COMP 的 `xeedFrame`，返回版本、sequence 和 accepted。请求字段和响应字典按当前官方回调 API 编写。[webserverDAT Class](https://derivative.ca/UserGuide/WebserverDAT_Class)
4. 为这一台电脑创建一个 24–128 字符的随机本地字符串（ASCII 字母、数字、下划线或连字符），不要发送到聊天或提交到仓库。填入 `.env.render-bridge.local` 的 `XEED_TD_TOKEN`。在 TD 的 Textport 用相同值设置 `op('你的 COMP 路径').store('bridgeToken', '你自己的本机字符串')`。工程若保存该值，则只能作为私有设备资产保存。
5. 给 `xeed_channels` 接一个 DAT to CHOP，配置为按行读取：第一列 channel names、第二列 values，跳过标题行。先检查 `rain`、`wind`、`leafOpenness` 等通道是否出现；TD 版本的转换参数显示名可能不同，可在 operator help 确认。
6. 将通道绑定到已经制作好的粒子、风场、灯光与植物形变参数。例如 `rain/100` 控制你定义的降雨粒子可见强度，`wind` 控制风场，`leafOpenness` 控制叶片展开幅度。通过 Math/Lag CHOP 做值域转换和平滑。它不会自动制作完整粒子植物。
7. 激活 Web Server DAT。将桥配置改为 `XEED_BRIDGE_TARGET=td`，重启本机桥并重新配对。从网站发送一帧；先检查 `engine-http-ack` 和 Table DAT，再人工检查画面。TD 回执说明通道已经写入，不能说明作品已经调试完成。

## 4. Unreal Engine：建立受限 Blueprint 接收函数

1. 在自己的 UE 工程启用 **Remote Control API** 插件，重启编辑器。在 Output Log 的 Cmd 输入 `WebControl.StartServer`；默认 HTTP 端口 30010。官方说明默认监听 **127.0.0.1**。核查你项目 `DefaultEngine.ini` 的 `[HTTPServer.Listeners]` / `DefaultBindAddress` 没有被改成 `0.0.0.0` 或局域网地址；如需要显式设置，采用 `DefaultBindAddress=127.0.0.1`。当前官方文档将 Remote Control 标为 Beta。[Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/remote-control-quick-start-for-unreal-engine)
2. 建立 Actor Blueprint，例如 `BP_XeedRenderBridge`，放进需要运行的关卡。在该 Actor 上创建可由 Remote Control 调用的公开函数 **ApplyXeedFrame**。输入名必须与下表完全一致；不是任意 Custom Event 名称。

| 输入 | 类型 | 范围/用途 |
|---|---|---|
| Sequence | Integer | 0–1,000,000,000，原样返回 |
| Source | String | `manual-visual` 或 `teaching-model` |
| RainVisibility / SnowVisibility / FogVisibility / DustVisibility | Float | 0–100，作者视觉可见强度 |
| WindSpeed / WindDirection | Float | 0–25 m/s；−180–180 屏幕方向度数 |
| CloudCover / Humidity / SoilWater | Float | 0–100；humidity 实际契约为10–100；SoilWater 是教学根区比例 |
| LightingHour | Float | 0–24 |
| DayTemperature / NightTemperature | Float | −15–45 °C / −20–35 °C |
| LeafOpenness / MotionEnergy | Float | 0–1，作者表达参数 |
| LeafHue | Float | 0–360，色相度数 |

3. 在函数内把这些输入分配到 Niagara User Parameters、材质参数、灯光和你自己的植物骨骼/形变控制。0–100 的可见强度需按你作品的实际范围转换。模型的根区水量、季节过程仍由 Xeed 计算；UE 只呈现结果。
4. 函数增加 **Applied (Boolean)** 与 **AcceptedSequence (Integer)** 两个输出。只有参数已经成功写入目标控制后，返回 `Applied=true`，`AcceptedSequence=Sequence`。否则返回 false。桥要求收到这两个字段并匹配 sequence；仅 HTTP 200 不算应用确认。
5. 复制实际 Actor 的 UObject path，填入设备配置 `XEED_UE_OBJECT_PATH`；不要复制 Windows/macOS 文件系统路径。编辑器关卡实例与 PIE 实例的对象路径可能不同，必须采用当前运行实例。用 `/remote/object/describe` 在本机核查函数名和参数暴露。[HTTP Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/remote-control-api-http-reference-for-unreal-engine)
6. 设置 `XEED_BRIDGE_TARGET=ue`，确认 `XEED_UE_PORT=30010` 或自己的本机端口，重启桥、重新配对并发送。若 Actor 路径错误、输出不匹配或超时，网站会显示错误，不会报成功。

桥只调用固定函数 `ApplyXeedFrame`；没有暴露搜索资产、运行任意函数、写任意属性等通用 UE 控制能力。初始控制更新可先手动发帧；以后如增加持续发送，建议从每秒 5 次等低频控制尝试，并在引擎内插值。这只是工程起点，尚未做性能实测。

## 5. 发布网站后的浏览器限制

本机桥来源许可默认只有 `http://localhost:5173` 和 `http://127.0.0.1:5173`。发布后将**实际 HTTPS 网站 origin** 加入设备配置 `XEED_BRIDGE_ORIGINS`，用逗号分隔；不得填写 `*` 或带路径 URL。换域名后重启桥。

公开网站访问 loopback 属于浏览器本地网络访问。Chrome 文档说明从 Chrome 142 起加入 Local Network Access 许可；网站仍需满足安全上下文、精确 CORS 和浏览器/操作系统权限。[Chrome Local Network Access](https://developer.chrome.com/blog/local-network-access)

Loopback `http://127.0.0.1` / `http://localhost` 有安全上下文的特殊处理，但浏览器支持与站点 CSP 仍需实际测试。普通局域网 HTTP 不应视为 HTTPS 网站必然可访问。[MDN Mixed content](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Mixed_content)

若连接被拒绝，依次检查桥是否运行、端口、配对码是否本次启动、来源是否精确、浏览器网络权限与控制台 CORS/CSP；不要通过关闭浏览器安全策略解决。先完成本地网站版本的配对；公开 HTTPS 域名到本机桥的完整浏览器验证尚未完成。Windows PC 上 localhost 始终是 PC 本身，不能用它访问 Mac 的 UE/TD。

## 6. 参数接口不会传回视频

此桥发送数值，不传视频或音频。网站嵌入 UE 画面需要独立的 Pixel Streaming/WebRTC 链路，包括运行渲染、编码画面的机器和信令；GPU、编码、网络与并发需要另测。TD 也需单独设计视频输出与网页播放。项目现在没有启用这些通道。[UE Pixel Streaming](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-pixel-streaming-in-unreal-engine)

## 验证与边界

- Node 合同/API/安全/适配器测试 14 项通过，包含真正的 loopback HTTP dry-run 往返，以及请求仍在上传时防止并发穿透。
- 改动范围的 TypeScript 检查与 lint 通过；TD 回调 Python 语法与 3 项纯回调测试通过（令牌拒绝不改通道、写入后匹配回执、非法参数/缺失 Table 不回报成功）。
- UE、TD API 的回执格式、错误、超时和固定映射采用受控替身验证。无真实引擎集成结果，无 GPU/帧率测量。
- 本机桥不接 OpenAI，不把 LLM 输出接入正式生命状态，不把视觉雨雪百分比冒充实测降水，不改变原有教学模型或学生记录。