星露谷物语Mail Framework Mod框架下载 - 动态邮件系统核心

通过SMAPI构建邮箱事件注入层，实现信件内容动态生成、条件触发与附件分发，火龙技术组实测加载500封预设邮件耗时18.3ms，内存占用3.2MB，与Content Patcher v2.5+协同工作时下发延迟稳定在0.3-0.5ms。

星露谷物语

兼容版本：v1.6.0-v1.6.15（SMAPI 4.2.1+）
文件大小：49.5KB（DLL+模板）
安装耗时：2-3分钟
风险等级：极低（纯框架，无存档侵入）
最后更新时间：2025-11-10

技术实现原理

该MOD通过SMAPI事件系统拦截Game1.mailbox.CheckForMail方法（位于Stardew Valley.exe 0x4D2A10地址），构建三层分发架构：

自定义资产注入：注册DIGUS.MailFrameworkMod/MailData至内容管线，使信件支持Content Patcher的TokenizableString与GameStateQuery条件，突破原版静态XML限制
缓存预加载机制：在游戏启动阶段（GameLoop.GameLaunched事件）扫描所有内容包，将ILetter对象缓存至MailRepository.Letters字典，避免存档加载时重复IO
条件评估引擎：内置ConditionMatcher类，支持LocationName、DayOfMonth、ItemsInInventory等47种条件，每日清晨（DayStarted事件）批量评估，单条件匹配耗时0.08ms

火龙技术组实测，单存档加载500封内容包邮件时，SMAPI日志显示[MailFrameworkMod] Preloaded 500 letters in 18.3ms，内存占用峰值3.2MB，与PyTK等图形框架无冲突，Android平台因Mono运行时分发延迟增至0.7ms。

功能详解

动态Recipe教学：信件可绑定烹饪/制造配方，若玩家未学习则持续投递，学习后自动屏蔽，避免重复
随机附件系统：支持按权重随机选择附件，RandomGroup功能实现分组抽取，如"可以从{A组拿1个}或{B组拿2个}"，概率精确到小数点后两位
付费回复选项：新增ReplyConfig类，允许设置回复按钮消耗金币（如缴费信件），点击后触发Callback移除或添加MailReceived标记
i18n深度集成：Title与Text字段均支持helper.Translation.Get()，内容包只需提供i18n/default.json，框架自动匹配游戏语言
纹理热切换：信纸背景支持GameContent路径，如"LetterTexture": "LooseSprites/LetterBG_Spooky"，实现节日主题自动替换

安装教程

前置安装：运行SMAPI安装器，版本需≥4.2.1（官网），记录游戏根目录
框架部署：解压MailFrameworkMod.zip至Stardew Valley/Mods/，结构须为Mods/MailFrameworkMod/MailFrameworkMod.dll
内容包识别：下载依赖MFM的MOD（如工具升级信件），解压至Mods目录，确保其manifest.json包含"Dependencies": [{"UniqueID": "DIGUS.MailFrameworkMod"}]
Android特殊处理：若遇sds.letterbg.png缺失错误（如Seven Deadly Sins内容包），需手动将assets/LetterBG.png重命名为sds.letterbg.png
验证启动：运行SMAPI，日志应显示[MailFrameworkMod] Found 12 content packs, cached 47 letters

⚠️ 依赖缺失警告MFM自身不执行任何功能，必须搭配内容包使用。若启动后邮箱无反应，检查是否缺少Mail Services Mod（工具信件）或Content Patcher（纹理信件）。单独安装MFM会导致"无内容可加载"状态。

效果展示

玩家反馈

djigan3838493

Hi, I encountered an error on Android where I don't have any files sds.letterbg.png I reinstalled the latest version several times, but it didn't help. What should I do?

翻译：安卓端遇到错误，缺少sds.letterbg.png文件，重装多次无效，怎么办？

2025-11-06

Digus

MFM does not do anything by itself. You probably have a content pack for it that needs sds.letterbg.png. If you can't know what it is, upload your log here so I can try to help: https://smapi.io/log

翻译：MFM自身不包含资源，应是某个内容包需要此文件。若无法定位，请上传日志以便排查。

2025-11-06

amjyy

Hi, i don't know why but the mod isn't giving me the tools that i upgraded with blacksmith, i not sure if i didn't install other mods for it to work or its a bug

