04 技术架构
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.gd | IslandInterface | 508 | HUD、对话框、选项、背包、商店、声音设置、提示、拾取飞入动画、语音播放 |
demo_director.gd | IslandDemoDirector | 238 | 演示视频的自动驾驶导演 |
voice.gd | IslandVoice | 229 | 动物语合成、离线语音清单、在线 TTS 请求队列和缓存、代理解析 |
actor.gd | IslandActor | 226 | 角色表现:逐帧走路、程序化动画、表情气泡、居民状态机 |
game_state.gd | IslandState | 140 | 纯逻辑状态:时钟、铃钱、背包、好感、每日限制、存读档 |
music.gd | IslandMusic | 136 | 按时段播放 BGM、交叉淡化、循环、对话时压低 |
navigation.gd | IslandNavigation | 96 | 网格、阻挡、最近可达格、A* 和路径平滑 |
prop.gd | IslandProp | 84 | 场景物件:绘制、遮挡淡化、点击判定、摇树、夜间灯光 |
ground.gdshader | — | 56 | 整片地面、水面、桥面 |
dialogue.gd | IslandDialogue | 48 | 台词抽取、去重、占位符替换 |
audio_settings.gd | IslandAudioSettings | 32 | 音量设置的读写和应用 |
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() 按顺序:
- 解析命令行参数。
--dump-voice导出后直接退出;截图和演示模式固定随机种子 842,保证可复现; - 读取
data/*.json,配置IslandState。正常游戏此时读档(路径可以在入树前注入save_path,测试用),截图和演示模式不读档; - 配置台词和寻路,加载
assets/sprites/下全部纹理; - 构建地面:一个铺满地图的多边形,挂
ground.gdshader,传入距离场纹理fields.png; - 创建
y_sort_enabled的YSortedWorld,放入桥栏杆,按objects列表生成物件,按heights表缩放到游戏内高度; - 生成玩家(有存档时放回存档位置)和居民;
- 如果存档的落地物不是今天的,刷新当天的贝壳和树枝,否则恢复剩余的落地物;
- 初始化界面和音乐(音乐在读档之后,所以开场就能放对应时段的曲子);
- 进入截图模式、演示模式或正常游戏。
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.json | 64×44 ASCII 地形、70 个物件(格坐标、占地、门口)、2 座桥、14 条路、广场、物件高度表 | tools/build_data.py 确定性生成 |
data/npcs.json | 6 位居民设定和全部 282 条台词 | 实现方按设定扩写,策划审核 |
data/items.json | 5 种物品的名字、价格、图标、堆叠上限 | 按规格 |
data/voices.json | TTS 接口地址、6 位居民的声音参数、在线开关、增益、代理 | 策划定声音,实现方定增益 |
data/music.json | 4 个时段的曲目文件、增益、循环方式,交叉淡化时长,对话压低量 | 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.py | data/map.json → assets/terrain/fields.png |
bake_font.gd | TTF → default_font.res |
gen_voice.py | npcs.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 许可。