Modding:Common data field types

← Index

The following describes the upcoming Stardew Valley 1.6, and may change before release.

This page documents common field types which appear in the game's data files.

You normally don't need to read through this page directly; specific sections are linked from field docs on other pages.

String formats

These formats can only be used in fields that specifically support them. The field docs will link to this page if applicable.

Unique string ID

The game identifies data using unique string IDs. For example, Town is the unique ID for the Pelican Town location; no other location can use that ID. The IDs are used for a wide range of purposes, from internal game logic to content pack edits.

Best practices for mods:

• Use namespaced IDs prefixed with your mod's unique ID. For example, if your mod ID is Example.PufferchickMod and you're adding a pufferchick plushy, your item ID would look like Example.PufferchickMod_PufferchickPlushy (or optionally {{ModId}}_PufferchickPlushy in a 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.
• Only use alphanumeric (a–z, A–Z, 0–9), underscore (_), and dot (.) 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 queries).

Context tag

A context tag is an arbitrary data label attached to items. The game auto-generates some context tags, while others can be added through the item data.

These can produce various effects in-game, be queried in various asset fields or using the ITEM_CONTEXT_TAG game state query, or may be informational only.

See Modding:Items#Context tags for more info.

Game state query

A game state query defines a condition using a special command syntax. For example, this checks if today is spring or summer:

"Condition": "SEASON Spring Summer"

See Modding:Game state queries for more info.

Item ID

Every item is identified by two strings:

• An unqualified item ID (item.ItemId) is a unique string ID for the item. This should generally be unique, but older vanilla items have non-unique numeric IDs for legacy reasons.
• A qualified item ID (item.QualifiedItemId) prefixes the unqualified ID with the type identifier to guarantee uniqueness.

For example, pufferfish has two item IDs: 128 (unqualified) and (O)128 (qualified).

See Modding:Migrate to Stardew Valley 1.6#Custom items for more info.

Item query

An item query creates any number of items dynamically using either an item ID or a special command syntax. For example, you can select random house plants:

"ItemId": "RANDOM_ITEMS (F) 1376 1390"

See Modding:Item queries for more info.

Tokenizable string

A tokenizable string is text which can contain special tokens. For example, this shows a message like "It's a beautiful spring day":

"Message": "It's a beautiful [Season] day"

See Modding:Tokenizable strings for more info.

Trigger action

A trigger action performs an action when something happens, with support for a wide range of actions (like sending mail, changing friendship, starting a quest, etc).

For example, you can give the player an item from dialogue:

"Message": "Hi there! Here's a pufferfish.#%action AddItem (O)128"

See Modding:Trigger actions for more info.

Data structures

Item spawn fields

Item spawn fields are a common set of fields used to create items using item queries in many data assets.

For example, you can create an iridium-quality strawberry juice:

"ItemId": "FLAVORED_ITEM Juice (O)400",
"Quality": 4

See Modding:Item queries#Item spawn fields for more info.

Mod data

modData dictionary fields store custom data about instances. These are synchronized in multiplayer, persisted in the save file, and accessible from both C# and game state queries like PLAYER_MOD_DATA.

When you split an item stack, the new stack copies the previous one's mod data; when merged into another stack, the merged items adopt the target stack's mod data. Otherwise mod data has no effect on item split/merge logic (e.g. you can still merge items with different mod data).

In C#, these are available on these types: Character (including monsters, NPCs, and players), GameLocation, Item, Projectile, Quest, and TerrainFeature.

To avoid mod conflicts, mod data keys should be unique string IDs:

item.modData[$"{this.ModManifest.UniqueID}/item-age"] = "30";