🎮 Unity 3D 与 WebGL 集成

Microi吾码可以承载 Unity 3D 游戏、数字孪生和沉浸式展厅：Unity 负责实时渲染与交互，Microi.Unity UPM SDK 负责浏览器桥接，V8 接口引擎负责身份、权限和业务数据。三层保持独立，Unity 客户端代码不编译进 Microi.Server。

Unity / WebGL

实时 3D 客户端

角色、设备、场景、物理、镜头、输入、材质和浏览器全屏运行。

Microi.Unity

可安装 UPM SDK

封装 V8 请求、DiyToken 续签、OsClient、WebGL SendMessage 与构建工具。

V8 接口引擎

低代码业务后端

用表单引擎、权限、事务和幂等键保存玩家或数字孪生业务状态。

图：仓库内“桃源云梦”样板的原创 AI 主视觉。实际 3D 山谷、角色、桃树、亭桥、湖水与花瓣由 Unity 运行时生成。

平台现状与选择

Microi 不是从零开始支持 Unity：大屏源码已有 Unity WebGL 加载组件，也已有项目级编辑工具、镜头与 WebGL 桥接代码。过去缺少的是稳定的公共 SDK、完整 V8 通讯约定、官方独立文档和可复现公开样板。

能力	当前标准入口	不推荐做法
Unity 客户端复用	仓库根级 Microi.Unity UPM 包	在 Microi.Server 建依赖 UnityEngine 的类库
页面嵌入	go-view 的 UnityWebGL 组件或独立全屏模板	每个页面复制一份 loader 与全局回调
业务通讯	/apiengine/{ApiEngineKey}	为单个游戏新增专用 Controller
身份	osclient + authorization: Bearer DiyToken	把 Token 放进 URL、场景或日志
状态持久化	Manifest 表 + V8 + 数据库唯一幂等键	用 Unity 内存或单节点锁作为完成事实

只有当需求涉及 V8 无法复用的平台级可信协议、安全原子能力或底层运行时内核时，才扩展 Microi.Server。常规玩家进度、设备状态、任务、积分和交互记录都应由接口引擎编排。

安装 Microi.Unity

在 Unity Packages/manifest.json 添加本地包：

{
  "dependencies": {
    "com.microi.unity": "file:../../../Microi.Unity"
  }
}

推荐包结构：

