《芙田物语 AlfFarmTale》的所有版本变更。版本格式遵循 主版本.次版本.修订号，并按发布阶段加 Alpha / Beta 前缀

[Beta 0.20.0] — 2026-06-21・Prologue 章节解锁

“故事开始了：雨夜、卷宗、即将到来的海鸥岛。”

本次更新在 alpha0.19.2 的基础上，正式解锁序章 Prologue 章节、引入体力 / 食物双轨制、重做可破坏建筑系统，并大幅扩展银岚城（SilverMist）内容。属于一次较大的内容性版本重写。

✦ 故事・新内容

全新 Prologue 章节「WuningHouse」

解锁 Wuning 居所三联场景 + 完整开场剧情。新增 / 改动的场景：

• WuningHouse（wuning 居所）：雨夜 Alf 闯入收卷宗的房间，屋内带事故片段视频播放（自带 Skip 按钮）
• WuningHouseAlf（卧室）：按 F 拾取关键道具 → 走到床边点 “Sleep” → 推进一日 + 切到走廊
• WuningHouseCorridor（走廊）：走到 Wuning 私人房间入口触发回忆对话门
• 三联场景统一接入 PointLight2D 烛火闪烁系统
• 专属 BGM《Silent Rain Narrative》全程循环

配套新增资产

• 音效：雨声、雷声（3 变种）、翻页声、开锁声、撞击声
• 角色立绘：Wuning 全身立绘、Alf 剑击 + 放置动画
• 场景贴图：Wuning 三联场景全套室内贴图、SilverMist 屋内贴图

新任务

表格

✦ 玩法・系统大改

体力 / 食物 / 休息系统（核心升级）

旧版单一能量条改为「跑步消耗可自然回复」+「劳作永久扣除」双轨制：

• 跑步消耗（按住 Shift）：归零后 2 秒喘息期，期间 Shift 无效但不致死锁
• 永久扣除：锄地 / 浇水 / 砍树 / 建造 / 播种 全部累加 energy_floor，封顶 energy_max
• 8 种食物可食用：右键手持 Food 类物品直接吃，吃掉永久降低体力下限 → 上限自动上升
  • 苹果 / 胡萝卜 +5、番茄 / 茄子 +6、小麦 +4、卷心菜 +8、南瓜 +10、小黄瓜 +7
• 体力 ≤ 0 拦截：锄头 / 浇水壶 / 斧头完全无法使用，range 提示自动隐藏
• 累瘫对话：体力跌到 0 那一帧边沿触发一句 Alf 提示，不会反复弹
• 能量条 UI 升级：体力归零时变暗红色，条不再消失（避免玩家误判为 bug）

农田生长 × 浇水联动

• 旧版：时间推进就生长
• 新版：只有 moisture > 0.5（视觉湿润）时才生长
• 不浇水约 50 分钟后生长自动暂停，再浇水立即恢复
• 所见即所得，wet 视觉 ↔ 生长状态对齐

可破坏建筑系统重做

• 砍栅栏 / 箱子 / 床 / 装饰 统一走斧头（HoldEffectResource 抽象），大部分 1 下碎
• 砍宝箱：先吐内部所有物品到地上，再让宝箱消失，不会丢东西
• 锄头新功能：可擦带 metadata/tellable = true 的装饰 tile（如 Afforest 层），擦完自动变可耕地，主动扩展开垦空间
• 配置集中在 Level 顶部两张 const 表，加新特例改表不动 Inventory 资源

SilverMist 热闹起来了

新增 3 个 NPC + 3 家新商店：

表格

旧 npc2001 工具店大幅精简：只留 axe /hoe/sprinkler /sword/carrot /carrot_seed

✦ 视觉・体验优化

• 启用 MSAA 2D / 3D 抗锯齿，场景锯齿大幅缓解
• 室外相机缩放 1.2 → 1.8，视野更近更舒适
• 室内相机缩放 1.5 → 2.0，屋内更聚焦
• Wuning 三联场景 + Alf 全身动画 + Wuning 立绘全套到位
• SilverMist 场景首次加入室内
• 新增 BGM 池混合播放：未注册专属 BGM 的场景自动从 village_01 + birth 两池随机选播

🐛 修复

