Difference between revisions of "Modding:Machines"
Pathoschild (talk | contribs) (create with content copied from Modding:Migrate to Stardew Valley 1.6 (I'm the only contributor for the copied content)) |
Pathoschild (talk | contribs) (integrate copied text into page, add definitions section) |
||
Line 3: | Line 3: | ||
This page explains how add/edit machines in the game data. This is an advanced guide for modders. | This page explains how add/edit machines in the game data. This is an advanced guide for modders. | ||
− | == | + | ==Definitions== |
− | == | + | A "machine" is a placeable object which takes input and/or produces output based on the rules in <samp>Data/Machines</samp>. A machine doesn't need to do both (e.g. [[Solar Panel|solar panels]] produce output without accepting input), and it's not necessarily something players would intuitively consider a machine (e.g. [[incubator]]s and [[Mushroom Log|mushroom logs]] are machines). |
− | You can | + | |
+ | ==Data format== | ||
+ | You can add/edit machine logic by editing the <samp>Data/Machines</samp> [[Modding:Editing XNB files|asset]]. | ||
This consists of a string → model lookup, where... | This consists of a string → model lookup, where... | ||
− | * The key is the [[# | + | * The key is the [[Modding:Common data field types#Item ID|'''qualified''' item ID]] for the item which acts as a machine (like <samp>(BC)127</samp> for [[The Cave|mushroom boxes]]). |
* The value is a model with the fields listed below. | * The value is a model with the fields listed below. | ||
− | + | ===Item processing rules=== | |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
Line 110: | Line 112: | ||
|- | |- | ||
| <samp>PriceModifiers</samp><br /><samp>PriceModifiers</samp> | | <samp>PriceModifiers</samp><br /><samp>PriceModifiers</samp> | ||
− | | ''(Optional)'' [[#Quantity modifiers|Quantity modifiers]] applied to the output item's price. Default none. | + | | ''(Optional)'' [[Modding:Migrate to Stardew Valley 1.6#Quantity modifiers|Quantity modifiers]] applied to the output item's price. Default none. |
|- | |- | ||
| <samp>IncrementMachineParentSheetIndex</samp> | | <samp>IncrementMachineParentSheetIndex</samp> | ||
Line 169: | Line 171: | ||
|- | |- | ||
| <samp>ItemId</samp> | | <samp>ItemId</samp> | ||
− | | The [[# | + | | The [[Modding:Common data field types#Item ID|qualified or unqualified item ID]] for the required item. |
|- | |- | ||
| <samp>RequiredCount</samp> | | <samp>RequiredCount</samp> | ||
Line 182: | Line 184: | ||
|- | |- | ||
| <samp>ReadyTimeModifiers</samp> | | <samp>ReadyTimeModifiers</samp> | ||
− | | ''(Optional)'' [[#Quantity modifiers|Quantity modifiers]] applied to the produced item's processing time. The modifier conditions can use item-only tokens, which will check the ''input'' (not output) item. | + | | ''(Optional)'' [[Modding:Migrate to Stardew Valley 1.6#Quantity modifiers|Quantity modifiers]] applied to the produced item's processing time. The modifier conditions can use item-only tokens, which will check the ''input'' (not output) item. |
|- | |- | ||
| <samp>ReadyTimeModifierMode</samp> | | <samp>ReadyTimeModifierMode</samp> | ||
− | | ''(Optional)'' A [[#Quantity modifiers|quantity modifier mode]] which indicates what to do if multiple modifiers apply at the same time. Default <samp>Stack</samp>. | + | | ''(Optional)'' A [[Modding:Migrate to Stardew Valley 1.6#Quantity modifiers|quantity modifier mode]] which indicates what to do if multiple modifiers apply at the same time. Default <samp>Stack</samp>. |
|} | |} | ||
− | + | ===Behavior tweaks=== | |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
Line 222: | Line 224: | ||
|} | |} | ||
− | + | ===Audio & visuals=== | |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
Line 246: | Line 248: | ||
|- | |- | ||
| <samp>Id</samp> | | <samp>Id</samp> | ||
− | | The [[ | + | | The [[Modding:Audio|audio cue ID]] to play. |
|- | |- | ||
| <samp>Delay</samp> | | <samp>Delay</samp> | ||
Line 286: | Line 288: | ||
|- | |- | ||
| <samp>Color</samp> | | <samp>Color</samp> | ||
− | | ''(Optional)'' A tint color to apply to the sprite. See [[#Color | + | | ''(Optional)'' A tint color to apply to the sprite. See [[Modding:Common data field types#Color|color format]]. Default <samp>White</samp> (no tint). |
|- | |- | ||
| <samp>AlphaFade</samp><br /><samp>Loops</samp><br /><samp>Rotation</samp><br /><samp>RotationChange</samp><br /><samp>ScaleChange</samp><br /><samp>SortOffset</samp> | | <samp>AlphaFade</samp><br /><samp>Loops</samp><br /><samp>Rotation</samp><br /><samp>RotationChange</samp><br /><samp>ScaleChange</samp><br /><samp>SortOffset</samp> | ||
− | | ''(Optional)'' See equivalent fields in the [[ | + | | ''(Optional)'' See equivalent fields in the [[Modding:Event data|<samp>temporaryAnimatedSprite</samp> event command]]. Default 0. |
|- | |- | ||
| <samp>Frames</samp><br /><samp>Scale</samp> | | <samp>Frames</samp><br /><samp>Scale</samp> | ||
− | | ''(Optional)'' See equivalent fields in the [[ | + | | ''(Optional)'' See equivalent fields in the [[Modding:Event data|<samp>temporaryAnimatedSprite</samp> event command]]. Default 1. |
|- | |- | ||
| <samp>Interval</samp> | | <samp>Interval</samp> | ||
− | | ''(Optional)'' See equivalent fields in the [[ | + | | ''(Optional)'' See equivalent fields in the [[Modding:Event data|<samp>temporaryAnimatedSprite</samp> event command]]. Default 100. |
|- | |- | ||
| <samp>Flicker</samp><br /><samp>Flip</samp> | | <samp>Flicker</samp><br /><samp>Flip</samp> | ||
− | | ''(Optional)'' See equivalent fields in the [[ | + | | ''(Optional)'' See equivalent fields in the [[Modding:Event data|<samp>temporaryAnimatedSprite</samp> event command]]. Default false. |
|} | |} | ||
|} | |} | ||
Line 318: | Line 320: | ||
|- | |- | ||
| <samp>Color</samp> | | <samp>Color</samp> | ||
− | | ''(Optional)'' A tint color to apply to the light. See [[#Color | + | | ''(Optional)'' A tint color to apply to the light. See [[Modding:Common data field types#Color|color format]]. Default <samp>White</samp> (no tint). |
|} | |} | ||
|- | |- | ||
Line 328: | Line 330: | ||
|} | |} | ||
− | + | ===Player interaction messages=== | |
These only apply when the player interacts with a chest directly, instead of using a [[hopper]] or mod like {{nexus mod|1063|Automate}}. | These only apply when the player interacts with a chest directly, instead of using a [[hopper]] or mod like {{nexus mod|1063|Automate}}. | ||
Line 349: | Line 351: | ||
|} | |} | ||
− | + | ===Advanced logic=== | |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
Line 369: | Line 371: | ||
|- | |- | ||
| <samp>HasInput</samp><br /><samp>HasOutput</samp> | | <samp>HasInput</samp><br /><samp>HasOutput</samp> | ||
− | | ''(Optional)'' Whether to force adding the <samp>machine_input</samp> or <samp>machine_output</samp> [[# | + | | ''(Optional)'' Whether to force adding the <samp>machine_input</samp> or <samp>machine_output</samp> [[Modding:Items#Context tags|context tags]] respectively. This isn't needed for most machines, since they'll be set based on the <samp>OutputRules</samp> field. Default false. |
|- | |- | ||
| <samp>IsIncubator</samp> | | <samp>IsIncubator</samp> | ||
Line 396: | Line 398: | ||
|- | |- | ||
| <samp>CustomFields</samp> | | <samp>CustomFields</samp> | ||
− | | The [[#Custom | + | | The [[Modding:Common data field types#Custom fields|custom fields]] for this entry. |
|} | |} | ||
− | ====Interacting with machines | + | ==For C# mods== |
+ | ===Interacting with machines=== | ||
Stardew Valley 1.6 adds two <samp>Object</samp> fields for reference: | Stardew Valley 1.6 adds two <samp>Object</samp> fields for reference: | ||
{| class="wikitable" | {| class="wikitable" |
Revision as of 01:00, 6 April 2024
← Index
This page explains how add/edit machines in the game data. This is an advanced guide for modders.
Definitions
A "machine" is a placeable object which takes input and/or produces output based on the rules in Data/Machines. A machine doesn't need to do both (e.g. solar panels produce output without accepting input), and it's not necessarily something players would intuitively consider a machine (e.g. incubators and mushroom logs are machines).
Data format
You can add/edit machine logic by editing the Data/Machines asset.
This consists of a string → model lookup, where...
- The key is the qualified item ID for the item which acts as a machine (like (BC)127 for mushroom boxes).
- The value is a model with the fields listed below.
Item processing rules
field | effect | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
OutputRules | The output produced by this machine. If multiple output rules can be produced, the first available one is selected. This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AdditionalConsumedItems | (Optional) A list of extra items required before OutputRules will be checked. If specified, every listed item must be present in the player, hopper, or chest inventory (depending how the machine is being loaded).
This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AllowFairyDust | (Optional) Whether the player can add fairy dust to speed up the machine. Default true. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ReadyTimeModifiers | (Optional) Quantity modifiers applied to the produced item's processing time. The modifier conditions can use item-only tokens, which will check the input (not output) item. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ReadyTimeModifierMode | (Optional) A quantity modifier mode which indicates what to do if multiple modifiers apply at the same time. Default Stack. |
Behavior tweaks
field | effect | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
PreventTimePass | (Optional) A list of cases when the machine should be paused, so the timer on any item being produced doesn't decrement. Possible values:
| ||||||||||
AllowLoadWhenFull | (Optional) Whether the player can drop a new item into the machine before it's done processing the last one (like the crystalarium). The previous item will be lost. Default false. | ||||||||||
ClearContentsOvernightCondition | (Optional) A game state query which indicates whether the machine should be emptied overnight, so any current output will be lost. Defaults to always false. |
Audio & visuals
field | effect | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
LoadEffects WorkingEffects |
(Optional) The cosmetic effects shown when an item is loaded into the machine (for LoadEffects), or while it's processing the item (for WorkingEffects, based on the WorkingEffectChance probability). Both default to none. These consist of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||
WorkingEffectChance | (Optional) The percentage chance to apply WorkingEffects each time the day starts or the in-game clock changes, as a value between 0 (never) and 1 (always). Default 0.33. | ||||||||||||||||||||||||||||||||||||||||||
LightWhileWorking | (Optional) The light emitted by the machine while it's processing an item. Default none.
This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||
WobbleWhileWorking | (Optional) Whether the machine sprite should bulge in & out while it's processing an item. Default false. | ||||||||||||||||||||||||||||||||||||||||||
ShowNextIndexWhileWorking ShowNextIndexWhenReady |
(Optional) Whether to show the next sprite in the machine's spritesheet while it's processing an item (ShowNextIndexWhileWorking) or ready (ShowNextIndexWhenReady). Default false. |
Player interaction messages
These only apply when the player interacts with a chest directly, instead of using a hopper or mod like Automate.
field | effect |
---|---|
InvalidItemMessage | (Optional) A tokenizable string for the message shown in a toaster notification if the player tries to input an item that isn't accepted by the machine. |
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. |
InvalidCountMessage | (Optional) A tokenizable string for the message shown in a toaster notification if the input inventory doesn't contain this item, unless overridden by InvalidCountMessage under OutputRules.
This can use extra custom tokens:
|
Advanced logic
field | effect | ||||||||
---|---|---|---|---|---|---|---|---|---|
InteractMethod | (Optional) A C# method invoked when the player interacts with the machine when it doesn't have output ready to harvest.
This must be specified in the form /// <summary>The method signature for a custom <see cref="MachineData.InteractMethod"/> method.</summary>
/// <param name="machine">The machine instance for which to produce output.</param>
/// <param name="location">The location containing the machine.</param>
/// <param name="player">The player using the machine.</param>
/// <returns>Returns whether the interaction was handled.</returns>
public static bool InteractWithMachine(Object machine, GameLocation location, Farmer player);
| ||||||||
HasInput HasOutput |
(Optional) Whether to force adding the machine_input or machine_output context tags respectively. This isn't needed for most machines, since they'll be set based on the OutputRules field. Default false. | ||||||||
IsIncubator | (Optional) Whether this machine acts as an incubator when placed in a building, so players can incubate eggs in it. Default false.
This is used by the incubator and ostrich incubator. The game logic assumes there's only one such machine in each building, so this generally shouldn't be used by custom machines that can be built in a vanilla barn or coop. | ||||||||
StatsToIncrementWhenLoaded StatsToIncrementWhenHarvested |
(Optional) The game stat counters to increment when an item is placed in the machine (StatsToIncrementWhenLoaded) or when the processed output is collected (StatsToIncrementWhenHarvested). Default none. This consists of a list of models with these fields:
This can be used to increment both built-in stats (like GeodesCracked for the geode crusher) and custom stats. Using a unique string ID is strongly recommended for custom stats to avoid conflicts. | ||||||||
CustomFields | The custom fields for this entry. |
For C# mods
Interacting with machines
Stardew Valley 1.6 adds two Object fields for reference:
field | effect |
---|---|
lastOutputRuleId | If this is a machine, the output rule ID for the rule being processed by the machine (if any). |
lastInputItem | If this is a machine, the item that was dropped into the machine to start the current output (if any). |
And a few methods for processing items:
field | effect |
---|---|
IsMachineWorking() | Get whether the machine is currently processing an item. |
ShouldTimePassForMachine(location) | Get whether the machine should be updated in the given location. For example, this will return false for solar panels placed indoors, or outdoors on a cloudy day. |
GetMachineData() | Get the underlying machine data from Data/Machines. |
PlaceInMachine(…) | Try to place an item in the machine using the rules from Data/Machines. This returns a boolean which indicates whether the machine was successfully started. |
OutputMachine(…) | Try to set the machine output given the input item and an optional output rule to apply. Most code should call PlaceInMachine instead. |
A lot of the generic machine logic is also handled by a new MachineDataUtility class, which lets C# mods interact with machine data more directly. For example, you can check which output a machine would produce without actually updating the machine.