Modding:Buildings

← Index

This page explains how the define custom buildings. This is an advanced guide for mod developers.

Format

You can create/edit buildings by editing the Data/Buildings asset. Vanilla buildings have their names and descriptions defined as tokenizable strings in Strings/Buildings.

This consists of a string → model lookup, where...

• The key is a unique string ID for the building type.
• The value is a model with the fields listed below.

Required fields

field	effect
Name Description	A tokenizable string for the display name and description (e.g. shown in the construction menu).
Texture	The asset name for the texture under the game's Content folder.

Construction

field	effect
Builder	(Optional) The NPC from whom you can request construction. The vanilla values are Robin and Wizard, but you can specify a different name if a C# mod opens a construction menu for them. Defaults to Robin. If set to null, it won't appear in any menu.
BuildCost	(Optional) The gold cost to construct the building. Defaults to data-sort-value="0">0g.
BuildMaterials	(Optional) The materials you must provide to start construction, as a list of models with these fields: field effect Id (Optional) The unique string ID for this entry within the current list. Defaults to the ItemId if not specified. ItemId The required item ID (qualified or unqualified). Amount The number of the item required.
BuildDays	(Optional) The number of days needed to complete construction (e.g. 1 for a building completed the next day). If set to 0, construction finishes instantly. Defaults to 0.
BuildCondition	(Optional) A game state query which indicates whether the building should be available in the construction menu. Defaults to always available.
BuildMenuDrawOffset	(Optional) A pixel offset to apply to the building sprite when drawn in the construction menu. Default none.
AdditionalPlacementTiles	(Optional) The extra tiles to treat as part of the building when placing it through the construction menu. For example, the farmhouse uses this to make sure the stairs are clear. This consists of a list of models with these fields: field effect TileArea The tile area relative to the top-left corner of the building, specified as an object with X, Y, Width, and Height fields. OnlyNeedsToBePassable (Optional) Whether this area allows tiles that would normally not be buildable, so long as they are passable. For example, this is used to ensure that an entrance is accessible. Default false.
IndoorItems	(Optional) The items to place in the building interior when it's constructed or upgraded. This consists of a list of models with these fields: field effect Id The unique string ID for this entry within the current list. ItemId The qualified item ID for the item to place. Tile The tile position at which to place the item, specified as an object with X and Y fields. Indestructible (Optional) Whether to prevent the player from destroying, picking up, or moving the item. Default false. ClearTile (Optional) Whether to remove any item on the target tile, except for one matching the indoor item's ItemId. The previous contents of the tile will be moved into the lost and found if applicable. Default true.
MagicalConstruction	(Optional) Whether the building is magical. This changes the carpenter menu to a mystic theme while this building's blueprint is selected, and completes the construction instantly when placed.
AddMailOnBuild	(Optional) A list of letter IDs to send to all players when the building is constructed for the first time.

Upgrades

field	effect
BuildingToUpgrade	(Optional) The ID of the building for which this is an upgrade, or omit to allow constructing it as a new building. For example, the Big Coop sets this to "Coop". Any numbers of buildings can be an upgrade for the same building, in which case the player can choose one upgrade path.
IndoorItemMoves	(Optional) When applied as an upgrade to an existing building, the placed items in its interior to move when transitioning to the new map. This is a list of models with these fields: field effect Id The unique string ID for this entry within the current list. Source The tile position on which any item will be moved. Destination The tile position to which to move the item. Size (Optional) The tile size of the area to move, specified as a model with X and Y fields. Defaults to a 1×1 area. If this is multiple tiles, the Source and Destination specify the top-left coordinate of the area.
UpgradeSignTile	(Optional) The tile position relative to the top-left corner of the building where the upgrade sign will be placed when Robin is building an upgrade, in the form "<x>, <y>". Defaults to approximately "5, 1" if the building interior type is Shed, else "0, 0".
UpgradeSignHeight	(Optional) The pixel height of the upgrade sign when Robin is building an upgrade. Defaults to 0.

Exterior behavior

field	effect
Size	(Optional) The building's width and height when constructed, measured in tiles. Defaults to a 1 x 1 area.
CollisionMap	(Optional) An ASCII text block which indicates which of the building's tiles the players can walk onto, where each character can be X (blocked) or O (passable). Defaults to all tiles blocked. For example, a stable covers a 2x4 tile area with the front two tiles passable: XXXX XOOX When the collision map is parsed, leading/trailing whitespace is trimmed (both for the entire map and for each line). In JSON, you can specify it in two forms: // single line with \n line breaks "CollisionMap": "XXXX\nXOOX" // multi-line with optional indentation "CollisionMap": " XXXX XOOX "
HumanDoor	(Optional) The position of the door that can be clicked to warp into the building interior. This is measured in tiles relative to the top-left corner tile. Defaults to disabled.
AnimalDoor	(Optional) The position and size of the door that animals use to enter/exit the building, if the building interior is an animal location, specified as an object with X, Y, Width, and Height fields. This is measured in tiles relative to the top-left corner tile. Defaults to disabled.
AnimalDoorOpenDuration AnimalDoorCloseDuration	(Optional) The duration of the open/close animation for the animal door, measured in milliseconds. If omitted, the door switches to the open/closed state instantly.
AnimalDoorOpenSound AnimalDoorCloseSound	(Optional) The sound which is played once each time the animal door is opened/closed. Disabled by default.

