← 目录
此页面解释了如何自定义建筑。这是面向模组开发者的高级指南。
格式
您可以通过编辑 Data/Buildings 素材来创建/编辑建筑。
此素材文件内含一个“字符串 → 数据模型”查询，其中：
所需字段
| 字段
|
效果
|
Name
Description
|
一个模板字符串用于显示名称和描述（例如建造菜单中）。
|
| Texture
|
游戏 Content 文件夹下建筑贴图的素材名称。
|
建造
| 字段
|
效果
|
| Builder
|
（可选）负责建造此建筑的 NPC。原版数值为Robin和Wizard，但如果 C# 模组提供了其他选项，您也可以指定其他的值。默认为 Robin。若为空，则不会出现在任何菜单。
|
| BuildCost
|
（可选）建造此建筑花费的钱。默认为  0。
|
| BuildMaterials
|
（可选）建造此建筑所需的材料，为包含如下字段的数据模型组成的列表：
| 字段
|
效果
|
| Id
|
（可选）此列表项的唯一字符串ID。若未指定，默认未相应的 ItemId 字段。
|
| ItemId
|
所需的物品ID（限定性或非限定性）。
|
| Amount
|
所需数量。
|
|
| BuildDays
|
（可选）建造天数。1 代表次日建好。若设为 0，则会立即建好。
|
| BuildCondition
|
（可选）一个游戏状态查询，指示现在此建筑能否出现在建造菜单中。默认为总是出现。
|
| BuildMenuDrawOffset
|
（可选）将建筑贴图绘制到建造目录的像素位移。默认为空。
|
| AdditionalPlacementTiles
|
（可选）当在建造菜单中建造该建筑时，视作此建筑一部分的额外的地块。例如，农舍利用此字段来确保台阶没有被占用。此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| TileArea
|
相对于建筑左上角的地块区域，为包含X、Y、Width、Height 字段的数据模型。
|
| OnlyNeedsToBePassable
|
（可选）此区域是否允许正常情况下无法建造建筑物、但可以通行的地块。例如，此字段用于确保入口可通行。默认为 false。
|
|
| IndoorItems
|
（可选）建筑被建造或升级后，放置在其内部的物品。此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| Id
|
当前列表项的唯一字符串ID。
|
| ItemId
|
欲放置物品的限定性物品ID。
|
| Tile
|
放置此物品的地块坐标。为包含 X 和 Y 字段的数据模型。
|
| Indestructible
|
（可选）是否阻止此玩家摧毁、捡起、移动此物品。默认为 false。
|
|
| MagicalConstruction
|
（可选）是否为魔法建筑。若是，则会在选取该建筑的蓝图时将建筑菜单换为魔法主题，并立即完成建造。
|
| AddMailOnBuild
|
（可选）当此建筑被首次建造时，向所有玩家发送的信件ID的列表。
|
升级
| 字段
|
效果
|
| BuildingToUpgrade
|
（可选）欲升级建筑的ID，可以忽略此字段，代表允许按建造新建筑的方式构建此建筑。例如，大鸡舍的此字段为 "Coop"。同一个建筑可以有多个升级选项，而届时游戏会询问玩家选取哪种升级。
|
| IndoorItemMoves
|
（可选）当升级现有建筑时，如何将旧建筑的内部物品移动到新建筑的内部地图。此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| Id
|
此列表项的唯一字符串ID。
|
| Source
|
欲搬移的地块坐标。
|
| Destination
|
将物品搬移到的地块坐标。
|
| Size
|
（可选）欲移动区域的地块尺寸。为包含 X 和 Y 字段的数据模型。默认为 1x1。若指定多个地块，则 Source 和 Destination 分别代表左上角地块。
|
|
| UpgradeSignTile
|
（可选）罗宾正在建造升级时，放置升级标牌的地块位置，相对于左上角。其形如 "<x>, <y>"。若建筑内部类型为 Shed 则大约默认为 "5, 1"，否则为 "0, 0"。
|
| UpgradeSignHeight
|
（可选）罗宾正在建造升级时，升级标牌的像素高度。默认为 0。
|
外部行为
| 字段
|
效果
|
| Size
|
（可选）建造此建筑时的宽度和高度。单位为地块。默认为 1x1。
|
| CollisionMap
|
（可选）一个 ASCII 文本块，用于指示玩家能通行的建筑地块，其中每一个字符可以为 X（禁止通行）或 O（可以通行）。默认为全部禁止通行。
例如，马厩覆盖一个 2x4 地块区域，且仅有前两个地块能通行：
XXXX
XOOX
此碰撞地图被解析后，每行首尾的空白字符会被删除。在 JSON 中，您可以以两种方法添加空白字符：
// single line with \n line breaks
"CollisionMap": "XXXX\nXOOX"
// multi-line with optional indentation
"CollisionMap": "
XXXX
XOOX
"
|
| HumanDoor
|
（可选）门的位置。可以点击开门，进入建筑。位置相对于左上角地块。默认为不可用。
|
| AnimalDoor
|
（可选）动物门的位置，可供动物进出建筑。若建筑内部为动物地点，则此字段的数据模型应当拥有 X、Y、Width、Height（相对于左上角，单位为地块）。默认为不可用。
|
AnimalDoorOpenDuration
AnimalDoorCloseDuration
|
（可选）动物们开门/关门动画的持续时长，单位为毫秒。若省略，则门会瞬间开关。
|
AnimalDoorOpenSound
AnimalDoorCloseSound
|
（可选）每次开关动物门时播放的音效。默认为不可用。
|
外部外观
| 字段
|
效果
|
| SourceRect
|
（可选）此建筑在 Texture 贴图集中的像素区域，为包含 X、Y、Width 和 Height 字段的数据模型。默认为整张贴图集。
|
| Skins
|
（可选）罗宾目录中可供选择的外观（例如联机小屋的石头/木板/原木风格），以作为 Texture 的补充。此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| Id
|
此皮肤的唯一字符串ID。
|
Name
Description
|
一个模板字符串，用于显示皮肤名称和描述。
|
| Texture
|
游戏的 Content 文件夹下的贴图集的素材名称。
|
| Condition
|
（可选）指示此皮肤是否可用的游戏状态查询。已经使用此皮肤的建筑则不受影响。默认为总是可用。
|
BuildDays
BuildCost
BuildMaterials
|
（可选）若设置此字段，则会覆盖建筑数据中的的等价字段。
|
| ShowAsSeparateConstructionEntry
|
（可选）此皮肤是否应当在建造菜单中独立显示（例如联机小屋）。默认为 false。
|
| Metadata
|
（可选）相当于建筑物的 Metadata 字段。此字段定义的属性会在使用此皮肤的情况下被添加到建筑的元数据，并覆盖先前的同名属性（若可用）。默认为 false。
|
|
| FadeWhenBehind
|
（可选）玩家站在建筑后面时是否要将建筑变成半透明的。默认为 true。
|
| DrawOffset
|
（可选）建筑绘制在世界中时，对其贴图施加的偏移。默认为 0。
|
| SeasonOffset
|
（可选）每个季节应用的像素偏移。这会将 SourceRect 乘上相应的偏移量，其中 0 为春季、1 为夏季、2 为秋季、3 为冬季。默认为 0，此时所有季节使用相同的 SourceRect。
|
| SortTileOffset
|
（可选）绘制渲染层叠时的 Y 轴地块偏移。例如，此字段设为 2.5 表示渲染时所用的坐标要比真实坐标上移 2.5 地块，这主要用于处理图层顺序。默认为 0。
|
| AllowsFlooringUnderneath
|
（可选）下方是否可以放置地板，以及建造该建筑是否会保留相应地块的地板。默认为 true。
|
| DrawLayers
|
（可选）一个贴图列表，列出了需要画在建筑物前或建筑物后的贴图，支持条件和动画。此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| Id
|
此列表项的唯一字符串ID。
|
| SourceRect
|
texture 中要绘制的像素区域，格式为 "<x> <y> <width> <height>"。若此贴图使用 FrameCount 指定了动画，则此字段为第一帧的区域。
|
| DrawPosition
|
绘制贴图的左上角的地块坐标，相对于建筑左上角的地块坐标。
|
| Texture
|
（可选）欲绘制贴图集的素材名称。默认为建筑的默认 Texture 字段。
|
| DrawInBackground
|
（可选）是否要将此贴图绘制在建筑后方（底层），而非前面。
|
| SortTileOffset
|
（可选）绘制渲染层叠时的 Y 轴地块偏移。例如，此字段设为 2.5 表示渲染时所用的坐标要比真实坐标上移 2.5 地块，这主要用于处理图层顺序。默认为 0。
|
| OnlyDrawIfChestHasContents
|
（可选）Chests 中定义的箱子ID，只有当此箱子内含物品时才绘制此贴图。若箱子为空，则不会渲染此贴图。默认为 none。
|
FrameCount
FramesPerRow
FrameDuration
|
（可选）若 FrameCount 大于 1，则此贴图会自动动画化。对于每一帧，相应的 SourceRect 字段会右移 Width 像素，共右移 FramesPerRow - 1 次，然后下移 Height。每一帧都会在屏幕上停留 FrameDuration 毫秒再切换到下一帧。
例如，假设您将 FrameCount 设为 6，FramesPerRow 设为 3，则要求各帧在贴图集中排布如下（其中第 1 帧对应于 SourceRect）：
┌───┬───┬───┐
│ 1 │ 2 │ 3 │
├───┼───┼───┤
│ 4 │ 5 │ 6 │
└───┴───┴───┘
|
| AnimalDoorOffset
|
（可选）打开动物门时的绘制图层施加的像素偏移。当门打开时，像素偏移会乘以打开程度的百分比（例如，半开使得偏移减半）。
|
|
| DrawShadow
|
（可选）是否在建筑贴图的边缘绘制自动阴影。默认为 true。
|
内部
| 字段
|
效果
|
| IndoorMap
|
（可选）室内地图，即 Maps 文件夹下欲加载的地图名称。例如，"Shed" 会加载小屋的 Maps/Shed 地图。
|
| IndoorMapType
|
（可选）管理此建筑内部地点的 C# 地点类的全名。此字段必须为原版类型之一，以防存档时崩溃。但原版名称太多，我们只列出比较常用的：
- StardewValley.AnimalHouse；
- StardewValley.Locations.Cabin；
- StardewValley.Locations.Cellar；
- StardewValley.Locations.DecoratableLocation；
- StardewValley.Locations.FarmCave；
- StardewValley.Locations.FarmHouse；
- StardewValley.Shed;
- StardewValley.SlimeHutch.
默认为通用的 StardewValley.GameLocation 类。
|
| NonInstancedIndoorLocation
|
（可选）希望给此建筑内部分配的，现有的全局地点名称。例如农舍的全局地点名称为 FarmHouse，而温室为 Greenhouse。
每个地点只能用于一个建筑。若某个地点已经被使用（例如，玩家希望建造两个这种建筑），则后面建造的建筑会转而使用 IndoorMap 和 IndoorMapType 。例如，第一个温室会使用全局的 Greenhouse 未知，而后续建的温室会使用独立的实例化地点。
|
| MaxOccupants
|
（可选）能生活在此建筑中的最大动物数量。
|
| AllowAnimalPregnancy
|
（可选）动物能否在此建筑中怀孕和产仔。默认为 false。
|
| ValidOccupantTypes
|
（可选）一个建筑ID的列表，能在列表中的建筑中生活的动物也能在此建筑中生活。例如，[ "Barn", "Coop" ] 使得此建筑能够容纳畜棚动物和鸡舍动画。默认为空。
|
物品处理
| 字段
|
效果
|
| HayCapacity
|
（可选）能存储在此建筑中的干草容量。若建在农场上，则此建筑会像筒仓一样为农场提供可用的干草。
|
| ItemConversions
|
（可选）使用 Chests 中定义的物品栏交互时，把输入物品转换为输出物品的规则。
此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| Id
|
当前规则的唯一字符串ID。
|
| RequiredTags
|
一个上下文标签列表，用于匹配输入物品。一个输入物品仅当其具有全部标签时才会被接受。
|
| SourceChest
|
Chests 中定义的箱子 ID，用于获取输入物品。
|
| DestinationChest
|
Chests 中定义的箱子 ID，用于存储售出物品。
|
| ProducedItems
|
输入物品转换为的输出物品。此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| 通用字段
|
参见物品生成字段以了解机器输出支持的通用物品字段。
若设为返回多个物品的物品查询，则随机选取一个返回的物品。
|
| Chance
|
（可选）产出此物品的概率，介于 0（从不产出）到 1（总是产出）。默认为 1（100% 概率）。
|
|
| RequiredCount
|
（可选）消耗的输入物品数量。默认为 1。
|
| MaxDailyConversions
|
（可选）一天之内最多可以加工几件输入物品。每条输入-输出规则独立计算互不干扰（假设您有两个最大加工量为 1 的规则，则可各转换一个）。设为 -1 表示加工数量无限。默认为 1。
|
|
| Chests
|
（可选）能够通过此建筑外部某个地块输入/输出的物品。有单独的 ItemConversions 字段用于允许的物品。此字段为包含如下字段的数据模型：
| 字段
|
效果
|
| Id
|
当前箱子的唯一字符串ID。
此 ID 会被 ItemConversions 字段引用。
|
| Type
|
存储类型。必须下列之一：
- Chest：点击时显示正常的箱子界面。
- Collect：向玩家提供可收集的物品。点击此地块不会发生任何事情（若没有可收集的物品），或直接收集物品（若仅提供一个物品），或显示一个只拿不放的物品栏界面。
- Load：使得玩家提供给该建筑物品以供加工。
|
| Sound
|
（可选）当玩家点开箱子时发出的声音。
|
InvalidItemMessage
InvalidCountMessage
ChestFullMessage
|
（可选）一个模板字符串，当玩家试图以如下方式向箱子中添加物品时就会显示相应消息：
- 物品不支持。
- 物品支持，但背包中没有足够数量的物品。
- 箱子没有多余空间。
若忽略，则会无视玩家交互，也不会显示消息。
|
| InvalidItemMessageCondition
|
（可选）一个游戏状态查询，指示是否应当显示 InvalidItemMessage。可用物品相关的查询，例如 ITEM_TYPE。默认为总是显示。
|
| DisplayTile
|
（可选）箱子在建筑物外面的地块坐标，相对于建筑物左上角。其格式为 "<x>, <y>"。此字段会影响“物品待收集”气泡的位置。若忽略，则禁用气泡。
|
| DisplayHeight
|
（可选）若 DisplayTile 非空，则此字段指示箱子地块的高度，例如 1.5。
|
|
地块交互
| 字段
|
效果
|
| ActionTiles
|
（可选）一个地块列表。玩家可以点击此处的地块以触发一个 Action 地块属性。此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| Id
|
当前列表项的唯一字符串ID。
|
| Tile
|
地块坐标，相对于建筑左上角。
|
| Action
|
待实施动作的模板字符串，不包含 Action 前缀。例如，动作字符串 "Dialogue Hi there @!" 会显示一个类似于 "Hi there <player name>!" 的信息框。此模板字符串会在动作触发前被调用。参见地块性质列表以了解常用的 Action 取值。
|
|
| DefaultAction
|
（可选）若点击的地块不是 ActionTiles 地块，触发的默认地块动作。默认为空。
|
| TileProperties
|
（可选）设置的地块属性。此字段为包含如下字段的数据模型所组成的列表：
| 字段
|
效果
|
| Id
|
此列表项的唯一字符串ID。
|
| Name
|
欲设置的地块属性名称。
|
| Value
|
（可选）欲设置的地块属性值。若忽略，则设为空。
|
| Layer
|
地图的目标图层。
|
| TileArea
|
需要添加此属性的地块，相对于建筑碰撞箱的左上角。此字段为包含 X、Y、Width 和 Height 字段的数据模型。
|
|
| AdditionalTilePropertyRadius
|
（可选）将建筑四周指定半径的区域也纳入 TileProperties 检查。默认为 0，也就是仅有建筑正常范围内的地块会被检查。
|
高级
| 字段
|
效果
|
| Metadata
|
（可选）用于此建筑的自定义属性的列表，Skins 中的每个皮肤都可以重载此列表。默认为空。
原版游戏可以识别如下属性：
| 属性
|
描述
|
ChimneyPosition: <x> <y>
|
（可选）在建筑外面放置烟囱的像素位置。这与农舍烟囱逻辑相同（若建筑内部有点火的壁炉，则渲染烟雾）。
|
ChimneyPosition[upgrade level]: <x> <y>
|
（可选，仅用于农舍或联机小屋）。重载指定升级等级的 ChimneyPosition 字段。其中，0 代表初始的农舍/联机小屋。若当前升级等级没有对应的重载，则会使用可用的最高级重载（若有）。例如， ChimneyPosition3 用于第 3 次房屋升级（第 4 次升级没有单独的重载项而是沿用第 3 次升级）。
|
此字段也可以包含任何自定义属性，后者可以被 C# 模组以 building.GetMetadata(key) 读取。
|
| BuildingType
|
（可选）用于实例化建筑的 C# 类型的全名。默认为通用的 Building 示例。
⚠ 警告： 这主要用于支持原版建筑类型，例如 StardewValley.Shed。将此字段设为非原版建筑类型，会在写入存档时崩溃，且可能在多人游戏中导致崩溃。如果您需要自定义行为，请考虑如何在 C# 中基于建筑类型处理它，而不是创建自定义的子类；否则您可以使用 SpaceCore 等框架模组来处理序列化和多人游戏同步。
|
| ModData
|
（可选）一个“字符串 → 字符串”查询，用于获取建筑建好时附加在其上的 modData 值。
|
| CustomFields
|
此建筑的自定义字段。
|
Modding:Buildings
沪公网安备 31011002002714 号