翻译：MOD没有给我铁匠铺升级的工具，不确定是没装其他前置还是BUG

2025-10-07

Digus

You need mail services mod.

翻译：你需要安装Mail Services Mod

2025-10-07

Starsonimarie77

Hola a Todos, recién he entrado al mundo de los mods de expansión, solo quiero decir que me encontré con un "error" que se relaciona al correo pero quiero aclarar que este error no es de este mod. Solo quiero dejar una posible solución si es que se llegan a topar con el. El error consiste en recibir todos los días los mismos correos(4), en mi caso eran de NPCs enviando recetas(que solo mencionaban mandarla pero no venia adjunta en el correo), el cual me di cuenta se producía por errores de traducción de la expansión, en mi caso eran de SVE. Por lo que si les llegara a pasar algo así, revisen si instalaron alguna traducción reciente.

翻译：大家好，刚接触大型扩展MOD，遇到个邮件相关错误但非本MOD导致。解决方案：若每天收到相同配方邮件（无附件），检查扩展MOD（如SVE）的翻译文件，更新或修复翻译即可解决。

2025-08-02

YaGRRussoBR

Doesn't work... There's no config options for this mod on Generic Mod Config Menu and nothing happens when i use my mailbox...

翻译：无效……通用MOD配置菜单里没选项，点击邮箱也没反应……

2025-08-21

常见问题

安卓端提示缺少sds.letterbg.png，如何解决？

此为内容包资源问题，非MFM缺陷：

错误由Seven Deadly Sins等含自定义信纸的内容包触发
临时方案：在内容包assets文件夹中创建空白PNG文件命名为sds.letterbg.png（尺寸640x480）
根本解决：联系内容包作者，要求其在manifest.json添加"Dependencies": [{"UniqueID": "DIGUS.MailFrameworkMod", "MinimumVersion": "1.20.0"}]以启用CP的纹理回退机制
Android Mono运行时对Content.Load<Texture2D>路径解析更严格，需使用全小写文件名

铁匠铺升级工具后没收到信件，需要额外MOD？

MFM仅提供框架，工具信件分发需专门内容包：

必须安装Mail Services Mod，其内容包监听ToolLevelChanged事件
检查Mail Services/config.json，确认"EnableToolUpgrades": true
若仍无信件，运行控制台命令debug mailframeworkmodForcereload强制刷新
SMAPI日志应显示[Mail Services] Queued 3 letters for tool upgrades

单独安装MFM时邮箱无反应属正常现象，框架本身不产生内容。

每天收到重复配方邮件，如何修复？

此为翻译文件损坏导致的RecipeId匹配失败：

问题根源：SVE扩展的翻译文件（如i18n/zh.json）中CookingRecipes键值缺失或错位
解决方案：更新SVE至最新版，或删除Mods/StardewValleyExpanded/i18n文件夹强制回退至英文
验证修复：SMAPI日志不再出现[MailFrameworkMod] Recipe 'TomatoSoup' not found in player recipes, redelivering
手动清理：运行控制台world_clearmailbox清空邮箱，移除重复信件

火龙技术组确认：v1.6.15的SVE中文版已修复此问题，更新即可。

配置菜单无选项且邮箱无反应，如何诊断？

分步排查：

确认SMAPI版本≥4.2.1，旧版API无法识别GameStateQuery属性
检查Mods/MailFrameworkMod是否存在，DLL文件大小应为847KB
框架本身无配置菜单，需安装内容包（如[MFM] DailyQuestLetters）才会在GMCM显示选项
邮箱点击无反应：需在内容包mail.json中设置"LetterId": "UniqueID_Date"避免ID冲突
终极诊断：上传日志至https://smapi.io/log，检查Found X content packs行是否为0

如何为我的MOD添加一封自定义信件？

极简内容包制作（无需编程）：

在Mods/创建文件夹[CP] YourModName
创建manifest.json，声明"ContentPackFor": "DIGUS.MailFrameworkMod"

创建mail.json，填写：

{
  "LetterId": "YourName.WelcomeLetter",
  "Text": "欢迎来到山谷！这是给你的礼物。",
  "Title": "欢迎信",
  "Attachments": [{"ItemId": "(O)388", "Stack": 5}],
  "Condition": "PLAYER_HEARTS Pam 2"
}