《我真没让他们建城啊！》开发者日志 08

—— 先接上线，再让人看见 今天收到了九条玩家反馈，分三轮砸过来。 修完之后我发现，它们其实是同一件事的九个侧面： 写好的，不等于接上了；接上了，不等于玩家看得见。

一个函数定义了却从没被调用过；一个开关把 56 个音效全关掉了； 一个面板的回调正常触发，但字一个也画不出来。 这三种"看不见"，藏得比 bug 深。

日期： 2026-10-17 当前进度： 修复 9 条玩家反馈；接上 3 个"定义了但从未生效"的军事效果；新增远征帐篷、稳定食物来源建村；恢复全部音效；字号全局放大；新增常驻引导条与结算原因说明；修复玩法/设置面板打不开

写在前面：三种不同的"看不见" 今天收到的反馈，按玩家的话说，是这些：

1 建筑太近，希望改成到达一定路程修建帐篷 2 拥有稳定食物来源建村 3 军事这块好像没有启用 4 缺乏游戏内音效 5 字还巨小 6 毫无引导，不知道干什么，不知道在干啥 7 挂了也不知道为什么挂 8 选项也不知道干啥的 9 主界面玩法和设置按钮打不开 九条反馈，我一开始以为是九个不同的问题。修到最后才看明白——它们是三种"看不见"：

类型 含义 例子 定义了，但没接线 代码写好了，没有任何地方调用它 军事三效果 写了，但被关掉/藏起来 功能是通的，但玩家接触不到 音效开关、引导条 以为能用，但环境不支持 本机跑得通，玩家设备上不行 字体、分辨率、双通道 第三种最阴——因为开发环境里它看起来完全正常。

一、军事"好像没启用"——因为真的没启用 玩家这条反馈的语气很微妙：“军事这块好像没有启用”。

"好像"两个字说明他不确定——是没做？还是做了没生效？还是他没用对？

我搜了一下，答案是第二种，而且比我想的更彻底：

bash

复制 $ rg -n "HasBarracksCover" scripts/ Buildings.lua:303:function Buildings.HasBarracksCover(x, y) 只有定义，零次调用。

再看另外两个军事设施：

lua

复制 { id = "watchtower", desc = "半径内小人战斗力 +40%,并能预警野兽" }, { id = "wall", desc = "阻挡野兽的路径" }, 瞭望塔的"预警野兽"——没有对应代码 围墙的 effect = "block"——Buildings.GatherBonus / CombatBonus 都不处理 block，没有任何消费方 三个军事设施，三个效果，全是"写在了描述里，没写进代码里"。

1.1 为什么会这样 回头看，这个坑是分两批踩的：

第一批（v3）：设施定义和 desc 一起写的。desc 是"打算做成这样" 第二批（v4/v5）：加了 combat 效果的计算，但只处理了 combat 一种类型 block 和"清剿"就这么留在了描述里，没人回头核对过。

更尴尬的是，HasBarracksCover 那个函数——它写出来了，注释还写着"决定小人是否主动清剿野兽"——就是没接上去。

一条经验：函数写出来不等于接上了。 rg "函数名" | wc -l 如果是 1，那这个函数从来没被调用过。

1.2 顺带发现：兵营一局基本见不到 查兵营的解锁条件时发现还有一层：

{ id = "barracks", unlock = "twoSettlements", ... } twoSettlements 意味着要先养出两个聚落才能解锁兵营。而按数值设计，一局 15 分钟里能稳定长出两个聚落已经算强者了——所以大部分玩家的整局里，兵营这个设施压根不会出现。

这就是"军事没启用"观感的另一半原因：不是没生效，是没机会生效。

1.3 修法：三个效果逐个接线 兵营清剿——新增 Buildings.MilitaryCover(x, y)，一次遍历同时返回瞭望塔/兵营的覆盖状态。兵营覆盖内的成年人以 BarracksHuntScore = 82 主动猎杀感知范围内的野兽：

lua

复制 local huntScore = barracks and CC.BarracksHuntScore or (watchtower and CC.WatchtowerHuntScore or U.BaseWork) 82 这个值是算过的：高于日常工作（45），低于快饿死时的觅食（>80）——保证"有仗打时先打仗，快饿死时先吃饭"。