Exterior appearance

field	effect
SourceRect	(Optional) The building's pixel area within the Texture, specified as an object with X, Y, Width, and Height fields. Defaults to the entire texture.
Skins	(Optional) The appearances which can be selected from Robin's menu (like stone/plank/log cabins), in addition to the default appearance based on Texture. This consists of a list of models with these fields: field effect Id The unique string ID for the skin. Name Description Tokenizable strings for the skin's display name and description. Texture The asset name for the texture under the game's Content folder. Condition (Optional) A game state query which indicates whether this skin should be available to apply. This doesn't change buildings which already have it applied. Defaults to always true. BuildDays BuildCost BuildMaterials (Optional) If set, overrides the equivalent field in the building data. ShowAsSeparateConstructionEntry (Optional) Whether this skin should be shown as a separate building option in the construction menu (like cabins). Default false. Metadata (Optional) Equivalent to the Metadata field on the building. Properties defined in this field are added to the building's metadata when this skin is active, overwriting the previous property with the same name if applicable. Default none.
FadeWhenBehind	(Optional) Whether the building should become semi-transparent when the player is behind it. Default true.
DrawOffset	(Optional) A pixel offset applied to the building sprite's placement in the world. Default 0.
SeasonOffset	(Optional) A pixel offset to apply each season. This is applied to the SourceRect position by multiplying the offset by 0 (spring), 1 (summer), 2 (fall), or 3 (winter). Default 0, so all seasons use the same source rect.
SortTileOffset	(Optional) A Y tile offset applied when figuring out render layering. For example, a value of 2.5 will treat the building as if it was 2.5 tiles further up the screen for the purposes of layering. Default 0.
AllowsFlooringUnderneath	(Optional) Whether flooring can be placed underneath, and when the building is placed, if it will leave flooring beneath it. Default true.
DrawLayers	(Optional) A list of textures to draw over or behind the building, with support for conditions and animations. This consists of a list of models with these fields: field effect Id The unique string ID for this entry within the current list. SourceRect The pixel area within the texture to draw, formatted like "<x> <y> <width> <height>". If the overlay is animated via FrameCount, this is the area of the first frame. DrawPosition The position at which to draw the top-left corner of the texture, relative to the building's top-left corner. Measured in pixels. Texture (Optional) The asset name of the texture to draw. Defaults to the building's default Texture field. DrawInBackground (Optional) Whether to draw the texture behind the building sprite (i.e. underlay) instead of over it. SortTileOffset (Optional) A Y tile offset applied when figuring out render layering. For example, a value of 2.5 will treat the texture as if it was 2.5 tiles further up the screen for the purposes of layering. Default 0. OnlyDrawIfChestHasContents (Optional) The ID of a chest defined in the Chests field which must contain items. If it's empty, this overlay won't be rendered. Default none. FrameCount FramesPerRow FrameDuration (Optional) If FrameCount is more than one, the building overlay will be animated automatically. For each frame, the SourceRect will be offset by its Width to the right up to FramesPerRow - 1 times, and then down by its Height. Each frame will be rendered on-screen for FrameDuration milliseconds before switching to the next frame. For example, if you set FrameCount to 6 and FramesPerRow to 3, the building will expect the frames to be laid out like this in the spritesheet (where frame 1 matches SourceRect): ┌───┬───┬───┐ │ 1 │ 2 │ 3 │ ├───┼───┼───┤ │ 4 │ 5 │ 6 │ └───┴───┴───┘ AnimalDoorOffset (Optional) A pixel offset applied to the draw layer when the animal door is open. While the door is opening, the percentage open is applied to the offset (e.g. 50% open = 50% offset).
DrawShadow	(Optional) Whether to draw an automatic shadow along the bottom edge of the building's sprite. Default true.

Interior