• 「砍完树后不能耕地」：4 个 outdoor 场景的 hidden 美术辅助 Tree 层不再阻挡锄地判定
• 满体力误判守卫：旧版 floor > 0 时吃东西被误拦，现在用 future_current 预测算法判断
• 开局能量条不满：默认 energy_floor 从 1 改回 0.0，且 .tres 显式声明 energy_max / current / floor 三字段
• Afforest 装饰 tile 阻挡开垦：锄头走 BreakableTellable 通用入口
• 「离开区间反复触发对话」：状态机改用 Area2D._on_*_body_entered 边沿信号，不再每帧检测
• Web 镜像种子路径错位：birth_fellable_tree_exist_resource.tres → birth_fellable_tree_resource.tres 对齐桌面端
• 室内 mouse_focus 光标方块错乱：indoor 场景自动隐藏
• BGM 衔接错乱：Wuning → SilverMist 切换时按当前 level_name 重播
• 能量条归零完全看不见：旧版直接 visible=false，现在保留条 + 暗红色提示

⚡ 性能 / 存档

• 桌面端存档全部写到 res://archives/<slot>/，不再覆盖 res:// 源文件，多 slot 不再互相污染
• Web 端 cold-start 镜像范围扩展到 16 个新场景存档
• WebSaveAdapter 新增 swap_to_runtime_deep 递归 swap，Inventory 物品引用刷新
• InventoryNode._relink_inventory_after_swap() 修正 Web deep-swap 后玩家改动写到旧 bag 的 bug

📁 文件改动（按模块）

plaintext

新增资产
  assets/sound/                    雨声 + 雷声 + 翻页 + 开锁 + 撞击 + 剑击 SFX
  assets/sound/bgm/                Silent Rain Narrative (Prologue BGM)
  used/character/alf/...           全身动画 + 剑击 + 放置
  used/character/wuning/...        Wuning 立绘全套
  used/scene/wuninghouse/...       Wuning 三联场景全套贴图
  used/scene/silver_mist/...       SilverMist 室内新增

新增场景
  levels/wuninghouse/              Prologue 主场景
  levels/wuninghouse_alf/          Prologue 卧室
  levels/wuninghouse_corridor/     Prologue 走廊

新增 NPC
  compoents/npc/npc4001/           SilverMist 家具店主
  compoents/npc/npc4002/           SilverMist 食材种子店主
  compoents/npc/npc4003/           SilverMist 武器杂货店主

新增 / 重构模块
  compoents/breakable/             通用可破坏抽象（breakable.gd + 子类）
  compoents/chest/                 current_cell 字段追踪
  compoents/fellable_tree/         7003 走 to_tool() 统一入口
  managers/sound_manager/          BGM 池混合 + 早返守卫
  dialogic/timeline/Alf_stamina_deplete.dtl   累瘫对话

体力食物链
  structs/character_resource.gd    energy_floor 默认 0.0
  structs/inventory.gd             restore_value 字段
  compoents/character/character.gd  consume_food() + 满体力守卫
  compoents/character/children/attribute/children/statusinfo/statusinfo.gd
                                  边沿触发累瘫对话 + 能量条 UI
  compoents/range_prompt/          体力归零拦截 + 切工具抛光
  structs/hold_effect_resource.gd  consumes_energy() 虚方法
  compoents/character/hold_effect/7001.gd / 7002.gd / 7003.gd
                                  override consumes_energy() = true

历史版本（简表）

表格

版本约定

• 主版本：剧情 / 玩法机制大改（例：0.20.0 加入体力食物系统）
• 次版本：新增场景 / 新 NPC / 新系统模块
• 修订号：bug 修复 / UI 调优 / 资产微调
• Alpha → Beta：序章打通 + 核心玩法闭环后切换

AlfFarmTale 存档系统实现分析

整体架构

项目采用 WebSaveAdapter 适配层 + ResourceManager 统一接口 + GameManager 生命周期管理 的三层架构，实现了 Windows 桌面端和 Web 端的跨平台存档支持。

一、Windows 桌面端存档实现

1.1 存储路径

桌面端使用 res://archives/<slot>/ 目录结构，其中 <slot> 格式为 序号_月日_时分（如 1_0609_1431）。Plain Text

res://
├── archives/
│   ├── 1_0609_1431/
│   │   ├── game_resource.tres
│   │   ├── character_resource.tres
│   │   ├── village01_resource.tres
│   │   └── ...
│   └── 2_0609_1427/
│       └── ...
└── resources/
    └── ... (原始资源)

1.2 存档流程

保存时机：

• 用户主动保存（暂停菜单 save_to_archives()）
• 退出游戏时（NOTIFICATION_WM_CLOSE_REQUEST 触发）

核心流程（GameManager.on_quit()）：Plain Text