瞭望塔预警——覆盖内的小人感知半径 ×1.8：

if watchtower then senseRadius = senseRadius * CC.WatchtowerAlertMul end 狼还没靠近就被发现，恐惧更早积累、更早逃离或组织防御。而且这个判断只在有狼时才做（if #W.wolves > 0），平时零开销。

围墙阻挡——这是三个里最实的一个。加了 W.wallCells 登记墙格，然后：

W.FindPath(..., avoidWalls) 新增一个参数，野兽寻路时把墙格当不可通行 狼的移动循环里加兜底检查（防止寻路后墙才立起来） DestroyStructure 里同步清除墙格登记 关键设计：避墙只对野兽生效。小人寻路不传这个参数，不受自己建的墙影响——否则他们会被自己围死。

1.4 验证：7/7 全过 写了个专项诊断脚本，把三个机制逐条验证：

[PASS] 无食物热点不立村 -- 清掉 8 处食物,立村数=0 [PASS] 帐篷在规定路程外 -- 最近帐篷距核心 7.8 格(要求>=6) [PASS] 帐篷计入人口上限 -- 当前上限=103 [PASS] 兵营覆盖查询生效 -- MilitaryCover(s2)=(watchtower=false,barracks=true) [PASS] 兵营覆盖内主动清剿野兽 -- 狼被击杀=true [PASS] 狼寻路绕开围墙 -- 有墙路径=true,穿墙=false,普通寻路仍可穿=true [PASS] IsWall 查询 第三条 狼寻路绕开围墙 的断言值得说一下：它同时验证了两件事—— 野兽的路径不含墙格，而普通寻路（小人用的）仍然可以穿墙。 只验一半的话，很容易"修好了野兽，堵死了小人"。

二、建筑太挤——一个被"影响半径"卡住的设计 玩家说"建筑太近"，希望"到达一定路程修建帐篷"。

我先去看建筑到底建在哪：

local cx, cy = FindBuildSpot(s, (s.level or 1) + 2, (s.level or 1) + 6) FindBuildSpot(s, minR, maxR) —— 所有自建设施都落在聚落核心外 3~7 格。1 级聚落的影响半径只有 4 格，所以建筑全挤在村口那一小圈里。

但真正的根源在更下面一层：

lua

复制 function Buildings.CanAfford(kind, cx, cy) local s = W.SettlementAt(W.Center(cx, cy)) if not s then return false, "必须在聚落附近建造" end ... W.SettlementAt 只返回影响半径之内的聚落。也就是说：任何建在村外的设施，连"够不够资源"这一关都过不了，直接被拒。

所以"建筑太近"不是 FindBuildSpot 的半径问题，是整个建造逻辑从根上就禁止了往外建。

2.1 修法：帐篷，以及一条新的建造规则 改法分两步：

第一步，CanAfford 改用 W.NearestSettlement(x, y, maxDist)——不再要求目标格在影响半径内，只要最近的村子在 14 格以内就行（走得动、运得动）。

第二步，新增「帐篷」设施和一套远征逻辑：

lua

复制 B.OutpostConfig = { TentMinDist = 6, -- 离聚落核心的最小距离(Cell) TentMaxDist = 12, -- 最远距离 TriggerRatio = 0.62, -- 人口 >= 容量 × 0.62 时开始想扩张 MaxPerSettlement = 8, } 帐篷不需要任何知识——扩张是生存本能，神不用教。触发条件也刻意选得不一样：

住房的触发是"资源够了就建" 帐篷的触发是"人口逼近容量了才建"——人多得挤不下，他们才往外走 选址时按食物资源打分（foodUnits - 距离 * 0.3），食物强偏好、距离弱偏好——毕竟走太远运输就吃力了。

这里有个设计上的呼应值得一提： 帐篷建在有食物的地方 → 人聚过去 → 附近食物够稳 → 新的村庄从帐篷边长出来。 这和第三节的"稳定食物来源建村"是同一条链的两端。

三、建村——光有人挤在一起不算 玩家说"拥有稳定食物来源建村"。

查了原来的建村条件：

lua

复制 if sleep > S.SleepTotal and fear < S.FearAverageMax and W.ResourcesNear(cx, cy, S.ResourceRadius) >= S.NearbyResourceMin then ResourcesNear 数的是所有资源——食物、木材、石头加在一起。也就是说：一片全是石头的荒地，只要石头够多，也能立村。

