农民免费瑜伽

农民免费瑜伽

农民免费瑜伽让事件可以临时替换农民的角色精灵图集——身体、衬衫和裤子——换成完全自定义的图集，这样事件就能展示原版动画集无法呈现的姿态和动作。它完全由内容包驱动：农民免费瑜伽本身不附带任何美术或事件，它是一个供其他模组接入的框架。

本文档面向所有使用农民免费瑜伽构建内容包的开发者。

---

需求

你的内容包需要在 manifest.json 中声明两个依赖项：

• Content Patcher — 用于加载你的 PNG 文件并将事件添加到游戏中（Load/EditData）。
• FarmerYoga（唯一 ID ioicaleb.farmeryoga）— 用于从事件中触发精灵图集替换，并为你的图集自动生成头发/配饰偏移文件。

"Dependencies": [
    { "UniqueID": "Pathoschild.ContentPatcher" },
    { "UniqueID": "ioicaleb.farmeryoga" }
]

文件结构

一个最小的内容包结构如下：

YourPack/
├── manifest.json
├── content.json
├── FY_Offsets.json ← 首次加载时自动生成，之后由你编辑
└── <子文件夹> (如果你想将它们组织到子文件夹中)/
        ├── farmer_<后缀>.png
        ├── farmer_girl_<后缀>.png
        ├── shirts_<后缀>.png
        └── pants_<后缀>.png

<后缀> 是你为此精灵图集选择的任意简短名称（例如 yoga1）。它在这四个图片文件名以及激活它们的游戏事件命令中保持一致。 <子文件夹> 完全可选。你可以按照自己的喜好存储图片。

content.json

使用 Content Patcher 的 Load 操作将你的图片注册到农民免费瑜伽期望的资源名称下（Characters/Farmer/farmer_<后缀>、farmer_girl_<后缀>、shirts_<后缀>、pants_<后缀>），并使用 EditData 添加你的事件。例如：

{
    "Format": "2.2.0",
    "Changes": [
        { "Action": "Load", "Target": "Characters/Farmer/farmer_<后缀>", "FromFile": "Images/farmer_<后缀>.png" },
        { "Action": "Load", "Target": "Characters/Farmer/farmer_girl_<后缀>", "FromFile": "Images/farmer_girl_<后缀>.png" },
        { "Action": "Load", "Target": "Characters/Farmer/shirts_<后缀>", "FromFile": "Images/shirts_<后缀>.png" },
        { "Action": "Load", "Target": "Characters/Farmer/pants_<后缀>", "FromFile": "Images/pants_<后缀>.png" },
        {
           "Action": "EditData",
           "Target": "Data/Events/Farmhouse",
           "Entries": {
               "yourEventKey": "none/5 5/farmer 5 7 2/skippable/changeFarmerSprite <后缀>/ ... 你的事件 ... /pause 1000/globalFade/pause 500/end"
            }
        }
    ]
}

对于给定的后缀，你始终需要提供全部四个 farmer_/farmer_girl_/shirts_/pants_ 图片，即使衬衫或裤子美术只是完全透明的占位图——农民免费瑜伽不要求它们包含任何内容，但它会在这些资源名称下查找它们。

在事件中使用

在任何事件脚本中，可以使用两个自定义事件命令：

• changeFarmerSprite <后缀> — 将农民切换到你的自定义图集，在此期间隐藏他们装备的衬衫/裤子，并为此后缀换入你的头发/配饰偏移。
• changeFarmerSprite base — 恢复一切：纹理、头发/配饰偏移，以及玩家真实的衬衫/裤子。

你不必严格地自己调用 changeFarmerSprite base——它会在事件结束的那一刻自动发生（Game1.eventUp 变为 false）——但如果你想在事件结束前切换回去，在事件中途显式调用它也是可以的。

在 end 前务必淡出

每个自定义精灵事件在 end 之前必须以 globalFade（其后跟一个短暂的 pause）结束。 事件收尾时，在游戏自身的清理运行期间，会短暂地显示农民真实的原版外观一帧，这与农民免费瑜伽所做的任何事情无关——这是星露谷物语事件行为的正常现象，不是 bug，社区广泛采用的标准修复方法与你在实现流畅过渡时想要的方案相同：

.../pause 1000/globalFade/pause 500/end

