邮件框架模组

1.15.0

• 为SMAPI模组提供的新API接口。
• API方法，用于从您的SMAPI模组内部加载内容包文件夹。
• API方法，用于加载信件。
• API方法，用于获取信件数据。
• API方法，用于获取信件的邮件数据字符串。
• 修复了在关闭信件时发生错误导致邮箱无法正常工作的问题。
• 优化了这些错误的日志记录。

[
	{
		"Id": "MyMod.MyMailId", // 信件ID。必须确保是唯一字符串以避免冲突，且不应包含空格字符。
		"GroupId": "MyMod.MyGroupId", // 信件组ID。相同组ID的信件永远不会在同一天送达。先注册的信件优先处理，除非组ID以".Random"结尾，这种情况下会随机选择一封信件。默认为null。
		"Title": "我的信件标题", // 信件标题。将在收藏菜单中显示。若不想让信件出现在收藏中，请设为null或删除该行。如果提供了翻译文件，此处应放置翻译键，但仍可保留null表示无标题。
		"Text": "亲爱的@^这是我的自定义邮件。", // 信件内容。可使用@代表玩家名称，^表示换行。也可使用基础游戏指令添加金钱、物品等内容。若提供翻译文件，此处应填写翻译键。
		"RandomlyChooseAttachment": 2, // 若设置数值，将从每组附件列表中随机选取对应数量的物品。默认为空值。
		"RandomlyChooseEachGroup": { "洞穴物品": 3 }, // 如果在此设置了组别和数量，将使用该数量来挑选物品，而非RandomlyChooseAttachment中设置的数量。默认为空。
		"RandomGroupWithReplacement": [ "洞穴物品" ], // 默认情况下附件是从列表中随机选取且不重复的，若希望选取时替换原有附件，请将该分组加入列表。如未添加分组，请使用空字符串。默认值为空列表。
		"Attachments": [ // 附件列表。删除该属性可不将物品附加至邮件。
			{
				"Type": "Object", // [Object|BigCraftable|Tool|Ring|Furniture|Weapon|Boots|DGA|QualifiedItemId|None] 必填。指定将附加的物品类型。若未提供，该物品将被忽略。选择'None'时日志不会报错且始终被忽略，适用于需要设置不添加附件的概率时使用。
				"Name": "洞穴胡萝卜", // 用于查找物品索引。如果使用如Json Assets等自定义对象时必需。若使用DGA则应填写完整DGA ID。若未提供，则将使用索引值。默认为null。
				"Index": "(0)78", // 物品的索引。应为字符串形式的合格物品ID，但为了向后兼容，也可以作为整数使用。如果未提供名称或未找到对应名称的物品，则使用索引。否则，附件将被忽略。若类型为DGA则忽略此项。
				"Stack": 1, // 待交付物品的堆叠数量。仅适用于物品和大型可制作物品。默认值为1。
				"Quality": 2, // 交付物品的品质值。仅适用于物品对象。0 = 无品质，1 = 银星，2 = 金星，4 = 铱星。默认为0；
				"RequireMailReceived": [ "jojaVault", "ccVault" ], // 需要已收到其中一封邮件。游戏列表中还包含其他非邮件内容，如社区中心标志。默认为null表示不需要收到邮件。
				"RequireAllMailReceived": false, // 若为true，则要求"RequireMailReceived"列表中的所有邮件都必须已接收。默认为false。
				"ProbabilityWeight": 1, // 该配件在被选择交付时的权重值。模组会汇总指定组内所有权重值，并通过将此权重除以总权重来计算概率。默认值为1。
				"RandomGroup": "洞穴物品" // 当随机选择物品时，按找到的组别对列表进行分组，并从每组中选取设定的数量。默认值为空字符串，作为默认组别使用。
			},
			{
				"Type": "Tool", // 使用工具时，仅支持可附加的类型。
				"Name": "斧头", // [Axe|Hoe|WateringCan|Pickaxe|Scythe|GoldenScythe|MilkPail|Shears|FishingRod|Pan|ReturnScepter] 工具必备项。支持的工具名称。否则附件将被忽略。
				"UpgradeLevel": 1 // 工具的升级等级。普通工具：0 = 石头，1 = 铜，2 = 钢，3 = 金，4 = 铱。钓竿：0 = 竹竿，1 = 训练竿，2 = 玻璃纤维竿，3 = 铱竿。其他类型忽略此参数。默认值为0。
			},
			{
				"Type": "DGA", //DGA物品
				"Name": "spacechase0.DynamicGameAssets.示例/我的自定义物品", // 使用完整的DGA ID。必需。
				"Stack": 10, // 待交付物品的堆叠数量。仅适用于Objects和BigCraftable类型。默认值为1。
				"Quality": 2 // 待交付物品的品质值。仅适用于物品对象。0 = 无品质，1 = 银星，2 = 金星，4 = 铱星。默认为0；
			},
			{
				"Type": "QualifiedItemId", //任何支持的物品
				"Index": "(0)78", // 物品的合格物品ID。
				"Stack": 10, // 待交付物品的堆叠数量。仅适用于物品和大型可制作物品。默认值为1；
				"Quality": 2 // 待交付物品的品质值。仅适用于物品对象。0 = 无品质，1 = 银星，2 = 金星，4 = 铱星。默认为0；
			}
		],
		"Recipe": "配方名称", // 如果不想在邮件中附加配方，请删除此行。仅当邮件没有其他附件时才有效。对于DGA配方，仅使用ID部分（去掉ModID）
		"AdditionalMailReceived": ["MyMod.AnotherMailId", "VANILLA_FLAG"], // 用于向MailReceived列表添加额外文本。可用于添加原版标志或其他MFM信件ID。
		"MailReceivedToRemove": ["MyMod.AnotherMailThatNeedToBeResent","MyMod.SomeFlagThatWasLockingSomeFeature"], //要从MailReceived列表中移除的文本。可用于触发新邮件、事件、原版标记、阻止其他MFM邮件发送...
		"LetterBG": "CustomLetterBG.png", // 内容包中用于自定义信件背景的文件名。该文件结构应与游戏原版LetterBG文件保持一致。本信件的WhichBG设置将相对于此文件路径。若值为null或删除此项，模组将使用游戏默认的LetterBG文件。
		"WhichBG": 0, //信件背景的ID。0 = 经典，1 = 记事本，2 = 金字塔
		"TextColor": -1, //删除此行以使用默认颜色。若设置了CustomTextColor则此设置将被忽略。-1 = 深红, 0 = 黑, 1 = 天蓝, 2 = 红, 3 = 蓝紫, 4 = 白, 5 = 橙红, 6 = 柠檬绿, 7 = 青, 8 = 深灰
		"CustomTextColorName": "白色", //文本颜色。[http://www.foszor.com/blog/xna-color-chart/] 默认将使用TextColor属性。
		"UpperRightCloseButton": "CustomCloseButton.png", // 内容包中用作自定义关闭按钮的文件名。尺寸应为12x12像素。若为空或删除则使用默认按钮。
		"ReplyConfig": { // 若希望玩家在阅读信件后发送回复。将显示回复选项，根据玩家选择添加一个或多个"已收邮件"。所有与回复相关的额外逻辑都需要基于添加的"已收邮件"来实现。
			"QuestionKey": "MyMod.MyMailId.Question", //用于识别问题的键值。仅限内部使用，但在内容包中应保持唯一以避免回复冲突。
			"QuestionDialog": "发送回复选择你的奖励：", //显示在回复选项上方的问题或文本。如果提供了翻译文件，此处应填写翻译键。
			"Replies": [
				{
					"ReplyKey": "MyMod.MyMailId.Reply1", //必须在问题回复之间保持唯一。
					"ReplyOptionDialog": "我想要种子。", //将显示在回复列表中的选项文本。如果提供了翻译文件，应在此处放置翻译键。
					"RequireMailReceived": [ "jojaVault", "ccVault" ], // 需要已收到其中一封邮件。游戏列表中还包含其他非邮件内容，如社区中心标志。默认为null表示不要求收到邮件。
					"RequireAllMailReceived": false, // 若为true，则要求"RequireMailReceived"列表中的所有邮件都必须已接收。默认为false。
					"MailReceivedToAdd": [ "MyMod.MyMailId.PlayerSeedOption" ], // 要添加到MailReceived列表的文本。可用于触发新邮件、事件、原版标志、阻止其他MFM邮件发送...
					"MailReceivedToRemove": [ "MyMod.MyMailId.PlayerSapplingOption" ], //要从MailReceived列表中移除的文本。可用于触发新邮件、事件、原版标志、阻止其他MFM邮件发送...
					"ReplyResponseDialog": "您请求种子的信件已寄出。", //选择此回复选项后显示的文本。如果提供了翻译文件，应在此处填写翻译键。
					"Cost": 50 //玩家选择该选项需要拥有的金额。如果选择，该金额会立即从玩家的资金中扣除。务必提供一个无需花费的选项，否则可能导致玩家陷入无法继续游戏的困境。
				}
			]
		},
		"Repeatable": false, // 若为true，模组将不会检查该信件ID是否已被送达。默认为false。
		"AutoOpen": false, // 若为true，满足条件后信件将在新一天开始时自动打开。信件ID将被标记为已读，若设置了配方则会自动学习。由于信件不会显示，标题、正文、背景等视觉属性及附件都将不会被使用。
		// 交付条件
		//以下是交付条件。如果不想检查某项条件，请删除对应行。
		"Date": "第一年春10日", // 必须为该日期或之后。格式为"[1-28] [春|夏|秋|冬] Y[1-999]"。
		"Days": [7,14,21,28], // 必须是列表中的天数之一。
		"Seasons": ["秋季"], // 必须选择列表中的季节之一。[春季|夏季|秋季|冬季]
		"Weather": "晴朗", // 必须是游戏内天气。格式为"[晴朗|雨天]"。
		"HouseUpgradeLevel": 2, // 房屋升级等级必须等于或高于定义值。0 - 初始房屋（无理由使用此项，直接删除该行），1 - 厨房，2 - 二楼，3 - 地下室。
		"DeepestMineLevel": 80, // 最深矿井层数必须等于或高于设定值。120是矿井最后一层，121是骷髅洞穴的第一层。
		"CurrentMoney": 10000, // 当前金钱必须等于或高于定义值
		"TotalMoneyEarned": 500000, // 总收益必须达到或超过设定值。
		"FriendshipConditions": // 列表中每个NPC都必须满足所有条件。
		[
			{
				"NpcName": "刘易斯", //NPC名称。可使用自定义NPC。
				"FriendshipLevel": 8, // NPC必须达到或高于此处定义的友谊心等级。默认为0。
				"FriendshipStatus": ["恋爱中","已订婚","已婚"] // [友好|恋爱中|已订婚|已婚|离婚] 要求NPC的友谊状态必须符合列表中某一项。删除此项则不要求特定状态。
			}
		],
		"SkillConditions": // 列表中每个技能必须达到或超过定义等级。可使用原版游戏中所有编码技能，包括幸运。不可使用自定义技能。
		[
			{ "SkillName": "农耕", "SkillLevel": 1 }
		],
		"StatsConditions": // 列表中每项状态值必须达到或超过定义值。选择状态名称或状态标签
		[
			{
				"StatsName": "CheeseMade", //[播种种子|运送物品|烹饪物品|制作物品|鸡下蛋|鸭下蛋|奶牛产奶|山羊产奶|兔子产毛|绵羊产毛|制作奶酪|制作山羊奶酪|发现松露|收集石头|粉碎岩石|锄地|赠送礼物|昏迷次数|平均就寝时间|钓鱼次数|捕获鱼类|击碎巨石|砍伐树桩|行走步数|击杀怪物|发现钻石|发现五彩碎片|发现其他珍贵宝石|发现洞穴胡萝卜|发现铜矿|发现铁矿|发现煤矿|发现硬币|发现金矿|发现铱矿|熔炼金属锭|制作饮料|制作腌制品|回收垃圾数量|粉碎神秘石|游玩天数|清除杂草|砍伐树枝|发现笔记|完成任务|运送星级作物|运送作物|采集物品|击杀史莱姆|开启晶洞|好友数量|个人收入] 默认为空。
				"StatsLabel": "名称", // [exMemoriesWiped|childrenTurnedToDoves|trashCansChecked|boatRidesToIsland|beachFarmSpawns|hardModeMonstersKilled|timesEnchanted] 这些是通过标签识别的当前游戏统计数据，如果添加更多，也应支持。它还将识别其他模组添加的自定义统计标签。默认为null。
				"Amount": 1 // 状态值需等于或大于该数值条件才成立。
			}
		],
		"CollectionConditions": // 列表中的每个收集条件必须达到或超过定义的数量。
		[
			{
				"Collection": "已送达", //[已送达|鱼类|文物|矿物|烹饪|制作] 必填项。
				"Name": "石油", //已弃用，改用ID。对象名称或'制作'配方的名称。若非制作配方集合，将在对象列表中查找该名称以获取索引。若未找到名称，则忽略该字母。将与其他属性结合使用。默认为null。
				"Index": 211, //已弃用，改用Ids。对象的索引。将与其他属性结合使用。默认为null。
				"Ids": [ "282", "苔藓汤" ], //物品ID或合成配方名称。将与其他属性结合使用。数量会被累加以与Amount属性进行比较。
				"Amount": 10 // 集合中对象的总数必须等于或大于该数值才能使条件成立。
			}
		],
		"SpecialDateCondition": // 必须是该日期或之后。
		{
			"SpecialDate": "孩子出生", //[婚礼|孩子出生] 必填
			"YearsSince": 1, //距离事件发生的年数。0表示匹配实际日期，1表示次年。默认为0。
			"WhichChild": 1 //如果SpecialDate属性为ChildBirth，将引用哪个孩子。默认为1；
		},
		"ExpandedPreconditionsUtility": "d 周一 周五/拥有物品 粉色蛋糕/未完成乔家超市/非雨天", //需要安装扩展前置条件工具模组。请参阅该模组文档了解具体运作方式。若未加载该模组，信件将不会被送达。
		"ExpandedPrecondition": [ "!z 春季/t 600 1000", "f 莱纳斯 1000/w 雨天/z 春季", "f 莱纳斯 2500" ], //需要安装扩展前置条件功能模组。请参阅该模组文档了解其运作方式。如果未加载该模组，信件将无法送达。
		"RandomChance": 0.25, // 模组会检查0到1之间的随机数是否低于给定数值。同一存档、同一天、同一封信件将始终获得相同结果以防止作弊。
		"Buildings": ["鸡舍","大鸡舍","豪华鸡舍"], // 需要农场中当前已建造其中一种建筑。
		"RequireAllBuildings": false, // 若为true，则要求农场当前必须已建造"Buildings"列表中所有建筑。默认为false。
		"MailReceived": ["jojaVault","ccVault"], // 要求已收到其中一封邮件。游戏列表中还包含其他非邮件内容，比如社区中心标志。
		"RequireAllMailReceived": false, // 若为true，则要求必须收到"MailReceived"列表中的所有邮件。默认为false。
		"MailNotReceived": ["jojaVault","ccVault"], // 要求邮件未被接收。游戏列表中还包含其他非邮件内容，比如社区中心标志。
		"EventsSeen": [ "4", "32423" ], // 要求玩家已触发其中至少一个事件。应为字符串格式，但为保持向后兼容性也支持整数形式。
		"RequireAllEventsSeen": false, // 若为true，则要求玩家必须已看过"EventsSeen"列表中的所有事件。默认为false。
		"HasMods": [ "SMAPI.ConsoleCommands", "SMAPI.SaveBackup" ], // 需要加载其中一个模组。应为模组的UniqueID。
		"RequireAllMods": false, // 如果为true，则要求"HasMods"列表中的所有模组都已加载。默认为false。
		"EventsNotSeen": [ "4", "32423" ], // 要求玩家未触发过这些事件。应为字符串格式，但为保持向后兼容性也支持整数形式。
		"RecipeKnown": ["披萨","求生汉堡"], // 要求玩家已学会其中一种配方
		"RequireAllRecipeKnown": false, // 若为true，则要求玩家必须学会"RecipeKnown"列表中的所有配方。默认为false。
		"RecipeNotKnown": ["野生鱼饵"], // 要求玩家尚未学会该配方。
		"KeepValid": false // 若为true，满足条件后邮件将保持有效状态直至被阅读。默认为false。
	}
]

