Appearance
Unity 与 Android 跨端消息协议
一张图不是单纯 Unity 项目，它需要和 Android 服务、车控、系统属性、渲染首帧、NGP 场景持续通信。from_unity 模块的价值，是把这些消息从“散落调用”收束成可注册、可追踪、可扩展的协议层。
消息方向Unity ↔ Android
核心模式Factory / Router
治理重点线程 / 白名单 / 调试
背景
飞书 from_unity 文档覆盖了模块概述、完整调用链、目录结构、消息分发中心、消息接口层次、消息工厂模式、Unity Bridge、Android 服务交互、消息类型统计、核心消息示例、新消息接入步骤、性能优化、调试技巧和重构建议。
公开版本不展示内部消息码、类名清单和具体业务字段，只抽象出一套跨端协议的工程设计。
问题
| 问题 | 表现 | 风险 |
|---|---|---|
| 消息入口多 | Unity、Android 服务、业务模块都可能发起调用 | 排查链路长，容易漏处理 |
| 消息类型杂 | 车控、渲染、查询、场景类消息混在一起 | 新增消息时容易复制旧错误 |
| 线程边界复杂 | UI、Unity 主线程、Android 服务线程各有约束 | 卡顿、死锁、返回语义不清 |
| 调试成本高 | 只看单端日志无法判断消息是否走完 | 线上问题难复现、难归因 |
协议分层
text
Unity C#
-> Unity Bridge
-> from_unity Router
-> Message Factory
-> Message Handler
-> Android Service / System API
-> Result / Callback协议层要承担四件事：
- 统一入口：所有跨端消息先进入 Router，而不是业务模块互相直连。
- 统一注册：消息类型、处理器和白名单有明确关系。
- 统一线程边界：明确哪些步骤可异步、哪些必须回主线程。
- 统一调试口径：日志、消息码、耗时、返回值可追踪。
消息类型
| 类型 | 说明 | 设计重点 |
|---|---|---|
| 控制类 | 车控、系统控制、场景动作 | 幂等、权限、失败回传 |
| 渲染类 | 首帧完成、渲染状态、图层状态 | 不能阻塞主渲染链路 |
| 查询类 | 系统属性、状态查询、配置读取 | 返回值语义必须稳定 |
| 场景类 | NGP、泊车、地图状态切换 | 需要和 XMapState 对齐 |
新消息 SOP
飞书资料里最有价值的部分，是把“加一个新消息”变成标准流程：
- 定义消息码和语义，不复用含义模糊的旧消息。
- 创建处理器，明确输入、输出、失败返回和线程策略。
- 注册到工厂或路由表，避免散落 if/else。
- 补日志和白名单，保证灰度和排查可控。
- 做端到端验证：Unity 发出、Android 收到、服务调用、结果回传、异常分支。
性能与线程
跨端消息的性能问题通常不是单条消息慢，而是线程切换、队列积压、序列化和日志放大叠加。
| 关注点 | 处理原则 |
|---|---|
| 线程切换 | 主线程只做必要桥接，耗时操作下沉到后台 |
| 消息队列 | 高频消息要限流或合并，避免撑爆消费端 |
| 数据序列化 | payload 控制大小，避免把整段状态透传 |
| 日志 | 高频链路采样或分级，避免日志本身制造卡顿 |
调试体系
一个可维护的跨端协议，调试能力要内置：
- 能按消息码查询处理器。
- 能看到消息从 Unity 到 Android 的完整路径。
- 能区分“未发送、未注册、处理失败、返回失败”。
- 能统计高频消息和失败消息。
- 能用白名单控制新协议灰度范围。
与 KSP 注解化的关系
from_unity 侧解决的是运行时路由和处理器治理；KSP 注解化解决的是 Android 信号注册的编译期生成。两者可以形成闭环：
text
协议定义
-> 注解声明
-> 编译期生成注册代码
-> 运行时 Router 分发
-> 日志 / 监控 / 回传可复用方法论
- 跨端通信先设计消息生命周期，再设计字段。
- 消息新增必须有 SOP，不允许只复制一个旧处理器改字段。
- 高频消息要把日志、序列化和线程切换一起算进成本。
- 调试能力必须是协议层能力，不应该靠临时加日志。
复盘
原页面只写了一个简化 payload，现在已经补成 from_unity 协议治理案例。下一步可以继续从飞书资料中抽象“消息码统计”和“重构优先级”，做成一张可公开的协议治理看板。
公开版深化
案例定位
Unity 与 Android 跨端消息协议不是孤立笔记，而是引擎架构能力下的一个可复用案例。它服务于“小鹏一张图 / Unity Android Bridge”这条主线，公开版重点保留问题抽象、工程取舍和可复用方法，不暴露内部系统细节。
关键问题
一张图不是单纯 Unity 项目，它需要和 Android 服务、车控、系统属性、渲染首帧、NGP 场景持续通信。from_unity 模块的价值，是把这些消息从“散落调用”收束成可注册、可追踪、可扩展的协议层。
这篇文章已经覆盖 背景、问题、协议分层、消息类型、新消息 SOP、性能与线程。后续阅读时应重点看三件事：问题如何被定义，方案如何在约束下落地，以及哪些经验可以迁移到下一次类似项目。
企业级产出
| 产出 | 公开表达 |
|---|---|
| 问题定义 | 用用户体验、性能、稳定性或交付效率描述影响 |
| 技术方案 | 保留架构、流程、算法和工具链层面的抽象 |
| 指标证据 | 只使用页面已有数字或经过脱敏审查的量级 |
| 复用方法 | 沉淀为 SOP、检查清单、图谱关系或后续案例链接 |
指标与证据
- 1 份 from_unity 深度资料
- 4 类消息通道
- 新消息 SOP 标准化
复盘结论
这个案例的核心价值，是把一次具体工程处理沉淀成可检索、可复盘、可继续扩展的技术资产。没有公开证据支撑的细节继续留在私有材料池，不进入线上页面。
公开版深化
案例定位
Unity 与 Android 跨端消息协议不是孤立笔记，而是引擎架构能力下的一个可复用案例。它服务于“小鹏一张图 / Unity Android Bridge”这条主线，公开版重点保留问题抽象、工程取舍和可复用方法，不暴露内部系统细节。
关键问题
一张图不是单纯 Unity 项目，它需要和 Android 服务、车控、系统属性、渲染首帧、NGP 场景持续通信。from_unity 模块的价值，是把这些消息从“散落调用”收束成可注册、可追踪、可扩展的协议层。
这篇文章已经覆盖 背景、问题、协议分层、消息类型、新消息 SOP、性能与线程。后续阅读时应重点看三件事：问题如何被定义，方案如何在约束下落地，以及哪些经验可以迁移到下一次类似项目。
企业级产出
| 产出 | 公开表达 |
|---|---|
| 问题定义 | 用用户体验、性能、稳定性或交付效率描述影响 |
| 技术方案 | 保留架构、流程、算法和工具链层面的抽象 |
| 指标证据 | 只使用页面已有数字或经过脱敏审查的量级 |
| 复用方法 | 沉淀为 SOP、检查清单、图谱关系或后续案例链接 |
指标与证据
- 1 份 from_unity 深度资料
- 4 类消息通道
- 新消息 SOP 标准化
复盘结论
这个案例的核心价值，是把一次具体工程处理沉淀成可检索、可复盘、可继续扩展的技术资产。没有公开证据支撑的细节继续留在私有材料池，不进入线上页面。
公开版深化
案例定位
Unity 与 Android 跨端消息协议不是孤立笔记，而是引擎架构能力下的一个可复用案例。它服务于“小鹏一张图 / Unity Android Bridge”这条主线，公开版重点保留问题抽象、工程取舍和可复用方法，不暴露内部系统细节。
关键问题
一张图不是单纯 Unity 项目，它需要和 Android 服务、车控、系统属性、渲染首帧、NGP 场景持续通信。from_unity 模块的价值，是把这些消息从“散落调用”收束成可注册、可追踪、可扩展的协议层。
这篇文章已经覆盖 背景、问题、协议分层、消息类型、新消息 SOP、性能与线程。后续阅读时应重点看三件事：问题如何被定义，方案如何在约束下落地，以及哪些经验可以迁移到下一次类似项目。
企业级产出
| 产出 | 公开表达 |
|---|---|
| 问题定义 | 用用户体验、性能、稳定性或交付效率描述影响 |
| 技术方案 | 保留架构、流程、算法和工具链层面的抽象 |
| 指标证据 | 只使用页面已有数字或经过脱敏审查的量级 |
| 复用方法 | 沉淀为 SOP、检查清单、图谱关系或后续案例链接 |
指标与证据
- 1 份 from_unity 深度资料
- 4 类消息通道
- 新消息 SOP 标准化
复盘结论
这个案例的核心价值，是把一次具体工程处理沉淀成可检索、可复盘、可继续扩展的技术资产。没有公开证据支撑的细节继续留在私有材料池，不进入线上页面。