MikuMikuAR 文档

Appearance

ADR-047: 配置持久化覆盖现状 ​

状态: 已完成 — 2026-07-06 会话中修复了配置未持久化 Bug（clothConfig 防抖、调试开关、相机/时间流逝状态等），并完成全量覆盖梳理。 日期: 2026-07-06

一、持久化架构 ​

前端 envState / uiState
    ↓ setEnvState() / setUIState()（500ms 防抖）
    ↓ flushEnvState()（visibilitychange / beforeunload 立即刷写）
Go SetEnvState() / SetUIState()
    ↓ updateConfig() → writeConfig()
config.json（settingDir 或 configDir）

防抖机制 ​

防抖对象定时器间隔flush 入口
envState → SetEnvState_envPersistTimer500msflushEnvState()
场景 JSON → SaveLastSceneautoSaveTimer2000mssaveSceneImmediate()

两者均在 cleanupAndFlushSave() 中同步刷写（visibilitychange + beforeunload）。

二、已持久化状态 ​

EnvState（通过 SetEnvState → config.json.Env） ​

分类字段说明
天空skyMode, skyColorTop/Mid/Bot, skyTexture, skyRotationY, skyRotationSpeed, skyBrightness, starsEnabled, envIntensity天空外观
地面groundVisible, groundMode, groundColor, groundAlpha, groundTexture, groundTextureEnabled, groundTextureScale, groundTextureRotation, groundGridSize, groundLineColor, groundTerrainHeight, groundTerrainScale, groundTerrainSeed, groundTerrainOctaves, groundLevel, groundSize, groundEdgeFade, groundPitch, groundRoll, groundScrollSpeedX, groundScrollSpeedZ, groundPattern, groundReflectionBlend, groundReflectionQuality, groundNormalTexture, groundNormalStrength, groundElevationColoring, groundFollowCamera地面系统（边缘淡出 + Phase A 增强：坡度/纹理滚动/程序化图案 + Phase B 增强：镜面反射/法线贴图/高程着色/跟随相机）
地面 Phase AgroundPitch, groundRoll, groundScrollSpeedX, groundScrollSpeedZ, groundPatternADR-083 第一阶段（坡度/纹理滚动/图案）
地面 Phase BgroundReflectionBlend, groundReflectionQuality, groundNormalTexture, groundNormalStrength, groundElevationColoring, groundFollowCameraADR-083 第二阶段（反射/法线/高程着色/跟随网格）
风windEnabled, windDirection, windSpeed风场
粒子particleEnabled, particleType, particleEmitRate, particleSize, particleSpeed, particleSplash, particleCustomTexture粒子系统
水面waterEnabled, waterLevel, waterColor, waterTransparency, waterWaveHeight, waterSize, waterAnimSpeed基础水面
水面高级fresnelBias/Power, diffuseStrength, ambientStrength, foamTransitionRange, rippleNormalStrength/GlintStrength, causticColor1/2, causticScrollX/Y, fresnelAlphaInfluence, foamAlphaInfluence着色器参数
水下underwaterFogColor, underwaterFogDensity, underwaterChromaticAmount, underwaterToneIntensity, underwaterFogMultiplier水下效果
云cloudsEnabled, cloudCover, cloudScale, cloudHeight, cloudThickness, cloudVisibility, cloudGap体积云
雾fogEnabled, fogMode, fogColor, fogDensity, fogStart, fogEnd雾效
布料clothEnabled, clothConfig (13 字段), clothDebugParticles/Constraints/CollidersXPBD 布料
求解器solverSubsteps, solverTimeScale, collisionEnabled, bodyCollisionEnabled, groundCollisionEnabled物理参数
太阳sunAngle, azimuth太阳位置
灯光lightingPresetName灯光预设引用
时间流逝timeOfDayActive, timeOfDaySpeed2026-07-06 新增

UIState（通过 SetUIState → config.json.UiState） ​

字段说明
scaleUI 缩放
popupWidth弹窗宽度
accent主题色
fontFamily字体
animations动画开关
blurBg背景模糊
performanceMode性能模式
screenshotFormat/Quality截图设置
autoCameraEnabled自动机位开关（2026-07-06 新增）
autoCameraBeatsPerSwitch自动机位切换频率（2026-07-06 新增）

其他已持久化 ​

数据存储位置说明
场景文件config.json.LastScene / 最近场景 preset完整场景序列化
渲染预设Go RenderPresets用户自定义渲染预设
环境预设Go EnvPresets用户自定义环境预设
模型预设Go ModelPresets材质/变换预设
标签系统config.json.Tags模型标签
外部库config.json.ExternalPaths外部资源库挂载
下载监听config.json.DownloadWatchDir/AutoImport自动导入
快捷键绑定UIState.index_signature键位映射

三、未持久化状态（无需持久化） ​

状态原因
_fov场景序列化时已保存
_concertAngle / _concertPaused会话内临时状态
_presetAnimId动画 ID，非用户可见
各种 timer ID / DOM 引用内部实现细节
WASM Bullet 参数由场景物理级别控件管理

四、已修复的持久化问题 ​

问题修复
clothConfig 500ms 防抖 + 关闭丢数据flushEnvState() 加入 cleanupAndFlushSave()
布料调试开关重启重置clothDebug* 移入 EnvState
自动机位重启重置autoCamera* 移入 UIState
时间流逝重启重置timeOfDay* 移入 EnvState
config.ts 拆分后文档过时AGENTS.md / architecture.md / function-map.md 已更新

五、Android 文件选择 ​

Wails v3 (alpha2.105+) 原生支持 SAF 文件选择（dialogs_android.go）：

  • Dialog.OpenFile() 使用 Android Storage Access Framework
  • 选中的文件自动复制到 app cache 目录，返回真实文件系统路径
  • openFileDialog() → filepath.ToSlash(path) → 真实路径，不产生 content:// URI

目录选择（OpenDocumentTree）仍不支持，需自建 JNI bridge（非核心路径，延后）。