field	effect
IndoorMap	(Optional) The name of the map asset under Maps to load for the building interior. For example, "Shed" will load the shed's Maps/Shed map.
IndoorMapType	(Optional) The full name of the C# location class which will manage the building's interior location. This must be one of the vanilla types to avoid a crash when saving. There are too many to list here, but the most useful types are likely... StardewValley.AnimalHouse; StardewValley.Locations.Cabin; StardewValley.Locations.Cellar; StardewValley.Locations.DecoratableLocation; StardewValley.Locations.FarmCave; StardewValley.Locations.FarmHouse; StardewValley.Shed; and StardewValley.SlimeHutch. Defaults to the generic StardewValley.GameLocation class.
NonInstancedIndoorLocation	(Optional) The name of the existing global location to treat as the building's interior, like FarmHouse and Greenhouse for their buildings. Each location can only be used by one building. If the location is already in use (e.g. because the player has two of this building), each subsequent building will use the IndoorMap and IndoorMapType instead. For example, the first greenhouse will use the global Greenhouse location, and any subsequent greenhouse will use a separate instanced location.
MaxOccupants	(Optional) The maximum number of animals who can live in this building.
AllowAnimalPregnancy	(Optional) Whether animals can get pregnant and produce offspring in this building. Default false.
ValidOccupantTypes	(Optional) A list of building IDs whose animals to allow in this building too. For example, [ "Barn", "Coop" ] will allow barn and coop animals in this building. Default none.

Note: the player's entry position after entering the building will be 1 tile North of the first warp in the location's warp list.

Item processing

field	effect
HayCapacity	(Optional) The amount of hay that can be stored in this building. If built on the farm, this works just like silos and contributes to the farm's available hay.
ItemConversions	(Optional) The item processing rules which take input items and convert them into output items using the inventories defined by Chests. This consists of a list of models with these fields: field effect Id The unique string ID for this rule within the current list. RequiredTags A list of context tags to match against an input item. An item must have all of these tags to be accepted. SourceChest The ID of the inventory defined in Chests from which to take input items. DestinationChest The ID of the inventory defined in Chests in which to store output items. ProducedItems The output items produced when an input item is converted. This consists of a list of models with these fields: field effect common fields See item spawn fields for the generic item fields supported by machine output. If set to an item query which returns multiple items, one of them will be selected at random. Chance (Optional) The probability that the item will be produced, as a value between 0 (never drops) and 1 (always drops). Default 1 (100% chance). RequiredCount (Optional) The number of the input item to consume. Default 1. MaxDailyConversions (Optional) The maximum number of the input item which can be processed each day. Each conversion rule has its own separate maximum (e.g. if you have two rules each with a max of 1, then you can convert one of each daily). Set to -1 to allow unlimited conversions. Default 1.
Chests	(Optional) The input/output inventories that can be accessed from a tile on the building exterior. The allowed items are defined by the separate ItemConversions field. This is a list of models with these fields: field effect Id The unique string ID for this chest within the current list. This is referenced from the ItemConversions field. Type The inventory type. This must be one of: Chest: show a normal chest UI on click. Collect: provides items for the player to collect. Clicking the tile will do nothing (if empty), grab the item directly (if it only contains one item), else show a grab-only inventory UI. Load: lets the player add items for the building to process. Sound (Optional) The sound to play once when the player clicks the chest. InvalidItemMessage InvalidCountMessage ChestFullMessage (Optional) A tokenizable string to show when the player tries to add an item to the chest when... it isn't a supported item; it's supported but they don't have enough in their inventory; the chest has no more room to accept it. If omitted, the player interaction is ignored with no message shown. InvalidItemMessageCondition (Optional) A game state query which indicates whether InvalidItemMessage should be shown. This can use item-related queries like ITEM_TYPE. Defaults to always true. DisplayTile (Optional) The chest's position on the building exterior, measured in tiles from the top-left corner of the building, specified in the form "<x>, <y>". This affects the position of the 'item ready to collect' bubble. If omitted, the bubble is disabled. DisplayHeight (Optional) If DisplayTile is set, the chest's tile height like 1.5.

Tile interactions

field	effect
ActionTiles	(Optional) A list of tiles which the player can click to trigger an Action map tile property. This consists of a list of models with these fields: field effect Id The unique string ID for this entry within the current list. Tile The tile position, relative to the building's top-left corner tile. Action The tokenizable string for the action to perform, excluding the Action prefix. For example, "Dialogue Hi there @!" to show a messagebox like "Hi there <player name>!". The tokenizable string is expected before the action is raised. See the list of tile properties for useful Action values.
DefaultAction	(Optional) The default tile action if the clicked tile isn't in ActionTiles. Default none.
TileProperties	(Optional) The map tile properties to set. This consists of a list of models with these fields: field effect Id The unique string ID for this entry within the current list. Name The tile property name to set. Value (Optional) The tile property value to set, or omit to set a null value. Layer The name of the map layer whose tiles to change. TileArea The tiles to which to add the property, relative to the top-left corner of the building's collision box. This is specified as an object with X, Y, Width, and Height fields.
AdditionalTilePropertyRadius	(Optional) When checking whether the player clicked on a TileProperties tile, an added distance around the building at which tile locations may be placed. Default 0, so only tile properties within the normal building bounds will work.