1. 发出 quit 信号 → 所有监听者同步状态到内存资源
2. 保存 setting_resource
3. 遍历 archive_resource_list，调用 ResourceManager.save_resource()
4. 直接写回 res:// 路径（覆盖原始资源）
5. 关闭窗口

1.3 多存档槽实现

桌面端通过 目录复制 实现多存档槽：

• new_game 时创建新目录，从 _original.tres 文件加载初始状态
• load_game 时将对应目录的 .tres 文件复制回 res://resources/

二、Web 端存档实现

2.1 存储路径

Web 端使用 user://runtime_state/ 作为运行时状态根目录：Plain Text

user://
└── runtime_state/
    ├── game_resource.tres          # seed 文件（冷启动默认值）
    ├── character_resource.tres     # seed 文件
    ├── 1_0609_1431/               # slot 子目录
    │   ├── game_resource.tres
    │   ├── character_resource.tres
    │   └── ...
    └── 2_0609_1427/
        └── ...

2.2 核心机制：镜像替换

冷启动（Cold Start）：

• 首次加载时，将 SEED_RUNTIME_PATHS 中的资源从 res:// 复制到 user://runtime_state/
• 这确保了 WebAssembly 只读文件系统的可写性

运行时替换：gdscript

func swap_to_runtime_deep(original: Resource) -> Resource:
    # 1. 将外层资源替换为 user:// 镜像
    # 2. 递归遍历所有子 Resource 属性
    # 3. 将子资源也替换为镜像版本
    # 4. 修复"子资源仍指向 res:// 导致状态丢失"的问题

2.3 保存触发机制

Web 端没有 WM_CLOSE_REQUEST 事件，采用 多重保险：

关键代码（_register_beforeunload()）：gdscript

JavaScriptBridge.eval("""
    function _flush() {
        if (window.godotBeforeUnload) { window.godotBeforeUnload(); }
    }
    window.addEventListener('beforeunload', _flush);
    window.addEventListener('pagehide', _flush);
    document.addEventListener('visibilitychange', function() {
        if (document.visibilityState === 'hidden') { _flush(); }
    });
""")

三、核心类职责

四、路径转换逻辑

gdscript

func runtime_path(original_path: String) -> String:
    if not is_web:
        return original_path  # 桌面端：原路径
    
    if original_path.begins_with("res://"):
        var slot := GameManager.setting_resource.current_existing_index
        if slot == "":
            # cold start：返回 seed 位置
            return "user://runtime_state/<basename>"
        # 进入游戏后：返回 slot 子目录
        return "user://runtime_state/<slot>/<basename>"
    return original_path

五、设计亮点

5.1 零侵入式适配

• 桌面端可以完全移除 WebSaveAdapter autoload，不影响原有逻辑
• 通过 is_web 分支实现平台隔离

5.2 递归子资源处理

• swap_to_runtime_deep() 解决了 Godot 子资源引用问题
• 确保导出的 .tres 文件中 ext_resource 指向正确路径

5.3 事件覆盖完整性

• Web 端监听三种浏览器事件，覆盖所有退出场景
• 移动端切换后台也能正确保存

5.4 冷启动容错

• 首次加载自动 seed，无需手动初始化
• 检查文件存在性，避免覆盖已有存档

六、数据流向图

Plain Text

┌─────────────────────────────────────────────────────────────────┐
│                        用户操作/系统事件                          │
└──────────────────────────┬──────────────────────────────────────┘
                           │
            ┌──────────────┼──────────────┐
            ▼              ▼              ▼
    [用户保存]       [窗口关闭]       [浏览器事件]
            │              │              │
            └──────┬───────┴───────┬──────┘
                   │               │
                   ▼               ▼
    ┌───────────────────────────────────────┐
    │        GameManager.quit.emit()        │
    │    (通知所有监听者同步状态)              │
    └───────────────────┬───────────────────┘
                        │
                        ▼
    ┌───────────────────────────────────────┐
    │      ResourceManager.save_resource()   │
    │    (递归保存资源及其子资源)              │
    └───────────────────┬───────────────────┘
                        │
        ┌───────────────┴───────────────┐
        │                               │
        ▼                               ▼
┌───────────────┐             ┌───────────────┐
│   桌面端       │             │    Web端       │
├───────────────┤             ├───────────────┤
│ res:// 原路径  │             │user://runtime │
│               │             │_state// │
└───────────────┘             └───────────────┘

七、总结

该设计通过 适配器模式 优雅地解决了 WebAssembly 只读文件系统的限制，同时保持了桌面端的原有行为，实现了真正的跨平台存档兼容性。

SDF数据是CPU预先计算后作为普通纹理上传的，不依赖GPU的特殊SDF支持

