| name | unity-pico-design |
| description | Doc-anchored design rules for PICO Unity Integration SDK v3.4.0 — XR/MR/platform services, version diffs 2.x-3.4, hallucination shields |
Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.
Triggers
- Writing or reviewing PICO Unity Integration SDK (
PXR_* / Pico.Platform) code
- Setting up a PICO XR project or choosing the Unity OpenXR plugin route
- Video seethrough / spatial anchors / spatial mesh / SecureMR / platform services
- Migrating from SDK 2.x or an older 3.x version
- 编写或审查 PICO Unity SDK 代码、配置 PICO 项目或 OpenXR 路线、透视/锚点/网格/SecureMR/平台服务、2.x→3.x 版本迁移
PICO Unity SDK - Design Rules（v3.4.0）
Advisory 模块。全部规则提炼自 PICO 官方文档 v3.4.0（2026-08-13 全量抓取：指南 203 页 + API 参考 32 页 + 更新说明 14 个版本 + 8 个版本的 API 快照 diff）。SDK 闭源，锚定方式为官方文档 URL——每条规则可点击复核。正文中文，API 名保持英文。
Mode: Documentation only——无 REST skills 可门禁；Approval / Auto / Bypass 任何模式下均可自由加载。
为什么需要本模块
AI 训练语料中的 PICO 知识大量停留在 SDK 2.x / 早期 3.x：旧振动接口、AnchorEntity 事件三段式、PXR_SDK > 菜单、PXR_EyeTracking 类……这些在 3.4.0 已废弃或更名。3.2.0 一个版本就废弃了 PXR_Input 30 个成员、PXR_MotionTracking 27 个成员。凭记忆写 PICO 代码 = 高概率幻觉。生成任何 PICO 代码前先加载本模块对应子文档。
Critical Rule Summary（跨域最高优先级，子文档细读前也要记住）
| # | 规则 | 详见 |
|---|
| 1 | PICO XR 插件与 Unity OpenXR 插件二选一：同时勾选只有 PICO XR 生效；OpenXR 路线勾选其他厂商插件会导致应用无法运行 | SETUP.md |
| 2 | PXR_Manager 必须挂每一个场景（含加载场景）；SDK 3.1.0 起仅支持 64 位（IL2CPP + 仅 ARM64），且 Unity 菜单是 PICO 不是 PXR_SDK | SETUP.md |
| 3 | PXR_MotionTracking 系方法返回 int 状态码（0 成功）不是 bool；SetFoveationLevel 是两参且 None = -1 | API_REFERENCE.md |
| 4 | 旧触觉接口全组（SetControllerVibration / StartVibrateBy* / CreateHapticStream 等）3.2.0 已废弃 → 现行 SendHapticImpulse | VERSIONS.md |
| 5 | MR 全家（锚点/场景标定/平面检测）操作前必须 StartSenseDataProvider；anchor handle 重启失效，跨会话只能存 UUID；删锚点先 UnPersist 再 Destroy | MR.md |
| 6 | 视频透视四前置：禁后处理、Vulkan 下禁 HDR、Clear Flags=Solid Color、背景 RGBA 全 0；EnableVideoSeeThrough 生效有延迟且 resume 后要重调 | MR.md |
| 7 | 手柄与裸手不能同时追踪（Controller And Hands 是自动切换）；全身动捕与体感追踪器独立追踪互斥 | INTERACTION.md |
| 8 | 平台服务：CoreService.AsyncInitialize 判两层（IsError + Success/AlreadyInitialized）；房间/匹配/排行榜/成就还需 GameInitialize | PLATFORM.md |
| 9 | 面部追踪在 v3.4.0 是官方矛盾区：指南在教的 API 同版本已标 Deprecated，语料无替代类——可沿用但标注状态，勿编造新 API | PITFALLS.md |
| 10 | 渲染互斥矩阵：AppSW×BufferDiscards=撕裂、AppSW×内容保护=拖影、LateLatching×合成层=抖动、超分×锐化同 Buffer 只生效超分 | RENDERING.md |
Sub-doc Routing
| 子文档 | 何时读 |
|---|
| SETUP.md | 环境搭建、双插件路线选择、项目设置、AndroidManifest、Project Validation、Building Blocks、AR Foundation、工具与示例索引 |
| RENDERING.md | FFR/ETFR、超分/锐化、合成层（Overlay/Underlay）、多视图、自适应分辨率、AppSW、Late Latching、URP、空间音频、性能目标 |
| INTERACTION.md | 控制器输入映射、触觉反馈、手势/眼动/面部/身体追踪、体感追踪器、系统键盘、与 XRI 的关系 |
| MR.md | 视频透视、空间锚点（含共享）、空间网格、场景标定、平面检测、MR 安全防护、空间数据权限、相机图像双路线、2.5→3.x MR 迁移 |
| SECUREMR.md | SecureMR 框架（3.2.0+）：Tensor/Operator/Pipeline 概念、gltf 渲染、Dynamic Texture、Readback、JavaScript Operator |
| PLATFORM.md | 平台服务精要：初始化、账号/好友、成就、排行榜、IAP、DLC、云存档、房间&匹配、RTC、内容保护、企业服务概览 |
| API_REFERENCE.md | XR 核心 9 类逐方法签名表（含 Deprecated 标记）、PXR_Enterprise 方法域清单、Legacy API 处置 |
| VERSIONS.md | 版本时间线（v2.0.1→v3.4.0）、逐版本方法级 API 增/删/废弃表、2.x→3.x 迁移要点——废弃清单以本文件为单一事实源 |
| PITFALLS.md | 幻觉陷阱总闸：废弃 API 黑名单、签名语义陷阱、互斥矩阵、构建陷阱、官方文档自身矛盾清单、能力边界 |
Routing to Other Modules
Version Scope
锚定 v3.4.0（2026-02-27 上线，2026-08-13 抓取）。文档站可切换版本：3.4.0 / 3.3.2 / 3.3.0 / 3.2.0 / 3.1.0 / 3.0.5 / 3.0.0 / 2.5.0；更新说明覆盖至 v2.0.1。关键分水岭：
- 3.0.0：MR 接口全面重构（AnchorEntity 事件式 →
*Async + SenseDataProvider）
- 3.1.0：菜单
PXR_SDK → PICO；仅支持 64 位应用
- 3.2.0：史上最大废弃潮（PXR_Input 30 成员、PXR_MotionTracking 27 成员、PXR_System 面部/亮度组）；SecureMR 登场
- 3.3.0：
PXR_Over Lay → PXR_Composition Layer；部分 API 跨类搬家至 PXR_Enterprise
- 3.4.0：平面检测、
PXR_CameraImage（用户设备相机数据）、SecureMR JavaScript Operator
SDK 新版本发布后的语料更新方法见 memory：temp/pico-crawl/ 脚本重跑即可。
使用铁律
- 写 PICO 代码前先读对应子文档；语料查不到的 API 宁可声明"官方文档未记载"也不要按记忆补全。
- 官方文档自身有矛盾（面部追踪、XRI 版本口径、SecureMR 双套命名）——矛盾区处置见 PITFALLS.md 第五节，不要只信单页。
- 版本迁移问题一律先查 VERSIONS.md 的方法级增删表再回答。