Advanced

field	effect
Metadata	(Optional) A list of custom properties applied to the building, which can optionally be overridden per-skin in the Skins field. Default none. The base game recognizes these properties: property description ChimneyPosition: <x> <y> (Optional) The pixel position at which to place a chimney on the building exterior, relative to the top-left corner of the sprite. This will apply the same logic as the farmhouse chimney (e.g. producing smoke if there's a lit fireplace inside the building). ChimneyPosition[upgrade level]: <x> <y> (Optional, for farmhouses/cabins only) Override ChimneyPosition for the given upgrade level, starting from 0 for the initial farmhouse/cabin. If there's no override for the current upgrade level, the highest override for a lower upgrade level is used (if any). For example, ChimneyPosition3 would be used for the third house upgrade (and the fourth if there's no ChimneyPosition4). This can also contain arbitrary custom properties, which C# mods can read using building.GetMetadata(key).
NameForGeneralType	(Optional) A tokenizable string for the display name which represents the general building type, like 'Coop' for a Deluxe Coop. For example, this can be shown in Robin's started-construction dialogue. If omitted, it defaults to the Name field.
BuildingType	(Optional) The full name of the C# type to instantiate for the building instance. Defaults to a generic Building instance. ⚠ Caution: this is meant to support vanilla building types like StardewValley.Shed. Setting this to a non-vanilla type will cause a crash when it's written to the save file, and may cause crashes in multiplayer. If you need custom behavior, consider handling it in C# based on the building type instead of creating a custom subclass; otherwise you'll need a framework mod like SpaceCore to handle serialization and multiplayer sync.
ModData	(Optional) A string → string lookup of arbitrary modData values to attach to the building when it's constructed.
CustomFields	The custom fields for this entry.

For C# mods

The following methods are available to simplify common operations on buildings:

type	method	effect
Building	CreateInstanceFromId	Create a building instance from its type ID in Data/Buildings. For example: Building shippingBin = Building.CreateInstanceFromId("Shipping Bin", Vector2.Zero); // creates an instance of StardewValley.Buildings.ShippingBin
	FinishConstruction	If the building is being constructed or upgrade, instantly finish doing so.
	GetData TryGetData	Get the data for the building's type from Data/Building.
	GetIndoors	Get the location within this building, if applicable.
	GetIndoorsName	Get the unique name of the location within this building, if applicable.
	GetMetadata	Get a value from the Metadata field in Data/Buildings for this building.
	GetPaintDataKey	Get the key in Data/PaintData for this building, if it has any.
	GetParentLocation	Get the location which contains this building.
	HasIndoors	Get whether the building has an interior location.
	HasIndoorsName	Get whether the building has an interior location and its unique name matches the given value (like building.HasIndoorsName("FarmHouse")).
	IsInCurrentLocation	Get whether the building is in the same location as the current player.
	ReloadBuildingData	Apply the latest data in Data/Buildings to this building.
	UpdateTransparency	Update the building transparency on tick for the local player's position. This method mainly exists to let mods override/patch the transparency logic.
Cabin FarmHouse	GetCellar	Get the cellar location linked to this cabin, if any.
	CanAssignFarmhand AssignFarmhand	(Cabin only) Check whether the cabin is available to assign to a farmhand, or perform the assignment.
	HasOwner	Get whether the home has an assigned player, regardless of whether they've finished creating their character.
	OwnerId	Get the unique ID of the player who owns this home, if any.
	IsOwnedByCurrentPlayer	Get whether the cabin belongs to the current player.
	IsOwnerActivated	Get whether the home has an assigned player and they've finished creating their character.
	HasNpcSpouse	Get whether the player who owns this home is married to any NPC (when used like HasNpcSpouse()) or a specific NPC (like HasNpcSpouse(name)). This also replaces shouldShowSpouseRoom().
Farm	GetMainFarmHouse	Get the main farmhouse building.
GameLocation	AddDefaultBuildings	Can be overridden to add custom buildings when the location is created and/or loaded. These can either be re-added whenever they're missing (like the vanilla farmhouse), or only built once on save creation (like the vanilla pre-built cabins).
	GetContainingBuilding	Get the building instance which contains this location (like the cabin for a cabin interior), if applicable.
	GetInstancedBuildingInteriors	Get all building interiors within this location which are instanced to the building (i.e. not in Game1.locations separately).
	OnBuildingConstructed OnBuildingMoved OnBuildingDemolished	These methods are called for all players when any player constructs, moves, or demolishes a building.
	OnParentBuildingUpgraded	Called when the building containing this location is upgraded, if applicable.

• All buildings have an id field, which uniquely identifies each building in the world.