《收旧时光》v1.6.18 开发日志

本次开发记录归档至 docs/dev-log.md，提交 commit：9672de7

一、本轮需求（4项用户需求，附首页昏暗问题截图）

1. 首页角色辨识度不足，对场景装饰进行美术优化
2. 摆摊、外出收货完成后，使用大图弹窗展示获取物品
3. 体力消耗差异化：摆摊收获扣减体力更少，外出收货扣减体力更多
4. 外出收货模块新增2.5D实景HUD场景，搭载真实场景模型与NPC角色；同步登记新增素材与界面资源

二、交付明细

① 首页场景美术优化（StreetScene.lua）

• 新增相机正向主光源 KeyLight + 主角专属暖调点光源 AvatarLight，解决摊位场景主角背光、面部发黑问题
• 环境光 ambient 从 0.34 上调至 0.40，全局画面提亮
• 主楼窗户重构：摒弃大面积纯色黄块，改为密集小窗组合；通过哈希值独立控制每扇窗状态，实现暖黄、冷蓝、熄灯交错的夜景层次感

② 收获大图弹窗（新增模块 RewardPopup.lua）

• API：RewardPopup.Show(title, subtitle, items, onConfirm)
• 单件物品：150px大图卡片，展示设备名称+成色标签
• 多件物品：96px横向排布卡片
• 接入场景：摆摊估值成交（区分「捡漏成功」「收机成交」并附带估值标签）、外出逐箱搬货
• 架构约束：弹窗仅做展示，不接管游戏流程跳转；禁止跨页面Goto，避免根节点重建销毁弹窗引发卡死；顶层仅依赖UI模块，内部采用惰性require引入页面，规避循环引用问题

③ 体力&心情消耗差异化配置（data.lua STALL + state.lua）

• 资源提示文案中原硬编码 -5 全部改为从 Data.STALL 动态插值，保证文案与代码数值统一

④ 外出2.5D实景收货场景（新增模块 OutingScene.lua，注册页面 screens.outing）

• 场景资源构成：混凝土地面、远端矮背景墙（压缩上部画面空间，避免画面溢出）、两侧三层陈列货架、2盏带锥罩悬挂暖点光灯、地面暗色油渍贴图、3个带浮动自发光金球效果的货箱、2个复用41骨骼的NPC角色；通过大檐彩帽、胸牌子件区分NPC与主角模型
• 场景加载策略：场景壳体、光照、相机同步初始化，分4帧渐进加载场景元素；搭配进度遮罩「潜入 X%」；场景实例常驻复用，重新进入时将主角复位至场景入口
• 完整玩法链路：地图点击外出 → State.BeginOuting()（扣减25体力、心情并触发冷却，预生成升序收获队列）→ 进入实景场景 → WASD/摇杆移动，胶囊碰撞检测 RoomMotion → 靠近发光货箱唤起「搬货」交互按钮 → 逐箱拾取，弹出收获大图弹窗（优先拾取低价物品）→ 点击「回去交货」，通过导航栈返回地图界面
• 数值统一保障：收货逻辑 State.TryCollectJunk 统一处理扣费、重复拾取校验；实景手动搬货与托管外出 DoOutTrip 复用同一底层函数，两条玩法路径数值不会出现不一致

追加：首页全黑问题排查

• 问题定性：属于预览加载旧安装包导致，非代码Bug。冷启动入口 main.lua 90帧渲染画面完整；构建文件修改时间晚于全部源码，Lua日志无报错
• 判定规则（已纳入项目避雷清单）：HUD与3D视口一同消失，不属于Lua逻辑问题；若仅视口销毁，HUD界面会保留
• 修复：上一版交付文档标注版本升级，但 data.lua 版本号未同步更新，补全版本号并重新打包 build 7

三、本轮修复Bug（共2处）

1. 背景墙坐标错误，创建在相机+Z方向，画面被墙体完全遮挡。修正方案：背景装饰墙统一放置远端-Z位置，玩家活动边界使用不可见碰撞体实现
2. doPick 根据索引重新点亮货箱，会将已经搬空的箱子再次点亮。调整逻辑：拾取后显式关闭当前货箱光源，仅场景入场/复位阶段才批量刷新全部货箱灯光

四、新增素材与界面登记（配套需求④）

• 素材路径 assets/image/新素材/{1,2,3}/：32张 721×1281 全屏cutout资源（11+14+7），PNG与meta文件配对完整，已提交Git并打入构建包。

素材为v1.6.16地图分层改版回滚资产，本次不用于地图渲染，吸取上次回滚教训，后续评估通过后再启用。

• 新增界面：外出实景页面 outing；新增组件：收获大图弹窗

五、验证结果

• 外出场景探针：28项无头测试全部通过，覆盖体力扣费、队列生成、视口挂载、分帧构建场景、主角+2NPC+货箱生成、交互按钮解锁、搬货弹窗、队列消耗、返回地图视口重置、场景复用复位等逻辑
• 回归测试：导航50项、HUD10项、首页+卧室页面探针全部通过；LSP无报错；主入口60帧稳定，Lua/资源/引擎层无异常
• 人工校验：3张540×960截图核验首页角色清晰度、外出场景构图、收获弹窗展示效果
• 构建信息：build 1.0.16 build 7，客户端 48a970e4，构建日志 build_20261013_230816；资源总数557，无缺失资源；OutingScene/RewardPopup/StreetScene源码纳入打包，探针、截图脚本排除
• Git：commit 9672de7，变更文件80个

六、新增项目避雷要点（长期归档）

1. 黑屏/白屏故障排查：优先使用「HUD与视口是否同步消失」判定，三步取证，不要盲目修改代码
2. 版本升级记录：文档标记VERSION更新前，必须确认 data.lua 版本号实体修改，避免版本虚记造成更新补偿静默失效
3. 2.5D场景制作：实心墙体不可遮挡相机与玩家活动区域；截图脚本自带启动参数，必须携带 -tool_mode

• 完整日志：docs/dev-log.md（头部更新时间标记 + 第五节版本表新增v1.6.18条目）
• 决策记录：docs/memory-index.md D-044
• 版本总览：docs/versions.md