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

精华03/1830 浏览开发日记

今日概况

今天做了什么

BUG-54 终结：TitleScreen 按钮宽度坍塌

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

在 fontSize

变化时会隐式重算 width

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

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

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

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

DWP 二次挑战：从失败到成功

这是今天的主线。上次（迭代#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 期间后台下载。

DWP 资源列表 UTF-8 修复

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

文案镜像：game-texts.txt

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

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

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

深夜收尾：记忆文档全面审计

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

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

结果比预想的差距大：

文件数 81 → 97（多了 16 个文件没被记录）
总行数 32000 → 47500（差了一万五千行）
版本号还停在 v3.1.1，实际已经是 v3.1.2
敌人种类写着"5+1种"，实际 EnemyData 里已经有 8 种了
地图层数写着"15层"，MapData 里已经是 18 层了
屏幕注册数写着"8个"，main.lua 里已经 10 个了

一项一项改完，主文档从 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+ 处差异

碎碎念