Modding:Modder Guide/APIs/Utilities

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

SMAPI provides some C# objects you can use to simplify your code.

Constants

The Constants class provides metadata about SMAPI and the game.

value	meaning
Constants.ApiVersion	The version of the running SMAPI instance.
Constants.MinimumGameVersion Constants.MaximumGameVersion	The game versions supported by the running SMAPI instance.
Constants.ExecutionPath	The absolute path to the Stardew Valley folder.
Constants.DataPath	The absolute path to the game's data folder (which contains the save folder).
Constants.LogDir	The absolute path to the folder containing the game and SMAPI logs.
Constants.SavesPath	The absolute path to the save folder.
Constants.CurrentSavePath	The absolute path to the current save folder, if a save is loaded.
Constants.SaveFolderName	The name of the current save folder (like Name_012345789), if a save is loaded.

Context

The Context class provides information about the game state and player control:

value	meaning
Context.IsWorldReady	Whether the player has loaded a save and the world has finished initialising. Useful for ignoring events before the save is loaded.
Context.IsPlayerFree	Whether Context.IsWorldReady and the player is free to act on the world (no menu is displayed, no cutscene is in progress, etc).
Context.CanPlayerMove	Whether Context.IsPlayerFree and the player is free to move (e.g. not using a tool).
Context.IsMultiplayer	The following describes the upcoming SMAPI 2.6, and may change before release. Whether Context.IsWorldReady, and the player loaded the save in multiplayer mode (regardless of whether any other players are connected).
Context.IsMainPlayer	The following describes the upcoming SMAPI 2.6, and may change before release. Whether Context.IsWorldReady, and the player is the main player. This is always true in single-player, and true when hosting in multiplayer.

Dates

Use SDate for calculating in-game dates. You start by creating a date:

var date = SDate.Now(); // current date
var date = new SDate(28, "spring"); // date in the current year
var date = new SDate(28, "spring", 2); // date in the given year

Then you can calculate offsets from any date:

// add days
new SDate(28, "spring", 1).AddDays(370); // 06 fall in year 4

// subtract days
new SDate(01, "spring", 2).AddDays(-1); // 28 winter in year 1

...and compare dates:

var a = new SDate(01, "spring");
var b = new SDate(02, "spring");
if (a < b) // true
  ...

Note that SDate won't let you create invalid dates:

// ArgumentException: Invalid day '30', must be a value from 1 to 28.
new SDate(30, "spring");

// ArithmeticException: Adding -1 days to 01 spring Y1 would result in invalid date 28 winter Y0.
new SDate(01, "spring", 1).AddDays(-1);

Once created, dates have a few properties you can use:

property	meaning
Day	The day of month.
Season	The normalised season name.
Year	The year number.
DayOfWeek	The day of week (like Monday).
DaysSinceStart	The number of days since the first day, inclusively (i.e. 01 spring Y1 = 1).

Input

SMAPI's SButton constants unify the Buttons, Keys, MouseState, and InputButton constants. SMAPI events use this to let you handle controller, keyboard, and mouse input without needing separate code for each. See Modding:Key bindings for a list of values.

SMAPI provides extensions to convert any of the other constants to SButton:

SButton key = Keys.A.ToSButton(); // SButton.A
SButton button = Buttons.A.ToSButton(); // SButton.ControllerA
SButton input = new InputButton(true).ToSButton(); // SButton.MouseLeft

You can also convert SButton to the other constants. This uses a TryGet approach since SButton is a superset of the others (e.g. you can't convert SButton.ControllerA to a keyboard value):

SButton value = SButton.A;
if (value.TryGetKeyboard(out Keys key))
   ...;
if (value.TryGetController(out Buttons button))
   ...;
if (value.TryGetStardewInput(out InputButton input))
   ...;

Two last extensions let you check how the button is mapped in the game:

SButton button = SButton.MouseLeft;
if (button.IsUseToolButton())
   // use tool
else if (button.IsActionButton())
   // perform action

You can use SButton values directly in your config model, and they'll be represented by their names:

internal class ModConfig { public SButton DoThingButton { get; set; } = SButton.LeftControl; }

→

{ "DoThingButton": "LeftControl" }

Semantic versions

Use SemanticVersion to manipulate and compare versions per the Semantic Versioning 2.0 standard. Example usage:

// build version from parts
ISemanticVersion version = new SemanticVersion(5, 1, 0, "beta");

// build version from string
ISemanticVersion version = new SemanticVersion("5.1.0-beta");

// compare versions (also works with SemanticVersion instances instead of strings)
new SemanticVersion("5.2").IsOlderThan("5.10"); // true
new SemanticVersion("5.10").IsNewerThan("5.10-beta"); // true
new SemanticVersion("5.1").IsBetween("5.0", "5.2"); // true

Note that game versions before 1.2.0 and some mod versions are non-standard (e.g. Stardew Valley 1.11 comes before 1.2). All SMAPI versions are standard.

← SMAPI reference