1. GlobalLight 光照系统

• ✅ 删除了 color_rect 和着色器相关代码
• ✅ 修改 DirectionalLight2D 角度为完整24小时周期：
  • 凌晨3点: -90°
  • 正午12点: -180°
  • 19点: -270°
  • 午夜: -360°（即 0°）
• ✅ 角度变化改为线性（移除缓入缓出）
• ✅ 添加 max_dist 时间变化逻辑（控制阴影距离）

2. ShadowShader 阴影着色器

• ✅ 将 angle 参数反向旋转（添加负号）
• ✅ 将 angle=0 偏移为 180°

3. SoundManager 音效管理

• ✅ 背景音乐随机播放间隔从 60-180秒 改为 30-90秒

4. 背包交互系统

• ✅ 修复右键拖拽误触：区分”左键拿起”和”右键平分”模式，只有左键拿起后右键拖拽才能逐格放置
• ✅ 禁止鼠标点击选择 hold 栏：只能通过快捷键（pageup/pagedown/1-9）选择
• ✅ 修复物品放入 hold 栏不刷新问题：在 HoldItem.update_display() 中自动检测并刷新 lift sprite 和 range 显示

这些修改提升了游戏体验，减少了误触操作，优化了光照系统的动态效果。

1. Menu 互斥逻辑修复

• 移除不存在的 handbook 调用：修复了 attribute.handbook.reset() 的报错
• 实现互斥打开：点击 Bag 时关闭 Task，点击 Task 时关闭 Bag
• 使用 call_deferred：确保切换操作在帧结束时执行，避免动画冲突

2. Bag 和 Task 动画效果增强

• 添加缩放动画：参考 Shop 的实现，为 Bag 和 Task 添加了缩放动画效果
• 修复居中问题：将 pivot_offset 设置移到 _ready() 中，确保缩放以面板中心为原点

3. StatusInfo 能量条控制

• 动态显示/隐藏：当能量为 0 时隐藏 %EnergyInner，否则显示

4. Shop 功能增强

• ESC 键关闭：添加 ESC 键关闭商店的功能
• 互斥控制：
  • 商店打开时禁止打开 Bag 和 Task（快捷键和点击菜单都禁用）
  • 商店打开时自动关闭现有的 Bag 和 Task
• 滚轮操作控制：
  • 商店打开时禁用 Hold 的滚轮操作（Page Up/Page Down）
  • 商店中 Page Up/Page Down 用于翻页
• Sell 逻辑优化：出售物品后保持选中状态，直到物品卖完才取消选择

5. 快捷键统一处理

• Bag 和 Task 的快捷键都通过 Menu 的 on_click_item() 方法处理，确保互斥逻辑一致

新增建筑系统（栅栏 + 箱子 持久化）

功能说明：

• 新增完整建筑放置功能，支持放置栅栏、箱子两种建筑道具
• 栅栏拥有自动连接逻辑，相邻栅栏可自动衔接，视觉效果连贯自然
• 栅栏配置专属碰撞体，玩家无法穿越，满足地形阻挡需求
• 全数据持久化生效：栅栏、箱子的放置位置永久保存
• 箱子支持独立储物，内部存放的物品数据同步持久化，重启游戏不丢失

斧头栅栏砍伐功能

修改文件：

• building_resource.gd：新增 fence_axe_count 字典，用于存储栅栏砍伐累计次数
• level.gd：新增 get_current_tile_can_axe_fence()、axe_fence() 核心逻辑函数
• 7003.gd（斧头效果脚本）：新增栅栏专属砍伐执行逻辑
• 8001.gd（栅栏配置脚本）：新增 AXE_NEEDED 配置常量

功能说明：

• 解锁斧头砍伐栅栏的能力，需累计砍伐指定次数才可破坏栅栏
• 砍伐所需次数可在 8001.gd 中自由配置，默认需要砍伐3次
• 栅栏砍伐成功后，自动掉落1个对应栅栏物品
• 完全保留原生砍树逻辑，互不冲突、互不影响

Shift+左键 物品快速转移功能

修改文件：inventory_node.gd

功能说明：

• 箱子存储空间已满时，物品自动转移至对应互补栏位（背包↔持握栏互换填充）
• 完整支持物品堆叠合并逻辑，自动补齐同类物品堆叠数量，优化转移体验

极速连续拾取物品功能

修改文件：

• character.gd：优化拾取逻辑，物品拾取后立即从物品列表移除
• interact.gd：移除拾取动画播放期间隐藏交互提示的限制条件

