SMAPI-Android-1.6 版本更新与技术解析

项目概述

SMAPI-Android-1.6 是 Stardew Valley（星露谷物语）Android 平台的模组加载器（Stardew Modding API）的最新版本分支，专门为游戏 1.6.x 版本设计。作为模组生态系统的核心组件，它提供了模组加载、API 接口、错误处理等关键功能。

最新版本更新（2025年3月25日）

玩家相关修复

• 自定义图块崩溃问题：修复了当某些模组的自定义图块显示在屏幕上时导致的游戏崩溃问题。这个问题主要影响使用自定义地图元素的模组，特别是那些添加了特殊家具或装饰性元素的模组。

模组开发者调整

• ChairTiles 逻辑回退：撤销了之前对游戏 Data/ChairTiles 逻辑中处理唯一字符串ID（如 Maps/Author.ModName）的修复方案。虽然原修复解决了字符串ID识别问题，但在某些情况下会导致地图图块加载崩溃。开发团队决定等待游戏本体下一次更新来彻底解决此问题。

历史版本重点更新

4.2.0 版本（2025年3月24日）

玩家体验改进

• 日志上下文命令：修复了 log_context 命令重复运行时无法正确关闭额外日志的问题。
• Linux 终端支持：优化了 Linux 平台下的安装程序，确保能按预期打开终端窗口。
• 版本检测：改进了对使用四段式版本号的非官方 SMAPI 移植版的更新提醒处理。

开发者功能增强

• 运输菜单事件：现在模组事件可以在运输菜单中触发（实际保存操作除外）。
• 翻译API扩展：
  • 新增 ContainsKey 和 GetKeys 方法，用于查询翻译键
  • 支持在占位符文本中使用令牌（tokens）
• API 代理改进：当 modRegistry.GetApi<T> 无法将API代理到给定接口时，现在会正确记录错误并返回 null。

4.1.0 版本（2024年11月4日）重大更新

核心改进

• 游戏版本适配：全面支持 Stardew Valley 1.6.9 版本
• 内容完整性检查：新增自动检测缺失或修改的内容文件功能，发现问题时会记录警告
• 多平台优化：
  • macOS：支持 iTerm2 终端
  • Linux：集成 GameMode 支持
  • 路径匿名化：隐藏日志中包含用户主目录的路径信息

开发者工具

• 私有程序集引用：支持将依赖项标记为私有，避免与其他模组冲突
• 国际化增强：
  • 支持 i18n 子文件夹结构
  • 新增翻译中的性别切换块支持
• API 扩展：
  • 新增 DoesAssetExist 方法检查资源存在性
  • 添加滚轮事件抑制功能
  • 新增路径匿名化显示工具

技术深度解析

翻译系统架构

SMAPI 的翻译系统在 1.6 版本中得到了显著增强：

1. 多语言支持：

   • 支持标准的 i18n 文件夹结构
   • 新增性别敏感文本处理
   • 令牌系统现在可以应用于占位符文本

2. 性能优化：

   • 使用惰性求值（lazy evaluation）优化了 Monitor.VerboseLog 的性能
   • 翻译键查询避免了不必要的资源加载

内容管道改进

针对游戏 1.6 版本的内容系统变化：

1. 地图处理：

   • 不再阻止修改 tilesheet 顺序（1.6.9+ 已修复相关崩溃问题）
   • 修正了 .tmx 地图文件的图块尺寸处理一致性

2. 资产传播：

   • 新增对 Data/ChairTiles 的资产传播支持
   • 改进了玩家精灵和建筑涂装掩码的变更传播

跨平台支持进展

macOS 特别注意事项

由于 macOS 系统安全策略更新，用户需注意：

• 必须遵循最新的安装指南配置安全权限
• 终端支持已优化为自动检测 iTerm2

Linux 增强

• GameMode 集成改善游戏性能
• Flatpak 安装路径检测更准确
• 终端处理逻辑更加健壮

开发者迁移建议

针对从旧版本迁移的模组开发者：

1. API 变更：

   • 移除了所有已弃用的 API
   • 控制台输出现在直接传递，不再被 SMAPI 拦截

2. .NET 升级影响：

   • 目标框架升级至 .NET 6
   • 需要重新编译模组以确保兼容性

3. Harmony 处理：

   • 不再重写使用 Harmony 1.x 的模组
   • 建议更新至 Harmony 2.x 版本

故障排查指南

常见问题解决方案：

1. 地图加载崩溃：

   • 暂时避免使用复杂的 ChairTiles 自定义ID
   • 等待游戏本体更新

2. 模组兼容性：

   • 检查 SMAPI 日志中的"assembly version"信息
   • 使用 log_context 命令获取详细上下文

3. 内容验证警告：

   • 可通过 smapi-internal/config.json 禁用完整性检查
   • 警告仅影响问题排查，不影响正常游戏

未来展望

根据更新路线图，后续版本将重点关注：

1. 性能优化：

   • 进一步减少模组加载时间
   • 改进资源缓存机制

2. 开发体验：

   • 增强翻译工具链
   • 完善调试工具支持

3. 跨平台一致性：

   • 统一不同平台的安装体验
   • 加强移动端特定功能的支持

SMAPI-Android-1.6 作为模组生态的核心，持续为 Stardew Valley 的模组开发者提供强大而稳定的支持，同时不断优化终端玩家的使用体验。开发者可以充分利用其提供的各种API和工具，创造出更加丰富多样的游戏内容。