Modding:Trigger actions

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

This page documents trigger actions, which let content packs perform an action when something happens. (C# mods should usually use SMAPI events instead.)

Overview

Introduction

Each trigger action is comprised of three main parts:

The trigger is when to apply the trigger action, either defined by the base game (like LocationChanged) or added by C# mods.
Actions are what to do (like send mail or start a quest).
Conditions are optional game state queries to decide whether the trigger action should be applied.

For example, consider this Content Patcher patch:

{
    "Format": "2.0.0",
    "Changes": [
        {
            "Action": "EditData",
            "Target": "Data/Triggers",
            "Entries": {
                "SomeMod.Id_OnLeoMoved": {
                    "Trigger": "LocationChanged",
                    "Location": "Farm",
                    "Condition": "PLAYER_HAS_FLAG Host leoMoved",
                    "Actions": [
                        "AddMail Current Abigail_LeoMoved Today",
                        "AddConversationTopic LeoMoved 5"
                    ]
                }
            }
        }
    ]
}

You can read that like: "When the player arrives in the Farm location, if Leo has moved to the valley, then send a letter and start a conversation topic".

Actions only run once by default, though you can use the MarkActionApplied command to re-enable one.

Action format

An action consists of an action name with space-delimited arguments. For example, AddMail Current Abigail_LeoMoved Today has action name AddMail with three arguments (Current, Abigail_LeoMoved, and Today).

If you have spaces within an argument, you can surround it with quotes to keep it together. For example, AddFriendshipPoints "Mister Qi" 10 has two arguments (Mister Qi and 10). You can escape inner quotes with backslashes, like AddFriendshipPoints "Mister \"Qi\"" 10.

Remember that quotes and backslashes inside JSON strings need to be escaped too. For example, "AddFriendshipPoints \"Mister Qi\" 10" will send AddFriendshipPoints "Mister Qi" 10 to the game code. Alternatively, you can use single-quotes for the JSON string instead, like 'AddFriendshipPoints "Mister Qi" 10'.

Triggers

The game has one built-in trigger which can be used in the Trigger field. (Other custom triggers may be added by C# mods.)

trigger	effect
`LocationChanged`	Raised when the player arrives in a location (including 'arriving' in the farmhouse when the day starts).

Actions

These are the built-in actions which can be used in the Actions field. (Other custom actions may be added by C# mods.)

	Article Stub This article is a stub and is missing information. You can help Stardew Valley Wiki by expanding it!

For C# mod authors

Using trigger actions in C# data

Trigger actions are mainly meant for Content Patcher packs. C# mod can use SMAPI's events instead, which are much more flexible and efficient (unless you want to let content packs edit your trigger actions).

Extensibility

C# mods can use the StardewValley.Triggers.DataTriggers class to interact with data triggers.

For example, you can add a new trigger type:

// register custom hook type
DataTriggers.RegisterTrigger("Some.ModId_OnItemReceived");

// raise trigger as needed
DataTriggers.Raise("Some.ModId_OnItemReceived");

Or you can add a new action handler:

DataTriggers.RegisterAction("Some.ModId_PlaySound", this.PlaySound);

...

/// <inheritdoc cref="DataTriggerActionDelegate" />
public static bool PlaySound(string[] args, string trigger, TriggerActionData data)
{
    // get args
    if (!ArgUtility.TryGet(args, 1, out string soundId, out string error, allowBlank: false))
        return DataTriggers.Helpers.LogActionError(args, trigger, data, error);

    // apply
    Game1.playSound(soundId);
    return true;
}

To avoid conflicts, custom trigger names should be unique string IDs.