这在逻辑上是说不通的。人聚在一起住下的前提，是有得吃。

3.1 修法 新增 StableFoodNear(cx, cy)，只看食物（food）和农田（farm）：

lua

复制 local foodUnits, hasFarm = StableFoodNear(cx, cy) if hasFarm or foodUnits >= S.FoodSourceMin then 两条路径任一满足即可：

有农田 —— 农田会再生，是"稳定"的标志 或食物总量 ≥ 10 这个设计有个隐含的好处：它让"教农耕知识"变得有回报。 农田是农耕知识解锁的，而农田又直接决定新村庄能不能立起来—— 知识 → 农田 → 新聚落，这条链现在是通的。

四、没有音效——56 个文件，一个开关关掉了 玩家说"缺乏游戏内音效"。

我第一反应是"音效没做完？"——去数了一下：

bash

复制 $ ls assets/audio/sfx/*.mp3 | wc -l 56 56 个音效文件，全都在。

然后打开 AudioManager.lua，第 116 行：

lua

复制 -- [诊断] 真机 UI 消失排查:临时禁用全部音效(见 Audio.Play 内说明),验证后改回 false Audio.silent = true 一个临时诊断开关，忘了改回来。

注释写得很清楚：当初是为了排查"真机 UI 消失"，怀疑音频播放和渲染管线冲突，所以把音效全关了做对照实验。后来问题定位到别处（双通道竞态，见第九节），但这个开关一直留在了 true。

而 Audio.Play 第一行就是：

if Audio.silent then return end 56 个音效，一个都没响过。

一条经验：临时诊断开关是定时炸弹。 它不会报错、不会警告，只是安静地把功能关掉。 写完诊断代码的那一刻，就该给自己留一条 TODO—— 或者更好：让它的默认值是"开启"，只在需要时才临时关掉。

改回 false，并把注释改写成"正常游戏必须为 false"，说明它的用途和关闭条件。

五、字太小——1280×720 的账，手机不认 玩家说"字还巨小"。

这个问题的账其实很清楚。游戏的 UI 是按设计分辨率 1280×720 手绘的，然后用 CONTAIN 模式缩放到实际屏幕：

lua

复制 Camera.designW, Camera.designH = 1280, 720 local scale = math.min(availW / Camera.designW, availH / Camera.designH) 而手机横屏的逻辑分辨率，注释里写着：

iPhone 横屏 844×390、安卓 915×412 算一下缩放比：

390 / 720 = 0.542 0.54 倍。 一个 14px 的设计字号，到屏幕上只剩 7.6 物理像素。

这在桌面（1280×720，缩放 1.0）上完全没问题——所以在开发机上永远看不出来。

5.1 修法：一个系数，而不是重排布局 按理说应该重新设计一套自适应布局。但那意味着改动整个 Render.lua 的绝对坐标——风险太大，而且我今天已经要改九件事了。

所以我选了一个更小的手术：全局字号系数。

lua

复制 local FONT_SCALE = 1.2

local function Text(x, y, size, str, col, align) nvgFontSize(vg, size * FONT_SCALE) 关键是：所有文本都从 Text() / Pr.Text() 这两个出口走。所以改这两处，全局生效。

连带 main.lua 里那个独立的提示文本出口（它直接调 nvgFontSize），也一起接上了同一个系数：

nvgFontSize(nvgCtx, 14 * R.FONT_SCALE) 一条经验：把改动收敛到一个出口，比改一百个调用点安全得多。 今天能用一个系数解决字号，是因为当初写代码时所有文本都走了同一个函数。 这是"顺手的好设计"在关键时刻的回报。

六、不知道干什么——目标指引藏在收起的面板里 玩家连着两条反馈：“毫无引导，不知道干什么”、“不知道在干啥”。

查下来，目标系统其实早就写好了：

lua

复制 function Systems.CurrentGoal() -- 第 1 档:立碑。这是全作最核心、也最反直觉的机制,必须第一个教会玩家。 if taught == 0 then return { icon = "🗿", title = "立起第一块石碑", ... } end ... 一个完整的阶梯：立碑 → 领悟 → 自建 → 农耕时代 → 第二个聚落 → 商路 → 铁器时代 → 收集图鉴。带进度、带提示、做完一档自动换下一档。

问题是它显示在哪。

它挂在"世界态势"面板的底部。而这个面板有两个致命设定：

默认收起（Camera.situationOpen 打开时才是展开的，收起时只剩一个 132px 的小标签） 只在没有紧急事件时才显示目标： lua

复制 local urgent = false for _, it in ipairs(items) do if it.sev >= 85 then urgent = true; break end end if not urgent then -- 才把 goal 加进去 end 也就是说：只要地图上有狼、有火、有人挨饿，目标指引就消失了。 而一个 15 分钟的局里，"有紧急事件"几乎是常态。

结果就是：这条精心设计的引导链，玩家几乎从没看到过。

6.1 修法：常驻引导条 新增 DrawGuideBar()，固定在顶部状态栏正下方：

┌─────────────────────────────────────────┐ │ 🕐 3:24 👥 42/120 🏠 3 ✨ 68/100 🌾 农耕 │ ← 状态栏 ├─────────────────────────────────────────┤ │ 🎯 🌾 把文明带进农耕时代 2 / 2 │ ← 引导条(常驻) │ → 时代资本 = 人口 + 建造 + 余粮,攒够了就晋级 │ └─────────────────────────────────────────┘ 三件事：

常驻 —— 不受"紧急事件"影响，永远显示 带进度 —— “2 / 2” 让玩家知道还差多远 带做法 —— “→ 时代资本 = 人口 + 建造 + 余粮”，只说"做什么"玩家还是会卡住 同时给开场独白补了两行——原来只说"他们不知道该做什么 / 你也不能命令他们"，但没告诉玩家这一局的目标是什么：

lua

复制 Text(sw / 2, sh / 2 + 30, 15, "你能做的,是改变他们的处境 —— 投放、立碑、定法则。", ...) Text(sw / 2, sh / 2 + 56, 15, "看他们自己长出村庄、城市,或是走进新的时代。", ...) 开场独白从 2.4 秒延长到 3.4 秒——多两行字，得给够阅读时间。

6.2 一个布局上的小账 引导条插在状态栏和工具栏之间，工具栏必须往下让位。我一开始把它做成"有进度条时 66 高、没有时 56 高"的动态高度——然后意识到工具栏没法知道它多高。

改成固定 46 高、紧凑两行：第一行目标 + 进度，第二行做法。工具栏用一个确定的偏移量避让就行。

一条经验：绝对布局里，"动态高度"是给下游挖坑。 如果一块区域的高度会影响另一块区域的位置，把它定死。

七、挂了也不知道为什么挂 玩家说"挂了也不知道为什么挂"。

我去看结算页——它显示称号（“农耕文明”）、显示数据（人口/出生死亡/道路长度）、显示编年史。但从不解释这一局为什么结束。

而游戏其实有三种结束方式：

lua

复制 Systems.endReason = extinct and "extinction" or "time" -- 以及叛神成功时的 "apostasy" 玩家看到的是同一个结算页，分不清自己是"活到了最后"还是"中途灭绝"。

7.1 修法：先说清"为什么"，再说成绩 新增一张结束原因卡片，放在称号下方、数据上方：

lua

复制 local END_REASON = { time = { icon = "⏳", title = "时间到了", desc = "十五分钟的世界走到了尽头。文明留在它自己长成的样子。", tip = "想看到更远的时代,试试教更多知识、把人口养得更大。" }, extinction = { icon = "💀", title = "他们灭绝了", desc = "最后一个豆人也倒下了。这片土地重新变得安静。", tip = "灭绝多因食物断供或野兽失控 —— 早点投食、教农耕知识可稳住人口。" }, apostasy = { icon = "🗼", title = "通天塔建成了", desc = "他们造了一座塔,爬上去,找到了你。这是唯一的失败结局。", tip = "苦难会累积成觉醒 —— 用投食安抚,或及早用天罚镇压。" }, } 每条三段：结论（为什么结束）+ 描述（发生了什么）+ 建议（下次怎么办）。

最后一段是我觉得最值钱的——玩家失败时最需要的不是安慰，是"下次怎么做"。

八、选项不知道干啥——诗化描述的问题 玩家说"选项也不知道干啥的"，指的是每 2.5 分钟一次的规则卡三选一。

原来的描述是这样的：

lua

复制 { id = "crowd_work", name = "众力之地", desc = "并肩劳作的人,在这片土地上产出更高" }, { id = "death_fear", name = "记死之土", desc = "这片土地记得每一次死亡,把它变成更重的恐惧" }, 读起来很美。但玩家读完还是不知道会发生什么。

“产出更高”——高多少？“更重的恐惧”——重多少？会有什么看得见的后果？

这是文学语言和功能语言混用的典型问题：名字可以诗意，但说明必须说清机制。

8.1 修法：改成"机制 + 后果"两段式 lua

复制 { id = "crowd_work", name = "众力之地", desc = "人越多干活越快。聚在一起采集时,产出明显提高" }, { id = "death_fear", name = "记死之土", desc = "每次死亡都会加重恐惧。一片墓地能压得整个聚落不敢出门" }, 前半句说机制，后半句说玩家会看到的场面。12 张卡全部重写。

卡片也得跟着改——描述从 11 字变长到 22 字左右，卡片宽度从 230 加到 250，折行从 11 字/行改成 12 字/行，行高和卡片高度都调了一遍。

一条经验：玩家读的是"会发生什么"，不是"设计者的诗意"。 诗意留给名字，说明留给机制。

九、按钮打不开——字体，和一条被违反的架构决定 最后这条是最技术的一个，也是最典型的"第三种看不见"。

玩家说"主界面玩法和设置按钮打不开"。

但图鉴、转生、退出这三个按钮是好的。同一个菜单里，五个按钮，三个能点、两个不能。

9.1 第一步：先证明点击是通的 我没有直接去猜，而是写了个诊断脚本，模拟点击并检查回调：

[诊断] menu_book 中心(514,550) 命中=menu_book [诊断] menu_prestige 中心(680,550) 命中=menu_prestige [诊断] menu_settings 中心(846,550) 命中=menu_settings [诊断] menu_help 中心(514,602) 命中=menu_help [诊断] 点击「玩法」后 Camera.helpOpen = true [诊断] 点击「设置」后 Camera.settingsOpen = true 四个按钮全部命中，回调全部触发，标志位全部置位。

点击链路完全正常。所以问题在渲染。

9.2 差异在哪 能显示的三个（图鉴/转生/退出）和不能显示的三个（玩法/设置/暂停），渲染路径不一样：

面板 渲染方式 图鉴 / 转生 / 结算 主通道自绘（Camera.RegisterUI 命中区） 玩法 / 设置 / 暂停 urhox-libs/UI 库（自建第二个 NanoVG 通道） 而 Panels/Help.lua 头部有一行日期：

-- Panels/Help.lua — 玩法说明 / 暂停菜单 / 设置(urhox-libs/UI 版,2026-10-16) 昨天才迁过去的。

9.3 两个坑叠在一起 第一个坑：字体不存在。

UI 库用 theme = "default-dark"，而该主题声明的字体是：

lua

复制 fonts = { { family = "sans", weights = { normal = "Fonts/NotoSansSC-Regular.ttf", bold = "Fonts/NotoSansSC-Bold.ttf", }}, } 我写了个探针脚本，实测哪个字体真能加载：

[probe] Fonts/MiSans-Regular.ttf -> fontId=0.0 ✅ [probe] Fonts/MiSans-Bold.ttf -> fontId=1.0 ✅ [probe] Fonts/NotoSansSC-Regular.ttf -> fontId=-1.0 ❌ ← 主题声明的就是这个 工程里根本没有 NotoSansSC 字体。 UI 库拿不到字体 → 面板所有文本都画不出来 → 点开只见一片遮罩 → 玩家观感就是"按钮打不开"。

第二个坑：双 NanoVG 通道。

UI 库在 UI.Init 里自建第二个 context：

lua

复制 nvg_ = nvgCreate(1) nvgSetRenderOrder(nvg_, 999990) 而项目 main.lua 里，早就记着一段决定：

lua

复制 -- 此前用"世界/UI 两个 NanoVG 通道 + nvgSetRenderOrder"隔离命令缓冲,但真机 -- (GLES)上双通道合成是竞态的:UI 每帧都在提交(日志证实 uiRects 持续 >0、 -- 无渲染错误),输出却间歇性整帧不上屏(荣耀真机约一半概率丢 UI)。 -- 回归单通道,后画即顶层,层级天然正确。 游戏 UI 早就因为这个问题回归单通道了——但 Help.lua 是昨天才迁到 UI 库的，没跟上这个决定。

9.4 修法：改回自绘 两个坑叠在一起，最干净的修法是把这三个面板改回主通道自绘——和已经验证可用的图鉴/转生走同一条路：

复用 Primitives 的原语（Pr.RRect / Pr.Text / Pr.Panel） 复用 Camera.RegisterUI 命中区 不再引入第二个 NanoVG 通道 顺带把音量调节从滑块改成了「◀ 65% ▶」点按式——触屏上滑块很难拖准，点按更稳。

9.5 验证 [diag] 玩法 面板: 渲染=true fill=10 text=57 命中区=9 [diag] 设置 面板: 渲染=true fill=17 text=31 命中区=16 [diag] 暂停 面板: 渲染=true fill=13 text=22 命中区=12 [diag] 玩法面板关闭按钮命中 = help_close [diag] 设置面板「总音量-」命中 = set_master_dn [diag] 设置面板「完成」命中 = set_done 三个面板全部正常渲染，按钮全部可点。

一条经验：nvgCreate 是"新增一个渲染通道"，不是"拿一个画布"。 项目里每多一个 nvgCreate，就多一份真机竞态风险。 如果项目已经为某条路踩过坑并做了决定，新代码必须跟着那个决定走—— 哪怕这意味着放弃一个更方便的库。

十、当前状态 项 状态 军事三效果（清剿/预警/围墙） 已接线并验证 远征帐篷 已实现（7.8 格外扎营，计入人口上限） 稳定食物来源建村 已实现（农田或食物 ≥10） 音效 56 个全部恢复 字号 全局 ×1.2 常驻引导条 已加入（目标 + 进度 + 做法） 结算原因说明 已加入（时间到/灭绝/通天塔） 规则卡描述 12 张全部重写 玩法/设置面板 改回自绘，已修复 渲染冒烟 PASS（30 帧无异常） 对局模拟 3 种子判据通过 十一、下一步 [ ] 拆分 Render.lua：3901 行，构建器每次都在提醒 [ ] 构建期校验：调色板键、字体路径、UI 库用法——三类"拼写错误"各踩过一次以上 [ ] 军事平衡：兵营去掉了 twoSettlements 门槛，得看新数值下会不会过强 [ ] 帐篷与建村的联动：现在链是通的，但"帐篷 → 新村庄"的实际转化率还没测过 [ ] 觉醒/通天塔震荡（04 记过，06 修了一半，仍有反复） [ ] 正式上架（需要人工确认） 写在最后 今天九条反馈，修完之后我盯着它们看了很久。

它们看起来毫无关联：一个说建筑太挤，一个说没声音，一个说字太小，一个说按钮点不动。

但把它们排在一起，规律很清楚：

玩家抱怨的，几乎都不是"功能没做"，而是"做了，但他碰不到"。

军事效果做了——没接线 音效做了——被开关关掉了 引导做了——藏在收起的面板里 结束原因做了——结算页不显示 规则卡做了——描述说不清 玩法面板做了——字体加载失败 六件事，六种"看不见"。

这让我意识到一件事：过去几篇日志，我一直在问"这个功能做了吗"。 今天之后，我得换个问题：

“玩家要怎么才能知道这个功能存在？”

第一个问题是实现问题，第二个是可见性问题。 而可见性问题不会出现在任何日志、任何报错、任何测试里—— 因为代码是对的，跑起来也是对的，只是没人看得见。

至于那条被违反的架构决定——main.lua 里明明写着"回归单通道"，Help.lua 还是引入了第二个通道。

这跟 08 里那个"踩了两次的色板坑"是同一类事：

写在注释里的决定，不等于被遵守的决定。 08 我说"文档靠人记得去看，而人总会忘"， 今天我又补了一句：注释也是文档。

真正的堵法还是那个——让它编译不过。 所以我把"构建期校验"列进了下一步： 字体路径要校验、调色板键要校验、nvgCreate 的调用点要校验。#聚光灯gamejam开发者日志