跳至内容

09 批次开发日志

所属专题:小岛物语 · Godot 游戏开发

本文逐批记录 v1 和 Batch A–G:起因、内容、验收发现、关键数据和改动文件。时间取自会话记录(UTC),“派发”指任务书交给 Codex 的时刻。实测数据的原始输出见 IMPLEMENTATION_NOTES.md。

总览

批次派发主题实现断言数截图数
v110-16 17:20完整垂直切片Codex901517
A18:04抠图残留、灯光偏绿Codex901517
B18:21地图、地面、桥Codex1221018
C18:39桥栏杆、界面、动物语导出Codex1226519
D10-17 02:50逐帧走路Codex1256128
E04:08居民 TTS 配音Codex1459528
E-fix04:37(04:43 成功)代理、在线音量、截图稳定性Codex1491528
F05:03四时段 BGM、声音设置、最小化恢复Codex1562729
F-fix05:26测试存档隔离、夜曲静音Codex15628 / 1566129
G07:39演示视频Claude约 1.56 万29

总览是各批当次执行的断言次数,并非独立用例数或覆盖率。F 之后的音乐曲线按实际帧采样,次数会浮动;F-fix 一栏依次是空目录、保留正常用户目录两次启动的结果,不代表成功读到了用户原档。


v1:完整垂直切片

  • 派发:10-16 17:20,任务书 codex_task1,约 42 分钟后完成。
  • 起因:制作人要一款用鼠标操作的 2D 小岛游戏。派工前我已写好 DESIGN.md,并用图像生成服务生成、选定了33张素材。
  • 内容:
    • 世界、寻路、角色、物件、对话、好感、背包、商店、存档、昼夜、UI、动物语 beep;
    • 地图和台词生成脚本 build_data.py、抠图脚本 process_assets.py;
    • 测试脚本,以及 17 张图的截图模式;
    • 受限环境启动器 run_godot.py 和引擎下载脚本 fetch_godot.py。
  • 验收:
    • 该轮逻辑脚本执行9015次断言,0次失败;
    • 变异测试三处都被抓住(见 06);
    • 看图发现一串视觉问题:栅栏格子里残留浅绿背景、路灯偏绿、路是矩形、海岸锯齿、桥顺着河铺、商店面板大片空白;
    • 一次 --import 崩溃,原因是和 Codex 同时导入同一个工程。
  • 之后:用户要求拆小批次。

Batch A:抠图与灯光

  • 派发:18:04。
  • A1 抠图:封闭空隙和四边连通背景共用一套颜色判定,33 张素材全部重新生成;新增 #203020 深色底的检查图 _raw/cutout_check_dark.png。
  • A2 灯光:不再用加法光,改为 #ffc870 的透明混合径向 sprite,路灯半径 110 px,18:00–19:00 渐亮、05:00–06:00 渐灭;窗户使用同样的暖色和时段。
  • 验收:逐张看深色底检查图,放大复查栅栏、兔子、鸭子、路灯;看 01_daytime 和 12_night。测试脚本未改,9015 条照旧通过;另有一个不进版本控制的灯光检查脚本,覆盖 9 个时间点。

Batch B:地图、地面与桥

  • 派发:18:21,任务书 codex_task2b(节选见 08)。
  • 内容:
    • 广场改成约 8×6 格的椭圆;道路改成宽 1.1–1.35 格的平滑曲线;
    • 土路占陆地 174/1468(11.85%),烘焙后的视觉土路 13.07%,都低于 15%;
    • 两座桥东西向横跨南北向的河,各 2×2 格,两端各延伸 16 px 到岸上;
    • 海岸和河岸用 512×352 的距离场烘焙,岸线偏移 10 px,加上噪声扰动不超过半格 16 px;
    • 物件重新摆放,从 76 个减到 70 个,落在海里的椰子树移到沙滩。
  • 新增:tools/terrain_fields.py、assets/terrain/fields.png。
  • 修改:build_data.py、map.json、ground.gdshader、world.gd、run_tests.gd。
  • 验收:git diff --stat -- data/ 只有 map.json 变化;新增截图 03_river_bridge,共 18 张;断言增到 12210。

