跳至内容

04 技术架构

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

4.1 工程约束

这些约束在写规格时就定下了,目的是让 AI Agent 能完全在命令行里开发和验证:

约束原因
Godot 4.7.2 stable + GDScript文本格式对 AI 友好;GDScript 避免 C# 的构建链
gl_compatibility 渲染器2D 足够,兼容性最好,headless 和截图都稳定
全程命令行,不依赖编辑器界面Agent 没法操作编辑器;所有验证都要能脚本化
主场景很薄,世界由代码按数据生成.tscn 里只有一个挂着 world.gd 的 Node2D,避免 Agent 手写复杂场景文件出错
可调内容全部放在 data/*.json改台词、价格、地图不用动代码;策划可以直接审数据
1280×720,canvas_items 拉伸,aspect = expand任意窗口大小都能铺满,界面不变形
存档 user://save.json,设置 user://settings.cfg存档和个人偏好分开,改音量不影响存档格式

scenes/main.tscn 的全部内容:

[gd_scene load_steps=2 format=3]
[ext_resource type="Script" path="res://scripts/world.gd" id="1"]
[node name="CozyIsland" type="Node2D"]
script = ExtResource("1")

4.2 模块总览

文件类名行数职责
world.gd(根节点)688搭建世界、读数据、输入、交互、昼夜、每日刷新、存档调度;截图模式编排
interface.gdIslandInterface508HUD、对话框、选项、背包、商店、声音设置、提示、拾取飞入动画、语音播放
demo_director.gdIslandDemoDirector238演示视频的自动驾驶导演
voice.gdIslandVoice229动物语合成、离线语音清单、在线 TTS 请求队列和缓存、代理解析
actor.gdIslandActor226角色表现:逐帧走路、程序化动画、表情气泡、居民状态机
game_state.gdIslandState140纯逻辑状态:时钟、铃钱、背包、好感、每日限制、存读档
music.gdIslandMusic136按时段播放 BGM、交叉淡化、循环、对话时压低
navigation.gdIslandNavigation96网格、阻挡、最近可达格、A* 和路径平滑
prop.gdIslandProp84场景物件:绘制、遮挡淡化、点击判定、摇树、夜间灯光
ground.gdshader—56整片地面、水面、桥面
dialogue.gdIslandDialogue48台词抽取、去重、占位符替换
audio_settings.gdIslandAudioSettings32音量设置的读写和应用
bridge_rail.gd—15桥栏杆的视觉节点

分层关系:

world.gd ──────────────── 编排层(读 data/*.json,持有下面所有对象)
 ├─ IslandState          纯数据逻辑(RefCounted,无节点,可单测)
 ├─ IslandNavigation     纯寻路逻辑(RefCounted)
 ├─ IslandDialogue       纯台词逻辑(RefCounted)
 ├─ YSortedWorld (Node2D, y_sort_enabled)
 │   ├─ IslandActor × 7  玩家 + 6 位居民
 │   ├─ IslandProp × 70  场景物件
 │   └─ bridge_rail × N
 ├─ IslandInterface      界面层(CanvasLayer)
 │   ├─ IslandVoice      语音(由界面持有,跟着对话走)
 │   └─ IslandAudioSettings 音量设置
 ├─ IslandMusic          音乐
 └─ IslandDemoDirector   仅 --demo 模式

纯逻辑和表现分开是这套架构最重要的一点。状态、寻路、台词都是不依赖场景树的 RefCounted 类,测试可以直接构造它们,不需要启动整个游戏。

4.3 世界构建

world.gd 的 _ready() 按顺序:

  1. 解析命令行参数。--dump-voice 导出后直接退出;截图和演示模式固定随机种子 842,保证可复现;
  2. 读取 data/*.json,配置 IslandState。正常游戏此时读档(路径可以在入树前注入 save_path,测试用),截图和演示模式不读档;
  3. 配置台词和寻路,加载 assets/sprites/ 下全部纹理;
  4. 构建地面:一个铺满地图的多边形,挂 ground.gdshader,传入距离场纹理 fields.png;
  5. 创建 y_sort_enabled 的 YSortedWorld,放入桥栏杆,按 objects 列表生成物件,按 heights 表缩放到游戏内高度;
  6. 生成玩家(有存档时放回存档位置)和居民;
  7. 如果存档的落地物不是今天的,刷新当天的贝壳和树枝,否则恢复剩余的落地物;
  8. 初始化界面和音乐(音乐在读档之后,所以开场就能放对应时段的曲子);
  9. 进入截图模式、演示模式或正常游戏。

heights 表就在 map.json 里,物件的大小可以改数据调整。

4.4 寻路

navigation.gd 用 Godot 内置的 AStarGrid2D:

  • 启发式 octile,对角移动 DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES(不允许切墙角);
  • 每个物件的 footprint 标为不可走,房子的门口格可走,作为居民的“回家点”;
  • 河格不可走,桥格可走;
  • 点到不可走的地方时,用 nearest() 找最近的可走格。

得到格子路径后做一次视线平滑(string pulling):从起点开始,能直线走到的中间点都去掉。直线检测带 5 px 的边缘余量,避免角色擦着障碍物边缘走。角色沿平滑后的折线匀速移动:玩家 150 px/s,居民 60 px/s。

角色之间不互相阻挡。这是有意的简化:6 个居民在小岛上闲逛,如果互相阻挡,很容易在窄路和桥上卡死。

测试会检查全部 1344 个可走格互相连通,随机 220 组路线不穿障碍,以及关掉所有桥后两岸确实断开(证明河是真的不可走)。

4.5 角色

actor.gd 负责角色的一切表现:

  • 逐帧走路:读取 walk_frames.json,按累计走过的距离换帧(玩家每 13 px、居民每 9 px),循环 a → p → b → p2。路线经过多段折线时按段累加距离,长帧时间也不会跳帧。
  • 程序化动画:待机呼吸(scale.y 1.00–1.02,2 秒周期);没有逐帧数据时退回旧的弹跳、摇摆、压扁。
  • 朝向:向左走时水平翻转。
  • 阴影:脚下一个半透明椭圆。
  • 表情气泡:对话时根据当前台词的情绪前缀显示 ! / ♪ / … / ?。
  • 居民状态机:IDLE(2–5 秒)→ WANDER(家附近 7 格内的随机可达格)→ 循环。freeze() 和 release() 用来在对话时停住和恢复。22:00 后走回家门口隐藏。

4.6 物件

prop.gd:

  • 点击判定:按纹理 alpha 判断,点在树冠透明角落不算点到树;地上的小物品保留更宽松的点击区域,方便拾取。
  • 遮挡淡化:玩家走到高物件后面时淡化到 0.55。判定用包围矩形近似。
  • 摇树:点果树时摇一下,掉 1–3 个苹果或椰子。
  • 夜间灯光:路灯和窗户的暖光 sprite,按时段渐变。

4.7 对话

dialogue.gd 只有 48 行。下面是两个函数和一张演示用的字典:

  • resolve():替换占位符({player}、{cp}、{time}、{day}、{other:<id>});
  • pick():从台词池抽一条,避开上一次;chat 池按好感等级向下兼容;
  • forced:一个字典("id:pool" → 下标),用来固定某句台词。正常游戏里为空,只有演示模式用它控制视频时长。

对话界面在 interface.gd:打字机效果、点击补全或推进、选项按钮、头像、名字牌、镜头拉近。显示一句话与能否整句播出是两件事,播放和回退规则见05 音频设计。

4.8 状态与存档

game_state.gd 是一个纯逻辑类,保存所有需要持久化的东西:

字段内容
时钟第几天、几点几分
铃钱、背包20 格,每格物品 id 和数量
玩家名字、位置
好感每位居民的好感值
每日标记当天是否已问候、聊天、送礼;是否初次见面
采集标记哪些果树摇过、哪些花丛摘过
落地物当天剩余的贝壳和树枝
对话去重每个池上一次说的是哪条

存档规则:

  • 原子写入:先写临时文件,再替换正式文件。写到一半崩溃不会损坏存档。
  • 保存时机:每次交互后、每 15 秒、关闭窗口时。
  • 当天采空的东西读档后不会重刷:这条是测试专门覆盖的,防止玩家靠读档刷物品。

4.9 数据文件

文件内容谁写的
data/map.json64×44 ASCII 地形、70 个物件(格坐标、占地、门口)、2 座桥、14 条路、广场、物件高度表tools/build_data.py 确定性生成
data/npcs.json6 位居民设定和全部 282 条台词实现方按设定扩写,策划审核
data/items.json5 种物品的名字、价格、图标、堆叠上限按规格
data/voices.jsonTTS 接口地址、6 位居民的声音参数、在线开关、增益、代理策划定声音,实现方定增益
data/music.json4 个时段的曲目文件、增益、循环方式,交叉淡化时长,对话压低量Batch F

build_data.py 现在只重建地图和地面距离场,不会覆盖已经验收过的台词和物品数据。

4.10 命令行模式

整个游戏有多个启动模式,都通过 -- 之后的用户参数切换:

参数用途
(无)正常游戏
--screenshot-test [--shot-dir=<路径>]用真实注入的鼠标事件走完一套流程,每步截图后退出,共 29 张。不读写正常存档,禁止真实网络请求
--screenshot-minimize-test故障注入:截图中途主动把窗口最小化一次,检验自动恢复
--dump-voice=<目录>导出 7 种动物语 beep 的 WAV 后退出
--demo自动驾驶演示,配合 Movie Maker 录视频

另外两个独立脚本:tests/run_tests.gd(自动化测试)、tools/voice_online_smoke.gd(真实联网的 TTS 冒烟测试)。

4.11 离线工具链

这是一张工程输入和产出的对照表,不是“一键找回原素材”的清单。地图可以从源稿重建;要重新抠出原来那一张角色图,得先有清单指向的原图。

脚本输入 → 输出
assets_spec.py素材提示词表(被 gen_assets.py 引用)
gen_assets.py自配图像生成服务 → _raw/<id>_<seed>.png
contact_sheet.py候选原图 → 联系表,供人工选图
process_assets.py_raw/selected.json 选中的原图 → assets/sprites/*.png + 两张检查图
gen_walk_frames.py选中立绘 → klein 改图 → _raw/walk/ 候选帧
process_walk.py_raw/walk/selected.json → assets/sprites/walk/ 35 张帧 + walk_frames.json + 检查图
build_data.py地图生成源稿 → data/map.json + 距离场
terrain_fields.pydata/map.json → assets/terrain/fields.png
bake_font.gdTTF → default_font.res
gen_voice.pynpcs.json + voices.json → TTS → assets/audio/voice/ 282 个 OGG + 清单
compose_bgm.py手写和弦与动机 → MIDI → FluidSynth → assets/audio/music/ 4 个 OGG
record_demo.py--demo + Movie Maker + ffmpeg → 演示视频
fetch_godot.py / run_godot.py受限环境下的引擎下载和启动

交付工程保留的是入选精灵、走路帧、语音、曲目和相关脚本;引擎、音色库与候选原图等不随版本控制交付。如果对应原图还在,可以按选择记录重做后处理;原图不在,就得准备生成服务、重新出候选并挑选,不能保证得到原来那一帧。

4.12 几个实现细节

  • 在线语音与离线工具分开。 当时引擎的请求组件没有自动沿用生成脚本的网络设置,游戏端另做了可配置的连接处理。固定语音命中清单时不经过此路径。
  • project.godot 的 window_*_override 比命令行 --resolution 优先。 录 1080p 视频时只能临时写 override.cfg,录完还原。
  • canvas_items 拉伸下注入鼠标事件要做坐标变换。 窗口坐标要乘 get_tree().root.get_final_transform(),否则在非 1280×720 窗口下点歪。
  • Godot 4.7.2 的音频停止由混音线程异步处理。 销毁还在播放的音乐节点时要等两个混音周期(上限 100 ms),否则 --quit-after 退出时会报资源泄漏。

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

最后更新于