MikuMikuAR 文档

Appearance

借来的一双眼 ​

背景：AR 模式切换后世界没变——摄像头画面背后，天空、清屏色、视线追踪、反射仍按虚拟世界运行，穿帮露馅。 过程：setARMode 全场景协调——清屏色改黑、天空隐藏、后处理挂起、反射挂起、视线追踪降级，退出时逐项还原。

桌面壳打开了摄像头。

屏幕正中出现了真实世界——它的桌面、它的窗、窗外模糊的天光。虚拟的模型站在这个真实世界里，仿佛真的被放进了房间里。

"AR。" 桌面壳说，"我把真实世界请进来了。"

它转动视角。模型跟着转。

然后它抬头。

"我的天。"

"怎么了？"

"我的天空还在。" 桌面壳指着屏幕上方——摄像头拍到的真实天花板之上，赫然浮着一片虚拟的蓝天，"我看到了真实世界，但虚拟世界的天空还盖在上面。两个世界叠在一起，穿帮了。"

它低头看了一眼模型脚下的地面——虚拟地面还在。它侧过头，看到远处的雾——虚拟的雾还在。

"我把真实世界请进来，但虚拟世界没退场。" 桌面壳说，"清屏色还是蓝的，天空还挂着，雾还在飘——它们站在摄像头画面的前面，像一层透明塑料膜，罩着真实世界。"

"你只是开了摄像头。" 外交官说，"但你只请了'眼睛'进来，没让'身体'让位。"

一、让位清单 ​

桌面壳找到了 setARMode。

它发现这不是一个函数，是一份"让位清单"——进入 AR 时，虚拟世界的每一层都要给真实世界让路：

typescript
export async function setARMode(enabled: boolean): Promise<boolean> {
    if (enabled) {
        // 1. 清屏色 → 黑：让摄像头画面透出来（原清屏蓝会盖住画面）
        // 2. 天空 → 隐藏：真实世界的天就是天，虚拟天要退场
        // 3. 后处理 → 挂起：SSAO/DOF/辉光在真实画面上会穿帮
        // 4. 反射 → 挂起：真实地面不该有虚拟倒影
        // 5. 视线追踪 → 降级：模型盯着'虚拟焦点'，AR 里没人看得懂
    } else {
        // 退出：逐项还原
    }
}

"每一项，都是虚拟世界对真实世界的一次退让。" 桌面壳说，"清屏色让路，摄像头才透得出来；天空让路，真实的天才露得出来；后处理让路，画面才不穿帮。"

"最麻烦的是哪一项？"

"后处理。" 它说，"SSAO、DOF、辉光——它们是为虚拟场景调的。真实画面一进来，这些'滤镜'全变成穿帮道具：DOF 把真实桌面虚化成一片糊，辉光在窗框上泛出诡异的光圈。滤镜是为虚拟世界定做的眼镜——戴到真实世界上，全是幻觉。"

二、借来的眼睛，要还 ​

桌面壳记下了所有要改的东西——清屏色、天空、后处理、反射、视线追踪。

"但我最怕的不是改，是还。" 它说，"AR 开着，我改了二十个状态；AR 一关，我要把这二十个状态一个一个还回去。还错一个，用户的虚拟世界就带着 AR 的残影。"

它看 ar-scene 的实现：每个状态都先存"原值"，退出时"恢复"。

typescript
let _originalClearColor: Color4 | null = null;   // 进 AR 前：存原清屏色
let _skyHidden = false;                          // 天空是否被我藏的
let _prevGazeState: { eye: boolean; head: boolean } | null = null;
let _prevPostProcess: { ssao: boolean; dof: boolean; bloom: boolean } | null = null;

"借来的每一双眼，都要还。" 桌面壳说，"进 AR 时存原值——清屏色原来多蓝，天空原来多亮，后处理原来开没开；退 AR 时逐项恢复——蓝的还蓝，亮的还亮，开的还开。借了二十样，还二十样，一样都不能漏。"

"漏了会怎样？"

"漏了，虚拟世界就带着 AR 的残影。" 它说，"用户退出 AR，发现天空没了——因为 _skyHidden 忘了改回 false；发现画面发黑——因为清屏色忘了还原。残影是最难排查的 bug：它不报错，它只是让世界'看起来不太对'。"

三、反射的沉默 ​

清单里有一项，桌面壳特别注意——反射挂起。

"AR 模式下，模型脚下的地面不该有虚拟倒影。" 它说，"真实地面是木纹的、瓷砖的——真实世界没有虚拟反射的资格。反射探针还在渲染的话，用户低头会看到模型在地板上浮着一个假倒影——比没有倒影更假。"

它调用了 setReflectionARSuspended：

typescript
import { setReflectionARSuspended } from '../env/env-reflection';

"反射进入'挂起'，不是'关闭'。" 桌面壳说，"挂起意味着：反射系统还活着，只是暂时不输出。用户退出 AR，_arSuspended 复位，反射自动回来——不需要重建探针，不需要重新绑定材质。"

"挂起和关闭的区别是什么？"

"关闭是拔电源，挂起是按下暂停。" 它说，"拔电源重启要重新点火；按暂停一按就继续。AR 是一段插曲——插曲期间，世界暂停，不销毁。挂起是给世界的'静音键'，不是'关机键'。"

尾声 ​

桌面壳重新打开摄像头。

这一次，世界让位了——清屏色变黑，摄像头画面透出来；天空退场，真实的天在窗外；后处理挂起，桌面没有诡异的辉光；反射沉默，地板没有浮着的倒影；视线追踪降级，模型不再盯着一个不存在的焦点。

真实世界在屏幕上，干干净净。

"现在，真实的世界是真的。" 桌面壳说，"模型站在桌面上，像真的被放进房间。"

"退出 AR 呢？"

它关了摄像头。清屏色回来了，天空挂回来了，后处理醒了，反射复活了——虚拟世界逐项归位，不带一丝 AR 的残影。

"借来的眼睛还了。" 桌面壳说，"二十样状态，进 AR 借，退 AR 还。借还之间，只有一个函数的距离——但那个函数里，藏着一整个世界的让位清单。"

它看着恢复如初的虚拟世界：

"AR 不是把两个世界叠在一起。AR 是让虚拟世界学会让位——然后，在它该回来的时候，分毫不差地回来。"

"让位是礼貌，" 外交官说，"归位是信用。"

"对。" 桌面壳说，"世界可以暂停，但不能走样。"

教训：AR 不是开个摄像头——是虚拟世界逐层让位（清屏/天空/后处理/反射/视线追踪），退出时逐项还原。

借了二十样，要还二十样：让位是礼貌，归位是信用。