Batch C:栏杆、界面与动物语导出

  • 派发:18:39。
  • 内容:
    • 桥两侧加 21 px 矮立柱和横木(bridge_rail.gd),纯视觉节点,不影响寻路;
    • HUD 铃钱改成紧凑的一行;岛名加阴影和描边,描边颜色随昼夜切换;
    • 商店面板按物品行数自适应高度,最小 200 px,长列表可滚动;空状态显示狸叔的台词;打开商店时隐藏对话框;
    • 动物语合成集中到 voice.gd;新增 --dump-voice=<目录>,导出 7 个 WAV。
  • 验收:测试逐字节比对导出 WAV 和游戏实际播放的 PCM;新增截图 07b_shop_empty,共 19 张;断言 12265。
  • 阶段交付:10-16 18:49,第一阶段结束。

Batch D:逐帧走路

  • 起因:10-17 01:49,用户希望“走路的时候更逼真一些,身体四肢的动作那种”。
  • 前期(Claude):
    • 对比三种方案:Qwen-Image edit、H3 首尾帧视频、FLUX.2 klein;
    • 用户选定 klein,我写了 gen_walk_frames.py,为 7 个角色生成约 200 张候选;
    • 人工挑选 a / p / b / p2 四帧,记录在 _raw/walk/selected.json。
  • 派发:02:50。
  • 内容(Codex):
    • process_walk.py:复用原有抠图接口,用头部区域对齐,统一缩放,两级校色;输出 35 张帧和 walk_frames.json;
    • actor.gd:按行走距离换帧(玩家每 13 px、居民每 9 px 换一帧),起步时左右脚交替;停下或进入对话时回到待机。
  • 验收:
    • 新增 18_three_walking 和 8 张 walk_sequence,截图共 28 张;
    • 38 个受保护文件 SHA-256 不变;
    • 断言 12561;
    • 03:11 验收通过。

Batch E:居民 TTS 配音

  • 起因:03:59,用户要求用 TTS 网页的接口给每个居民配声音,并加背景音乐。
  • 前期(Claude):探测接口参数和 UA 要求,为六位居民试听、选定声音和参数。
  • 派发:04:08。
  • 内容:
    • gen_voice.py 离线预生成 282 条语音,共 1081.67 秒;12 条含 {time}/{day} 的动态句跳过,0 条失败;
    • 处理流程:裁剪首尾静音,轻度压缩,归一化到 -16 LUFS,编码 OGG;
    • 新增 default_bus_layout.tres(Music / Voice / SFX 三条总线);
    • voice.gd 支持在线请求、磁盘缓存,以及迟到或过期的请求结果不覆盖当前台词。
  • 验收:测试断言 14595;看了 03_dialogue 和 07_shop。我在真实环境联网冒烟时发现两个问题:
    • Godot 的 HTTPRequest 不读代理环境变量,在线请求不通;
    • 在线片段比离线片段小声。
  • 多次重跑截图,还发现截图偶发失败:点击被识别成拖动。

Batch E-fix:代理、在线音量、截图稳定性

  • 派发:04:37。前两次因 Codex 服务端容量不足而失败(“Codex is at capacity”),04:43 第三次派发成功。
  • 内容:
    • 游戏端可使用显式连接设置,也能沿用运行环境设置;例外主机按规则直连;
    • 在线片段加 4.5 dB;按 MP3 时长 - 0.9 s 估算打字速度;
    • 新增 tools/voice_online_smoke.gd,单独做一次真实联网请求;
    • 截图模式在同一轮完成鼠标按下和松开,并等渲染、布局、相机、寻路都就绪后再操作。
  • 验收:
    • 真实代理请求返回 200,共 25632 字节;不可达代理按预期超时失败;
    • 截图连续三次通过;
    • 断言 14915。

