11 附录:命令速查
这份速查给已经持有对应版本工程的人使用,不是公开游戏的安装或下载页。以下是当时在 cozy-island/ 工程根目录使用的 PowerShell 命令;可执行文件、服务地址和输出目录要换成自己的配置。正常游玩看11.2,复核构建看11.3,只有改素材才需要11.5–11.6。
11.1 两种启动方式
| 方式 | 命令前缀 | user:// 指向 | 适用 |
|---|---|---|---|
| 正式安装的 Godot | & '<自行安装的 Godot console 路径>' | 常规游戏用户目录 | 平时游玩、验收 |
| 工作区启动器 | python tools/run_godot.py [--record=<log>] | .tools/test-profile/(隔离) | 受限沙箱(Codex);--record 会把输出存到 test-results/ |
下文用 godot 代指第一种的完整路径;换成 python tools/run_godot.py 效果相同,只是用户目录不同(区别见 06)。
准备同版本引擎(下载到 .tools/,核对 SHA-256):
python tools/fetch_godot.py11.2 运行游戏
godot --path . # 正常游玩11.3 验收四件套
godot --headless --path . --import # ① 导入资源,应退出 0
godot --headless --path . --quit-after 120 # ② 冒烟:输出 READY: 小岛物语 | 64x44 | 70 props | 6 NPCs | day 1
godot --headless --path . -s tests/run_tests.gd # ③ 逻辑测试:输出 ALL TESTS PASSED
godot --path . -- --screenshot-test "--shot-dir=$PWD\test-results\screens" # ④ 截图(不能 headless,29 张)注意:
- 改了素材、音频或 JSON 以后,先跑 ① 再跑其他命令;
- 截图需要真实窗口,不加
--headless。截图时窗口被最小化会自动恢复; - 不要和另一个进程同时导入同一个工程。
11.4 专项命令
# 截图模式 + 故障注入:01 之后主动最小化一次,检查能否恢复
godot --path . -- --screenshot-test --screenshot-minimize-test "--shot-dir=$PWD\test-results\screens_min"
# 导出 7 个角色的动物语 beep(22050 Hz 16-bit 单声道 WAV),导出后直接退出
godot --headless --path . -- "--dump-voice=$PWD\test-results\voices"
# 独立联网冒烟;第二条的 $UnreachableTestProxy 由持有者设为不可达的测试代理,预期退出码 1
godot --headless --path . -s tools/voice_online_smoke.gd
godot --headless --path . -s tools/voice_online_smoke.gd -- "--proxy=$UnreachableTestProxy" --timeout=1
# 自动驾驶演示(实时运行,不录制)
godot --path . -- --demo
# 录制演示视频 → test-results/demo/cozy_island_demo.mp4(需要 ffmpeg)
python tools/record_demo.py
python tools/record_demo.py --size 1280x720 --out <path.mp4>11.5 重建前的准备:用到的模型和推理框架
这版把入选图片、固定台词的录音和四首背景音乐随工程保存,正常游玩不需要生成模型。例外在对话:动态时间、日期或改名后的句子未命中缓存时,开启在线语音可能访问自配服务;断网时文字照常显示,只用提示音。
总览
| 环节 | 模型 / 工具 | 推理框架 | 运行位置 | 产出 |
|---|---|---|---|---|
| 静态精灵(角色、建筑、物件) | Z-Image Turbo(int8_convrot 量化)+ 文本编码器 Qwen3 4B + VAE ae | ComfyUI | 持有者自配的图像生成服务 | 33张静态精灵 |
| 走路帧 | FLUX.2 klein 4B(以选定立绘为参考图改图)+ 同一个 Qwen3 4B + VAE flux2-vae | 同上 | 同上 | 7 个角色共 35 帧 |
| 抠图、对齐、校色、地面距离场 | 不用模型,numpy + Pillow 写的规则算法 | 本机 Python | 本机 | assets/sprites/、地面距离场 |
| 居民配音 | 六位居民各选一种中文声音 | 可配置的 /v1/audio/speech 接口 | 自备语音服务 | 282条离线固定配音 |
| 背景音乐 | 不用 AI 模型:Python 手写和弦与旋律 → MIDI | FluidSynth 2.6.1 + GeneralUser GS 2.0.3 音色库渲染,ffmpeg 做响度和编码 | 本机 | 4 首时段 BGM |
模型文件、量化权重、编码器与音色库的许可要按具体版本及用途分别核对;本次记录不是再分发或商用授权。为什么选这批走路帧,见03 美术管线;为什么四个时段最后都用了 MIDI,见05 音频设计。
ComfyUI 服务
- 兼容条件:推理环境需要支持工作流中的节点和所选量化格式,特别是
int8_convrot。 - 节点:两个工作流只用 ComfyUI 内置节点,不需要装自定义节点。
- Z-Image:
UNETLoader、CLIPLoader(typelumina2)、VAELoader、ModelSamplingAuraFlow、KSampler等; - klein:
LoadImage、VAEEncode、CLIPLoader(typeflux2)、ReferenceLatent、CFGGuider、Flux2Scheduler、EmptyFlux2LatentImage、SamplerCustomAdvanced等。
- Z-Image:
- 连接:按所用服务的本地配置启动;脚本需要的是能提交工作流的接口,不是原开发设备。加载时间与每张耗时会随环境变化。
模型文件
当时使用的是 ModelScope 上 Comfy-Org 打包的下列文件。按类型放进 ComfyUI 模型目录,或由持有者自行映射路径:
| 文件 | 放到 ComfyUI 的 | 大小 | 来源(ModelScope 仓库内路径) | 用于 |
|---|---|---|---|---|
z_image_turbo_int8_convrot.safetensors | models/diffusion_models/ | 6.2 GB | Comfy-Org/z_image_turbo:split_files/diffusion_models/ | 静态精灵 |
qwen_3_4b.safetensors | models/text_encoders/ | 8.0 GB | Comfy-Org/z_image_turbo:split_files/text_encoders/ | 两个模型共用 |
ae.safetensors | models/vae/ | 335 MB | Comfy-Org/z_image_turbo:split_files/vae/ | 静态精灵 |
flux-2-klein-4b.safetensors | models/diffusion_models/ | 7.8 GB | Comfy-Org/flux2-klein-4B:split_files/diffusion_models/ | 走路帧 |
flux2-vae.safetensors | models/vae/ | 336 MB | Comfy-Org/flux2-klein-4B:split_files/vae/ | 走路帧 |
表中各文件合计约22.7 GB,文件大小不能直接当作显存需求。更换量化格式时要同步修改脚本使用的文件名,并复核输出。
换一台机器生成
- 按上面两张表准备可用的推理服务和模型文件。
- 将
tools/gen_assets.py和tools/gen_walk_frames.py中的COMFY指向自己的服务;本文不提供原开发环境的连接配置。 - 换显卡、换量化版本或换 ComfyUI 版本以后,同一个种子出来的图会不一样。已有的选图记录(
_raw/selected.json、_raw/walk/selected.json)只对应原环境生成的原图,重新生成后要重新挑图。
配音接口
- 接口地址在
data/voices.json的endpoint,每位居民的声音、语速、音高、风格也在这个文件里。 - 批处理脚本与游戏的在线语音分别测试连接。服务、访问许可与网络出口均需自行配置,不是公开文档附带的资源。
- 动态台词未命中固定录音或缓存时,才在允许在线语音的模式下请求;截图和常规测试禁用真实请求。
本机 Python 依赖
在 Python 3.13 上测试过:
pip install numpy pillow imageio-ffmpegnumpy 和 Pillow 用于抠图、走路帧处理和地面距离场;imageio-ffmpeg 自带 ffmpeg,用于配音后处理和音乐编码。FluidSynth 和音色库的准备见下面 11.6 的“音乐”。
11.6 重建素材和数据
运行所需的成品已在对应工程中,正常运行不需要重建。以下命令用于修改内容之后;原图、候选和音频缓存不全在工程里,缺少原件要重新生成和挑选。重建后再跑一次 --import。
美术
# 通过自配 ComfyUI(Z-Image Turbo)生成原图 → _raw/<id>_<seed>.png(已存在则跳过)
python tools/gen_assets.py [asset_id ...] [--variants 2] [--seed-base 1000]
# 拼候选对比图,方便挑选
python tools/contact_sheet.py <out.png> [前缀 ...]
# 挑选结果写入 _raw/selected.json 后,抠图 → assets/sprites/*.png + 两张检查图
python tools/process_assets.py走路帧
# 用 FLUX.2 klein 4B 从选定立绘生成候选 → _raw/walk/<角色>_<pose>_s<seed>.png
python tools/gen_walk_frames.py [角色 ...] [--seeds 3,4,5,6] [--poses stepL,pass,stepR]
python tools/gen_walk_frames.py [角色 ...] --mirror # 先翻转原图再改图,得到另一只脚在前的帧
# 挑选结果写入 _raw/walk/selected.json 后,对齐、校色 → assets/sprites/walk/(35 张 + walk_frames.json)
python tools/process_walk.py地图和地面
python tools/build_data.py # 重建 map.json 和地面距离场(会覆盖手工改过的地图;不动台词和物品)
python tools/terrain_fields.py # 只手工改了 map.json 时,用它重新烘焙距离场字体
godot --headless --path . -s tools/bake_font.gd # 换了源字体后重建 default_font.res语音
# 改了 data/voices.json 的声音参数或改了台词后重跑;只会请求缓存里没有的句子
python tools/gen_voice.py
python tools/gen_voice.py --limit 5 # 开发探测:最多处理 5 句,不改 manifest报告输出到 test-results/voice_report.json,原始 MP3 缓存在 _raw/voice_cache/。
音乐
需要先准备(都放在不进版本控制的 .tools/):
- FluidSynth 2.6.1:
.tools/fluidsynth/fluidsynth-v2.6.1-win10-x64-cpp11/bin/fluidsynth.exe; - GeneralUser GS v2.0.3 音色库:
.tools/soundfonts/GeneralUser-GS.sf2; pip install numpy imageio-ffmpeg。
python tools/compose_bgm.py # 重新作曲、渲染全部四首
python tools/compose_bgm.py --only night # 只重渲染夜曲,但仍检查全部四首
python tools/compose_bgm.py --fluidsynth=<exe> --soundfont=<sf2> --ffmpeg=<exe> # 指定工具路径报告输出到 test-results/bgm_report.json。
若已有来源和使用权明确的替换曲目,先将音频放入工程,再在 data/music.json 中选它:
"morning": {
"file": "res://assets/audio/music/your_candidate.ogg",
"gain_db": 0,
"loop_mode": "crossfade",
"loop_crossfade": 3.0
}11.7 常见调整
| 想改什么 | 改哪里 | 之后要做 |
|---|---|---|
| 某位居民的台词 | data/npcs.json | python tools/gen_voice.py → --import |
| 某位居民的声音 | data/voices.json | 同上 |
| 物品售价、喜好 | data/items.json、data/npcs.json | 直接重启 |
| 背景音乐、交叉淡化时长、对话压低量 | data/music.json | --import(换文件时)→ 重启 |
| 换一张素材 | _raw/selected.json | python tools/process_assets.py → --import |
| 换一帧走路图 | _raw/walk/selected.json | python tools/process_walk.py → --import |
| 地图布局 | data/map.json(或 build_data.py) | python tools/terrain_fields.py → --import |
| 演示视频的台词 | scripts/demo_director.gd 里的 forced 设置 | python tools/record_demo.py |
11.8 输出位置
| 内容 | 路径 | 是否进版本控制 |
|---|---|---|
| 截图、日志、报告、演示视频 | test-results/ | 否 |
| 原始生成图、走路候选 | _raw/*.png、_raw/walk/*.png | 否(检查图除外) |
| 选图记录 | _raw/selected.json、_raw/walk/selected.json | 是 |
| MIDI 源文件 | _raw/bgm/*.mid | 是 |
| TTS 原始 MP3 缓存 | _raw/voice_cache/ | 否 |
| 引擎、FluidSynth、音色库、测试用户目录 | .tools/ | 否 |
| 游戏存档、声音设置、在线语音缓存 | user://save.json、user://settings.cfg、user://voice_cache/ | 否 |
本文写作中使用了 AI 辅助。文字采用 CC BY-NC-SA 4.0 许可。