Changes

Jump to navigation Jump to search

Modding:Common data field types (view source)

Revision as of 17:15, 31 May 2024

5,565 bytes added ,  31 May
m
→‎Quantity modifiers: Fix broken links
Line 1: Line 1:  
← [[Modding:Index|Index]]
 
← [[Modding:Index|Index]]
−
  −
{{upcoming|1.6}}
      
This page documents common field types which appear in [[Modding:Editing XNB files|the game's data files]].
 
This page documents common field types which appear in [[Modding:Editing XNB files|the game's data files]].
Line 14: Line 12:     
Best practices for mods:
 
Best practices for mods:
−
* Use namespaced IDs prefixed with your [[Modding:Modder Guide/APIs/Manifest#Basic fields|mod's unique ID]]. For example, if your mod ID is <code>Example.PufferchickMod</code> and you're adding a pufferchick plushy, your item ID would look like <code>Example.PufferchickMod_PufferchickPlushy</code> (or optionally <code><nowiki>{{ModId}}_PufferchickPlushy</nowiki></code> in a [[Modding:Content Patcher|Content Patcher pack]]). Although the game doesn't validate the ID format, you're '''strongly encouraged''' to use this exact format to maintain good mod compatibility, avoid ID conflicts, and allow automatically determining which mod added custom content.  
+
* Use namespaced IDs prefixed with your [[Modding:Modder Guide/APIs/Manifest#Basic fields|mod's unique ID]]. For example, if your mod ID is <code>Example.PufferchickMod</code> and you're adding a pufferchick plushy, your item ID would look like <code>Example.PufferchickMod_PufferchickPlushy</code>. In a [[Modding:Content Patcher|Content Patcher pack]], you can use <code><nowiki>{{ModId}}_PufferchickPlushy</nowiki></code> to insert your mod ID automatically.
 
* Only use alphanumeric (a–z, A–Z, 0–9), underscore (<code>_</code>), and dot (<code>.</code>) characters in string IDs. This is important because they're often used in places where some characters have special meaning (like file names or [[#Game state query|game state queries]]).
 
* Only use alphanumeric (a–z, A–Z, 0–9), underscore (<code>_</code>), and dot (<code>.</code>) characters in string IDs. This is important because they're often used in places where some characters have special meaning (like file names or [[#Game state query|game state queries]]).
 +
 +
Although the game generally doesn't validate the ID format, you're '''strongly encouraged''' to use this exact format to maintain good mod compatibility, eliminate ID conflicts, and make it easy (for both troubleshooters and mod code) to identify which mod added custom content.
 +
 +
===Asset name===
 +
An ''asset name'' uniquely identifies a [[Modding:Editing XNB files|game asset]]. These usually match files in the game's <samp>Content</samp> folder, but mods can add custom assets using [[Modding:Content Patcher|Content Patcher]] or the [[Modding:Modder Guide/APIs/Content|C# content API]].
 +
 +
For example, <samp>Portraits/Abigail</samp> contains [[Abigail]]'s portraits.
 +
 +
Asset names '''do not''' include the <code>Content/</code> prefix, file extension, or locale code. For example, the <samp>Content/Data/Achievements.de-DE.xnb</samp> file has asset name <samp>Data/Achievements</samp>.
    
===Color===
 
===Color===
Line 192: Line 199:     
See [[Modding:Items#Context tags]] for more info.
 
See [[Modding:Items#Context tags]] for more info.
 +
 +
===Custom fields===
 +
Many data assets have a <samp>CustomFields</samp> field. This is ignored by the game, but can be read by mod frameworks to enable custom features.
 +
 +
For example, a content pack can [[Modding:Crop data|add a crop]] with custom fields:
 +
<syntaxhighlight lang="js">
 +
"CustomFields": {
 +
    "Example.FrameworkMod/WetTexture": "{{InternalAssetKey: assets/crops-wet.png}}"
 +
}
 +
</syntaxhighlight>
 +
 +
And then a C# mod could handle the custom field if it's set:
 +
<syntaxhighlight lang="c#">
 +
CropData data = crop.GetData();
 +
if (data != null && data.CustomFields.TryGetValue("Example.FrameworkMod/WetTexture", out string textureName))
 +
{
 +
    // do magic
 +
}
 +
</syntaxhighlight>
    
===Game state query===
 
===Game state query===
Line 208: Line 234:  
For example, [[pufferfish]] has two item IDs: <code>128</code> (unqualified) and <code>(O)128</code> (qualified).
 
For example, [[pufferfish]] has two item IDs: <code>128</code> (unqualified) and <code>(O)128</code> (qualified).
   −
See [[Modding:Migrate to Stardew Valley 1.6#Custom items]] for more info.
+
See [[Modding:Items]] for more info.
    
===Item query===
 
===Item query===
Line 225: Line 251:     
See [[Modding:Tokenizable strings]] for more info.
 
See [[Modding:Tokenizable strings]] for more info.
 +
 +
===Translation key===
 +
A ''translation key'' uniquely identifies where to find translatable text, in the form <samp>{{t|asset name}}:{{t|key}}</samp>. For example, <code>Strings\\StringsFromCSFiles:spring</code> will look for a <samp>spring</samp> key in the <samp>Strings\StringsFromCSFiles</samp> asset file in the content folder.
 +
 +
This is often used in game code (''e.g.'' via <code>Game1.content.LoadString</code>) and in data assets (''e.g.'' via the <samp>LocalizedText</samp> [[#Tokenizable string|tokenizable string]] token).
    
===Trigger action===
 
===Trigger action===
Line 258: Line 289:  
<syntaxhighlight lang="C#">
 
<syntaxhighlight lang="C#">
 
item.modData[$"{this.ModManifest.UniqueID}/item-age"] = "30";
 
item.modData[$"{this.ModManifest.UniqueID}/item-age"] = "30";
 +
</syntaxhighlight>
 +
 +
===Point===
 +
A point represents an integer coordinate or size, usually measured in pixels or tiles. This is formatted as an object with an X/Y position. For example:
 +
<syntaxhighlight lang="js">
 +
"Position": {
 +
    "X": 0,
 +
    "Y": 0
 +
}
 +
</syntaxhighlight>
 +
 +
===Quantity modifiers===
 +
 +
''Quantity modifiers'' apply dynamic changes to a numeric field in a data asset like [[Modding:Shops|<samp>Data/Shops</samp>]] or [[Modding:Machines|<samp>Data/Machines</samp>]]. For example, you can multiply a shop item's price or increase a machine output's quality. You can specify any number of modifiers for the same field.
 +
 +
====Modifier format====
 +
These consist of a list of models with these fields:
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| <samp>Id</samp>
 +
| The [[Modding:Common data field types#Unique string ID|unique string ID]] for this modifier within the current list.
 +
|-
 +
| <samp>Modification</samp>
 +
| The type of change to apply. The possible values are <samp>Add</samp>, <samp>Subtract</samp>, <samp>Multiply</samp>, <samp>Divide</samp>, and <samp>Set</samp>.
 +
|-
 +
| <samp>Amount</samp>
 +
| ''(Optional if <samp>RandomAmount</samp> specified)'' The operand applied to the target value (e.g. the multiplier if used with <samp>Multiply</samp>).
 +
|-
 +
| <samp>RandomAmount</samp>
 +
| ''(Optional)'' A list of possible amounts to randomly choose from. If set, <samp>Amount</samp> is optional and ignored. Each entry in the list has an equal probability of being chosen, and the choice is persisted for the current day. For example:
 +
<syntaxhighlight lang="js">
 +
"RandomAmount": [ 1, 2, 3.5, 4 ]
 +
</syntaxhighlight>
 +
|-
 +
| <samp>Condition</samp>
 +
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which indicates whether this change should be applied. Defaults to always true.
 +
|}
 +
 +
====Modifier mode====
 +
Quality modifier fields are often accompanied by a ''mode'' field (like <samp>PriceModifiers</samp> and <samp>PriceModifierMode</samp>), which indicate what to do when multiple modifiers apply to the same value. Available modes:
 +
 +
{| class="wikitable"
 +
|-
 +
! value
 +
! effect
 +
|-
 +
| <samp>Stack</samp>
 +
| Apply each modifier to the result of the previous one. For example, two modifiers which double a value will quadruple it.
 +
|-
 +
| <samp>Minimum</samp>
 +
| Apply the modifier which results in the lowest value.
 +
|-
 +
| <samp>Maximum</samp>
 +
| Apply the modifier which results in the highest value.
 +
|}
 +
 +
====Examples====
 +
For example, this will double the price of a shop item in <samp>Data/Shops</samp>:
 +
<syntaxhighlight lang="js">
 +
"PriceModifiers": [
 +
    {
 +
        "Modification": "Multiply",
 +
        "Amount": 2.0
 +
    }
 +
]
 +
</syntaxhighlight>
 +
 +
This will set the price to a random value between 100–1000, ''or'' 3–5 times the item's normal sell price, whichever is higher (like the [[Traveling Cart]]):
 +
<syntaxhighlight lang="js">
 +
"PriceModifierMode": "Maximum",
 +
"PriceModifiers": [
 +
    {
 +
        "Modification": "Set",
 +
        "RandomAmount": [ 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000 ]
 +
    },
 +
    {
 +
        "Modification": "Multiply",
 +
        "RandomAmount": [ 3, 4, 5 ]
 +
    }
 +
]
 +
</syntaxhighlight>
 +
 +
===Rectangle===
 +
A rectangle represents a square area, usually measured in pixels or tiles. This is formatted as an object with an X/Y position (for the top-left corner) and width/height size, where all values are integers. For example:
 +
<syntaxhighlight lang="js">
 +
"Rectangle": {
 +
    "X": 0,
 +
    "Y": 0,
 +
    "Width": 16,
 +
    "Height": 32
 +
}
 +
</syntaxhighlight>
 +
 +
===Vector2===
 +
A Vector2 represents a non-integer coordinate or size, usually measured in pixels or tiles. This is formatted as an object with an X/Y position. For example:
 +
<syntaxhighlight lang="js">
 +
"Position": {
 +
    "X": 10.5,
 +
    "Y": 12.0
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
    
[[Category:Modding]]
 
[[Category:Modding]]
BarleyZP
138

edits

Retrieved from "https://stardewvalleywiki.com/Special:MobileDiff/153572...171954"

Navigation menu