加载一封简单的信件，若玩家之前未阅读过则会显示，一旦被玩家打开后将不再重复投递：

MailRepository.SaveLetter(
	new Letter(
		"信件唯一标识"
		"自定义信件文本。"
		(l) => !Game1.player.mailReceived.Contains(l.Id)
		,(l)=>Game1.player.mailReceived.Add(l.Id)
	)
);

像之前一样加载一封简单的信件，但附带了5颗绿宝石：

MailRepository.SaveLetter(
    new Letter(
		"信件唯一标识符"
		,"自定义信件文本。"
		,new List<Item> { new StardewValley.Object(60,5) }
		,(l)=>!Game1.player.mailReceived.Contains(l.Id)
		,(l)=>Game1.player.mailReceived.Add(l.Id)
    )
);

玩家不会收到相同的物品，而是获得由getOne()方法返回的一个副本。

加载一封简单的信件，其中包含一个烹饪食谱的教学内容，如果玩家尚未掌握该食谱，信件将会送达。模组会在玩家加载时自动教授食谱，此处无需回调：

MailRepository.SaveLetter(
    new Letter(
		"信件唯一标识"
		, "自定义信件文本。"
		, "配方唯一名称"
		, (l) => !Game1.player.cookingRecipes.ContainsKey(l.Recipe)
    )
);