功能说明：

• 支持玩家快速连续按下F键批量拾取物品，无需等待拾取动画播放完成
• 场景物品交互提示永久显示，无隐藏限制，方便玩家连续操作拾取

StatusInfo 能量消耗功能 (statusinfo.gd)

• 监听角色操作信号（锄地/收获、浇水、砍树），每次操作消耗1点能量
• 确保能量不会低于0
• 实时更新生命条和能量条的 UI 显示

商店出售价格修复 (shop.gd)

• 价格显示：出售模式下显示八折价格，且最低为1金币（避免价格为1的物品打八折后变成0）
• 实时更新：在 _process 中持续更新价格，确保通过任何方式修改数量（点击按钮、手动输入、回车）都能正确显示

实际交易价格修复 (character.gd)

• 出售物品时实际获得的金币也应用八折计算，且最低为1金币
• 确保显示价格和实际交易价格保持一致

• 修复了背包满时拾取pickable导致重复生成的问题
• 修复了右键按住拖拽时误触发平分的问题
• 修复了右键点击和拖拽重复放置的问题

1. 物品堆叠上限

• 设置物品堆叠上限为64个
• 超过64个时会自动寻找新的空位放置

2. 左键点击操作

• 拾取物品：左键点击物品，物品附着到鼠标上，显示半透明预览
• 放置物品：
  • 点击空格子：直接放入
  • 点击相同物品：合并（超过64个时剩余继续附着）
  • 点击不同物品：交换位置

3. 右键点击操作

• 平分物品：右键短按（<200ms）物品，将物品平分到鼠标上，余数留在原格子
• 放置1个物品：右键点击空格子放置1个，或点击相同物品增加1个

4. 右键拖拽操作

• 按住右键滑过空格子：每个空格子放置1个物品
• 按住右键滑过相同物品格子：每个格子增加1个物品
• 同一个格子在一次拖拽中只能放置一次

5. 双击操作

• 双击物品：合并背包和手持中所有相同的物品，直到达到64个上限

6. 快捷键操作

• Q键：丢弃鼠标悬停的物品，每次只丢弃1个

7. 界面外操作

• 点击背包/手持界面外：掉落附着的物品

8. 背包关闭处理

• 关闭背包时，附着的物品会：
  • 尝试返回原格子
  • 如果原格子被占用，寻找空格子
  • 如果背包已满，触发掉落

一、商店购买功能实现

在shop.gd完善_on_buy_pressed()方法，实现完整购买逻辑：

1. 检查是否选中商品
2. 获取选中商品的inventory数据
3. 获取spinbox选择的购买数量
4. 调用角色to_buy_inventory()方法，完成扣除金币 + 添加物品到背包

二、代码结构优化（shop.gd）

添加region代码分类，提升可读性：

• #region export 导出变量
• #region var 内部变量
• #region signal 信号定义
• #region lifecycle 生命周期方法
• #region items 物品加载逻辑
• #region ui UI 操作方法
• #region signal handlers 信号处理器

三、UI 功能优化

1. 物品价格显示选中物品时，%Price标签显示总价 = 单价 × 数量，仅显示整数
2. 实时价格更新点击sub/add按钮、直接修改SpinBox数值时，价格自动同步更新
3. 界面缩放优化初始 / 关闭缩放从 80% 调整为 95%，缩放差值降至 5%，效果更自然

四、问题修复

1. Shop 界面 Buy 模式 SpinBox 最大值限制
   • 问题：购买数量最高只能为 1，add 按钮失效
   • 修复：update_current_select()区分模式
     • Buy 模式：spinbox.max_value = 99（无限库存）
     • Sell 模式：spinbox.max_value = 物品实际持有数量
2. BGM 提前停止
   • 问题：音乐硬编码限制 120 秒，播放中断
   • 修复：play_level_audio_loop()使用back_audio_player.finished信号，让音乐自然播放完毕
3. 出售物品逻辑失效
   • 问题：仅修改商店临时数据，未真正扣除背包 / 手持物品
   • 修复：_on_sell_pressed()中先定位背包 / 手持物品节点，再调用出售方法，同步修改真实数据
4. 物品添加优先级调整
   • 需求：购买物品优先放入手持 (hold)，再存入背包 (bag)
   • 修复：find_can_use_item()、find_exist_item()中交换遍历顺序，先检查手持

五、涉及文件

• AlfFarmTale\managers\utils_manager\children\shop\shop.gd
• AlfFarmTale\managers\sound_manager\sound_manager.gd
• AlfFarmTale\compoents\character\character.gd