Microi.Unity/
├─ Runtime/Api/                  UnityWebRequest 与 DosResult
├─ Runtime/WebGL/                C# 宿主桥接
│  └─ Plugins/WebGL/*.jslib      浏览器事件
├─ Editor/                       WebGL 构建工具
└─ Samples~/                     最小可运行示例

项目级相机路径、触发区、场景模型和客户业务脚本应留在项目或 Samples~。提取旧工具箱时先复制和重构，验证新包替代全部引用后再考虑迁移；不得顺手移动来源不明或禁止再分发的素材。

Unity 调用 V8 接口引擎

场景中挂载 MicroiApiClient，用协程发起 JSON 请求：

StartCoroutine(client.PostJson(
    "microi_unity_taoyuan_bootstrap",
    "{}",
    response => Debug.Log(response.IsSuccess ? "ready" : response.Msg)));

SDK 请求约定如下：

POST /apiengine/microi_unity_taoyuan_bootstrap HTTP/1.1
Content-Type: application/json
osclient: tenant-key
apiengine: 1
authorization: Bearer {DiyToken}
did: browser-device-id

{}

WebGL 网络由浏览器 Fetch 实现，因此必须满足 CORS；跨域 API 还要把 authorization 加入暴露响应头。SDK 读取轮换后的 Token 并通知宿主，但不会输出或序列化 Token。生产环境优先让 WebGL 静态资源与 API 经同源反向代理访问。

Microi 页面向 Unity 注入上下文

Unity 实例就绪后，宿主通过 SendMessage 注入当前会话：

unityInstance.SendMessage(
  'MicroiApiClient',
  'ApplyMicroiHostContext',
  JSON.stringify({
    ApiBaseUrl: apiBase,
    OsClient: osClient,
    Authorization: currentDiyToken,
    Did: browserDeviceId
  })
)

这些数据只进入 Unity 运行时内存。禁止改成 ?token=、loader 路径或静态配置文件，因为浏览器历史、代理日志、监控和分享链接可能泄露凭据。

标准 .jslib 回调包括：

• window.onMicroiUnityReady()：Unity 场景已准备接收上下文；
• window.onMicroiUnityAuthorizationRotated(token, requestToken)：DiyToken 已轮换，并携带发起请求时的旧 Token，供宿主防止旧响应覆盖新会话；
• window.onMicroiUnityEvent(name, json)：游戏或孪生场景的普通业务事件。

页面离开时应调用 Unity Quit()，移除 Canvas、WASM、WebGL 上下文和全局回调。仅隐藏 DOM 会让 GPU 与内存继续占用。

V8 服务端安全模板

接口必须从 V8.CurrentUser 取当前身份，并使用数据库唯一索引实现幂等：

var user = V8.CurrentUser || {};
if (!user.Id) return { Code: 0, Msg: '未登录或 DiyToken 已失效。' };

var requestId = String(V8.Param.RequestId || '');
if (!/^[A-Za-z0-9._:-]{16,80}$/.test(requestId)) {
  return { Code: 0, Msg: 'RequestId 格式不合法。' };
}

var replay = V8.FormEngine.GetFormData('mci_unity_save_log', {
  _Where: [['RequestId', '=', requestId]]
});
if (replay && replay.Code === 1) {
  return { Code: 1, Data: { Replayed: true } };
}

// 继续校验坐标、数量和状态，再写当前用户快照与幂等日志。

完整应用包还应做到：

1. 玩家或设备身份只取权威会话，不接受客户端传入的 UserId。
2. 坐标、数量、状态变化和字符串长度由服务端重新校验。
3. RequestId 唯一索引作为多节点与重试事实源；普通进程锁不能替代。
4. 接口引擎返回 Code=1 自动提交，失败返回其它 Code 自动回滚，不手动提交事务。
5. 表、索引、接口、菜单通过应用 Manifest 安装，并声明 ResourcePolicies.ApiEngines。

桃源云梦样板

仓库 AI-Project/microi/Unity 提供一个 Unity 2022.3 LTS 完整样板：

• 程序化桃园山峰、可碰撞谷地、镜湖、拱桥、亭台、桃林、落花和流萤；
• 原创程序化古风女主，支持 WASD、奔跑、跳跃、镜头旋转和缩放；
• 九枚桃花灵韵收集玩法，以及离线漫游降级；
• V8 初始化与幂等保存接口、Manifest 和资源策略；
• 原创加载主视觉、自定义全屏 WebGL 模板和可复现构建脚本。

样板不依赖未知许可证的网络模型。若替换为第三方高精模型、动作、字体或贴图，必须保存来源、许可证、作者和下载版本；许可证不明时不得随官方 SDK 或应用包再分发。

WebGL 构建与部署

Unity 2022.3 目标使用 WebGL 2 与 WebAssembly。选择 Built-in 或 URP；HDRP 不适合作为 WebGL 交付路线。构建前先检查物理内存与已有 Unity/Node/dotnet 进程，只运行一个高资源任务。

& 'D:\Program Files\Unity\Hub\Editor\2022.3.62f3c1\Editor\Unity.exe' `
  -batchmode -quit `
  -projectPath 'D:\Work\microi.net.all\AI-Project\microi\Unity' `
  -executeMethod Microi.Taoyuan.Editor.TaoyuanWebGLBuild.Build

部署时配置 .wasm、.data、.js 与压缩文件的正确 MIME/Content-Encoding；也可以启用 Unity 解压回退以兼容不能设置压缩响应头的静态服务器。必须经 HTTP(S) 运行，不能双击 index.html 用 file:// 验收。

Unity 2022.3 的 WebGL 浏览器支持以 64 位桌面浏览器为主，移动浏览器不属于该版本的官方支持范围。移动端目标应另做设备分档、内存、触控和弱网验收，不能用桌面构建成功代替。

分层验收

证据层	最小断言
源码	UPM 可解析、C# 编译、Manifest/V8 语法与安全扫描通过
Unity Editor	场景进入 Play，角色移动/奔跑/跳跃，碰撞与收集正常
WebGL 构建	IL2CPP/WASM 构建成功，输出文件完整
浏览器	HTTP 加载、全屏、键鼠、压缩、控制台、退出释放正常
Microi 测试租户	当前用户隔离、Token 轮换、保存重放、无权请求失败
多节点	重复请求与节点切换只产生一次业务结果
远端/生产	静态资源、API、CORS、公开 URL 和真实回读分别确认

任何未执行的层都要在交付结论中明确标记，不能把源码检查描述成在线运行成功。

延伸阅读

• 3D、CAD 与数据大屏
• 接口引擎
• 应用商城
• Unity 2022.3 WebGL 浏览器兼容性
• Unity Package Manager