"RecipeUniqueName" 必须与存储在 "Data//CookingRecipes" 或 "Data//CraftingRecipes" 中的名称相同。

加载一个带有不同文本和背景的简单信件：

MailRepository.SaveLetter(
    new Letter(
		"信件唯一标识符"
		,"自定义字母文本。"
		,(l)=>!Game1.player.mailReceived.Contains(l.Id)
		,(l)=>Game1.player.mailReceived.Add(l.Id)
		1
    ){文字颜色=8}
);

加载带有自定义背景的简单信件：

MailRepository.SaveLetter(
    new Letter(
		"信件唯一标识"
		,"自定义字母文本。"
		,(l)=>!Game1.player.mailReceived.Contains(l.Id)
		,Game1.player.mailReceived.Add(l.Id)
		1
    ){
		LetterTexture=helper.Content.Load<Texture2D>("CustomLetterBG.png")
		,文本颜色=4
    }
);

其中CustomLetterBG.png是一个图像文件，其结构与"LooseSprites//letterBG"相同

加载一个简单的信件，包含文本和标题的翻译。

MailRepository.SaveLetter(
	new Letter(
		"信件唯一标识符"
		"我的信件翻译关键文本"
		(l) => !Game1.player.mailReceived.Contains(l.Id)
		,(l)=>Game1.player.mailReceived.Add(l.Id)
	){
		Title = "我的信件翻译键标题",
		I18N = 助手.翻译
    }
);