开发日记 — 2026年3月17日（周一） 节拍前夜 · 第49天

今日概况

今天做了什么

跨了好几个会话的按钮宽度 bug 终于修了。根因是 Button:SetStyle\(\)

在 fontSize

变化时会隐式重算 width

，而此时 text=\&\#34;\&\#34;

导致宽度被压到 max\(64, 0\+32\) = 64

。修法很简单——SetStyle 后单独调一次 SetWidth。

真正的收获不是这个修复本身，而是过程中总结出的 debug-stuck-guard 规则：bug 修两轮不行就别继续猜了，加日志看数据。这条教训写进了 CLAUDE.md，以后应该能少走弯路。

这是今天的主线。上次（迭代#037）DWP 实验以失败告终——Boot 阶段黑屏、占位纹理不可控、2D 图片密集型项目和 DWP 天然不兼容。但加载时间的问题还是得解决，所以换了个思路重来。

新方案的核心想法：不在 Boot 阶段搞事，而是把 LoadingScreen 做成正经的 UI Widget，用引擎自己的 NanoVG 上下文渲染，通过 cache:DownloadResources\(\)

主动拉取全部资源。下载没完成就不切屏，玩家永远看不到白色占位纹理。

下午 16:53 写完第一版，17:24 重写为 UI Widget 架构，17:32 修了 Web 端卡在 0% 的问题（手动驱动 OnUpdate + 快速完成跳过动画），到 18:51 完成了 v2 美化版。三个小时，四轮迭代，从概念到成品。

LoadingScreen v2 最终效果：

选卡背景图 + 暗色渐变遮罩 + 暗角聚焦

Logo 替代文字标题，带紫色微光晕

进度条六层渲染：阴影→暗色轨道→紫色渐变填充→顶部高光→流动光效→末端发光点

DrawingMachine 卷纹九宫格装饰边框

鼠标移动生成紫色光点粒子，点击产生涟漪扩散

DWP 兼容：nvgCreateImage 每 0.5s 尝试加载，纹理就绪前用纯 NanoVG 兜底

初始加载从 120MB 降到约 1.8MB（仅脚本），剩余资源在 LoadingScreen 期间后台下载。

美化完没多久就发现新问题——ALL_RESOURCES 里的中文路径在某些环境下 UTF-8 编码损坏，导致资源匹配失败。花了一个小时做全量转义清理，顺便给下载失败加了显式报错，不再静默吞错。

晚上换个脑子，做了个一直想做的事：把游戏里散落在各处 Lua 文件里的文案全部镜像到game\-texts\.txt

。从 18 章扩展到 25 章，覆盖了乐器店、乐录、奖励、标题、通关、生涯、教学时停、新手指南、战斗界面等所有屏幕的文案。同时标记了已废弃的内容（TutorialModal、坚韧 tenacity 死代码），然后把对应的废弃代码也一并清理了——删了 TutorialModal 整个文件（118 行），移除了 RhythmEngineV2 和 BattleScreenV2 里残留的 tenacity 相关代码。

把 game-texts.txt 纳入了记忆文档体系的级联读取和自动同步清单，以后改文案时 AI 会自动同步。

做了一件拖了很久的事：把源代码和记忆文档逐行对账。

上次认真同步文档大概是 v3.0 发布前后，之后连续做了模块化拆分、废弃代码清理、新控件开发，文档就一直没跟上。花了两个小时，把 97 个 Lua 文件的行数全部重新统计，和文档里记录的 81 个文件 / 32000 行逐一比对。

结果比预想的差距大：

一项一项改完，主文档从 v2.6.0 更新到 v2.7.0。子文档（架构与系统、规范与历史）也检查了一遍，里面的旧数据都是历史快照，如实保留没动。

LoadingScreen 第一版在 Web 端卡在 0% 不跳转。根因是 Web 平台资源已在 VFS 里，`DownloadResources` 的回调瞬间完成，但 LoadingScreen 的 OnUpdate 还没被调用过，`displayProgress_` 停在 0。修法：手动驱动一次 OnUpdate，加上快速完成时跳过动画直接切屏。

DWP 资源列表的 UTF-8 问题也费了点时间，240 条资源路径逐一检查。

文档审计比较顺利，没有技术卡点。唯一花了点时间的是判断子文档里的\"15层\"\"v3.0.0\"该不该改——最终确认它们是特定版本的历史记录，改了反而不准确。

项目总代码量：47,744 行（104 个 Lua 文件）

版本跨度：v1.16.0 → v1.18.1（3 个版本）

迭代编号：#037、#040、#041

LoadingScreen 重写：\~580 行

game-texts.txt：25 章，约 1000 行文案镜像

清理废弃代码：删除 TutorialModal（118 行）+ tenacity 相关（约 40 行）

初始加载体积：\~120MB → \~1.8MB

文档审计：v2.6.0 → v2.7.0，修正 97+ 处差异

今天从下午干到凌晨，干了四件大事：BUG-54 收尾、DWP 翻盘、文案系统建立、记忆文档审计。每件单独拎出来都是一个完整的工作单元，一天全做完了，有种把待办清单一口气清空的爽感。

DWP 的故事挺有意思。上次的失败不是方向错了，是切入点错了。Boot 阶段搞 NanoVG 就是在和引擎的初始化时序较劲，注定不会顺利。换成 UI Widget 方案以后，所有东西都在引擎的正常生命周期里，一切顺理成章。有时候退一步换个角度，比死磕更有效率。

六层渲染的进度条是今天最满意的细节。加载屏是玩家看到的第一个画面，值得花功夫打磨。

深夜的文档审计不\"刺激\"——没有新功能、没有炫酷效果，就是把文档和代码对齐。但第50天了，代码从零写到快五万行，这种基础设施工作其实很重要，不然 AI 助手每次开会话都在用过时的信息做判断。

  （注：文档部分内容可能由 AI 生成）#开发日志 #节拍前夜