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.TargetPlatform	The current operating system (one of Linux, Mac, or Windows).
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.IsGameLaunched	The following describes the upcoming SMAPI 3.0, and may change before release. Whether the game has been launched and initialised. This becomes true immediately before the first update tick.
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	Whether Context.IsWorldReady, and the player loaded the save in multiplayer mode (regardless of whether any other players are connected).
Context.IsMainPlayer	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 uniquely represent controller, keyboard, and mouse button presses or clicks. See the Input page for more info.

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