跳过这一步会在事件结束时短暂出现农民正常衣服的突兀闪烁。

精灵图集规范

所有图集均使用每个姿态 16×32 像素的网格，与原版游戏规范一致。

• farmer_<后缀>.png / farmer_girl_<后缀>.png — 你的自定义身体。每行高 32 像素。每行最左侧的 6 列才计为不同的姿态——这与原版布局一致，其中这 6 列右侧的列是这同一 6 个姿态的手臂和配饰子帧，而非额外的姿态。你的事件中的 animate/frame 命令应始终只引用此每行 6 个范围内的索引。
• shirts_<后缀>.png — 8×8 单元。不需要与身体图集的尺寸匹配——只需其自身的内部帧数/顺序与身体按姿态一一对应（这里的帧 N 应与身体图集中的帧 N 是同一姿态）。
• pants_<后缀>.png — 16×32 单元，与衬衫的姿态一一对应。
• 这三个文件均按从左到右、从上到下的顺序读取，并根据每个文件自身的宽度自动换行——你不需要将图集填充到某个固定大小，只需确保它包含你事件使用的每个姿态的单元即可。
• 没有内置的"裸体"标记或覆盖规则。 你在身体图集躯干/腿部区域绘制的静止肤色即默认外观——无需切换任何东西，也没有任何东西阻止裤子/衬衫被绘制得尽可能少或尽可能多。农民免费瑜伽完全抑制原版的后备衬衫/裤子，所以你的美术是屏幕上唯一显示的内容。

头发和配饰偏移 (FY_Offsets.json)

由于你的自定义姿态不匹配原版动画集，头发和配饰需要它们自己的逐帧位置偏移，否则它们会相对于你的自定义身体绘制在错误的位置。

你的内容包首次加载时，农民免费瑜伽会扫描你的 farmer_*.png 文件并写入一个 FY_Offsets.json 在你的内容包根目录，为每个找到的姿态预先填充 [0, 0]。从那里，使用游戏内 SMAPI 控制台（不是事件命令）进行调整：

setFrameOffset <后缀> <帧索引> <X偏移> <Y偏移>
getFrameOffset <后缀> <帧索引>

• 帧索引 是上述每行 6 个身体方案中的姿态索引（从 0 开始）。
• 偏移以像素为单位；正 X 向右，正 Y 向下。
• setFrameOffset 会立即写回你内容包的 FY_Offsets.json，因此更改在多次会话间持久保存——测试一个姿态，微调它，然后重新加载事件查看效果。
• 每个 SheetID（你的<后缀>）在所有已加载的农民免费瑜伽内容包中必须唯一，而不仅仅是你自己的——如果两个内容包注册了相同的后缀，只会使用其中一个，并且控制台会记录一个警告，告诉你哪个内容包胜出。

已知限制

头发、帽子和配饰不会被农民免费瑜伽重新定位，超出上述偏移系统的范围。它们是使用游戏正常的逐帧偏移表绘制的，重定向到你的 FY_Offsets.json 值——但当前没有等效的处理方式适用于你的姿态需要比简单 X/Y 微调更复杂的情况（例如某些姿态中头发需要完全翻转或重新造型）。

目前不支持多人游戏。自定义身体纹理是一个同步字段，应该对其他玩家可见，但衬衫/裤子的抑制和覆盖仅限于你自己的客户端对你自己的农民的视图——其他玩家可能会看到你的自定义身体，但默认的原版衬衫/裤子仍会显示，而不是你的自定义服装。在重新审视此问题之前，任何多人游戏使用均视为不受支持。

没有自动验证衬衫/裤子的姿态数量是否与身体图集匹配。如果 shirts_<后缀> 或 pants_<后缀> 的姿态少于你的身体图集实际使用的姿态，不匹配的姿态将环绕以重用早期帧，而不是报错——请视觉上检查你的完整姿态范围，而不要仅凭几个测试帧假设覆盖完整。

路线图

尚未实现，但计划在未来的更新中推出：

• 超越简单逐帧 X/Y 偏移的适当头发/帽子/配饰处理。
• 多人游戏支持。
• 支持性别中立/非二元玩家模型（目前，图集仅沿游戏现有的男性/farmer_-女性/farmer_girl_ 约定进行拆分）。