跳至内容

11 附录:命令速查

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

这份速查给已经持有对应版本工程的人使用,不是公开游戏的安装或下载页。以下是当时在 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.py

11.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 aeComfyUI持有者自配的图像生成服务33张静态精灵
走路帧FLUX.2 klein 4B(以选定立绘为参考图改图)+ 同一个 Qwen3 4B + VAE flux2-vae同上同上7 个角色共 35 帧
抠图、对齐、校色、地面距离场不用模型,numpy + Pillow 写的规则算法本机 Python本机assets/sprites/、地面距离场
居民配音六位居民各选一种中文声音可配置的 /v1/audio/speech 接口自备语音服务282条离线固定配音
背景音乐不用 AI 模型:Python 手写和弦与旋律 → MIDIFluidSynth 2.6.1 + GeneralUser GS 2.0.3 音色库渲染,ffmpeg 做响度和编码本机4 首时段 BGM

模型文件、量化权重、编码器与音色库的许可要按具体版本及用途分别核对;本次记录不是再分发或商用授权。为什么选这批走路帧,见03 美术管线;为什么四个时段最后都用了 MIDI,见05 音频设计。

ComfyUI 服务

  • 兼容条件:推理环境需要支持工作流中的节点和所选量化格式,特别是 int8_convrot。
  • 节点:两个工作流只用 ComfyUI 内置节点,不需要装自定义节点。
    • Z-Image:UNETLoader、CLIPLoader(type lumina2)、VAELoader、ModelSamplingAuraFlow、KSampler 等;
    • klein:LoadImage、VAEEncode、CLIPLoader(type flux2)、ReferenceLatent、CFGGuider、Flux2Scheduler、EmptyFlux2LatentImage、SamplerCustomAdvanced 等。
  • 连接:按所用服务的本地配置启动;脚本需要的是能提交工作流的接口,不是原开发设备。加载时间与每张耗时会随环境变化。

模型文件

当时使用的是 ModelScope 上 Comfy-Org 打包的下列文件。按类型放进 ComfyUI 模型目录,或由持有者自行映射路径:

文件放到 ComfyUI 的大小来源(ModelScope 仓库内路径)用于
z_image_turbo_int8_convrot.safetensorsmodels/diffusion_models/6.2 GBComfy-Org/z_image_turbo:split_files/diffusion_models/静态精灵
qwen_3_4b.safetensorsmodels/text_encoders/8.0 GBComfy-Org/z_image_turbo:split_files/text_encoders/两个模型共用
ae.safetensorsmodels/vae/335 MBComfy-Org/z_image_turbo:split_files/vae/静态精灵
flux-2-klein-4b.safetensorsmodels/diffusion_models/7.8 GBComfy-Org/flux2-klein-4B:split_files/diffusion_models/走路帧
flux2-vae.safetensorsmodels/vae/336 MBComfy-Org/flux2-klein-4B:split_files/vae/走路帧

表中各文件合计约22.7 GB,文件大小不能直接当作显存需求。更换量化格式时要同步修改脚本使用的文件名,并复核输出。

换一台机器生成

  1. 按上面两张表准备可用的推理服务和模型文件。
  2. 将 tools/gen_assets.py 和 tools/gen_walk_frames.py 中的 COMFY 指向自己的服务;本文不提供原开发环境的连接配置。
  3. 换显卡、换量化版本或换 ComfyUI 版本以后,同一个种子出来的图会不一样。已有的选图记录(_raw/selected.json、_raw/walk/selected.json)只对应原环境生成的原图,重新生成后要重新挑图。

配音接口

  • 接口地址在 data/voices.json 的 endpoint,每位居民的声音、语速、音高、风格也在这个文件里。
  • 批处理脚本与游戏的在线语音分别测试连接。服务、访问许可与网络出口均需自行配置,不是公开文档附带的资源。
  • 动态台词未命中固定录音或缓存时,才在允许在线语音的模式下请求;截图和常规测试禁用真实请求。

本机 Python 依赖

在 Python 3.13 上测试过:

pip install numpy pillow imageio-ffmpeg

numpy 和 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.jsonpython tools/gen_voice.py → --import
某位居民的声音data/voices.json同上
物品售价、喜好data/items.json、data/npcs.json直接重启
背景音乐、交叉淡化时长、对话压低量data/music.json--import(换文件时)→ 重启
换一张素材_raw/selected.jsonpython tools/process_assets.py → --import
换一帧走路图_raw/walk/selected.jsonpython 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 许可。

最后更新于