Batch F:四时段 BGM

  • 前期(Claude):
    • 用户表示“可以生成 MIDI 的背景音乐,不一定非要用大模型”,于是两条路线同时做;
    • Codex 负责 MIDI 作曲和播放系统;我用 ACE-Step 为每个时段生成 3 首候选,共 12 首,用于对比。
  • 派发:05:03。任务书还附带两项:AI 曲目要能通过配置替换;截图测试在窗口被最小化时不能静默卡死。
  • 内容:
    • compose_bgm.py:自写 MIDI,32 小节,曲式 A/A’/B/A’’;用 FluidSynth 渲染;截取第二遍实现无缝循环;归一化到 -20 LUFS;四首共 5.8 MB;
    • music.gd:双播放器,4 秒等功率交叉淡化;对话时音乐压低 6 dB;
    • audio_settings.gd:设置面板,数据存在 settings.cfg;
    • 截图模式用独立计时器检测最小化并恢复窗口;新增 --screenshot-minimize-test;
    • 新增截图 01b_audio_settings,共 29 张;断言 15627。
  • 验收发现:
    • 我直接用正式安装的 Godot 跑测试,挂了 43 条,而 Codex 环境全部通过;
    • 夜曲循环点有约 1 秒完全静音(我测得 995 ms,Codex 解码测得 1089 ms)。
  • 用户选择:05:38 我发布了试听页,每个时段放 MIDI 版和 ACE-Step 候选;05:43 用户四个时段全选 MIDI。

Batch F-fix:测试存档隔离与夜曲静音

  • 派发:05:26,任务书要求先判断 43 条失败属于“测试隔离问题”还是“游戏 bug”。
  • 结论:属于测试隔离问题。测试读到了真实用户目录里的 save.json,music.gd 没有改。
  • 内容:
    • world.gd 支持注入 save_path;
    • 每次测试使用独立临时目录,存放存档、设置和语音缓存;
    • 加入只读保护:真实存档可读时,才比较测试前后的 SHA-256;
    • 夜曲的弦乐 pad 每小节延音 4.45 拍,跨过下一小节的起音;
    • compose_bgm.py --only night 只重渲染一首;生成器自检时,任何超过 250 ms 的静音都会报错。
  • 验收:
    • 夜曲最长静音 0.29 ms,循环接缝处 0 ms;其余三首的 OGG 哈希不变;
    • 修复后两次启动都通过:保留正常用户目录15661次断言、新建空目录15628次。该轮沙箱无法读取真实存档,两份日志都明确没有完成原档字节对照,也没有在原档可读条件下重现旧故障。详见验收附录的 F-fix 记录。

Batch G:演示视频

  • 起因:07:36,用户要一段不超过 1 分钟的玩法视频。
  • 派发:07:39 交给 Codex,随后 Codex 额度用完,用户说“codex 没有额度了,你得自己上了”,由 Claude 自己实现。
  • 内容:
    • scripts/demo_director.gd:自动驾驶导演;
    • tools/record_demo.py:Movie Maker 录制,ffmpeg 编码和响度归一化;
    • IslandDialogue.forced:固定演示用的几句台词;
    • 测试新增 _test_demo_isolation。
  • 成品:08:04 完成。批次记录的成片为57.4秒,1920×1080,48 MB,-15.8 LUFS。想看“摇树、送苹果、卖贝壳”怎样连成一段,见07 演示视频制作手记,这里不提供工程或成片下载。

文件增长一览

批次新增的主要文件
v1scripts/ 下的 world、actor、prop、navigation、dialogue、game_state、interface、ground shader;data/ 下的地图、居民、物品;tools/ 下的 gen_assets、process_assets、build_data、fetch_godot、run_godot;tests/run_tests.gd
Btools/terrain_fields.py、assets/terrain/fields.png
Cscripts/bridge_rail.gd、scripts/voice.gd
Dtools/gen_walk_frames.py(Claude)、tools/process_walk.py、assets/sprites/walk/(35 张图 + JSON)
Etools/gen_voice.py、data/voices.json、assets/audio/voice/(282 条 OGG + manifest)、default_bus_layout.tres
E-fixtools/voice_online_smoke.gd
Ftools/compose_bgm.py、scripts/music.gd、scripts/audio_settings.gd、data/music.json、_raw/bgm/*.mid、assets/audio/music/*.ogg
Gscripts/demo_director.gd、tools/record_demo.py

本文写作中使用了 AI 辅助。文字采用 CC BY-NC-SA 4.0 许可。

最后更新于