Protected, translators
5,421
edits
This wiki is a read-only version of the Stardew Valley Wiki. The official editable wiki maintained by ConcernedApe can be found at stardewvalleywiki.com
Changes
move content from Modding:Modder Guide/APIs (only author is Pathoschild)
{{../../header}}
==Utilities==
SMAPI provides some C# objects you can use to simplify your code.
===Constants===
The <tt>Constants</tt> class provides metadata about SMAPI and the game.
{| class="wikitable"
|-
! value
! meaning
|-
| <tt>Constants.ApiVersion</tt>
| The version of the running SMAPI instance.
|-
| <tt>Constants.MinimumGameVersion</tt><br /><tt>Constants.MaximumGameVersion</tt>
| The game versions supported by the running SMAPI instance.
|-
| <tt>Constants.ExecutionPath</tt>
| The absolute path to the <tt>Stardew Valley</tt> folder.
|-
| <tt>Constants.DataPath</tt>
| The absolute path to the game's data folder (which contains the [[Saves|save folder]]).
|-
| <tt>Constants.LogDir</tt>
| The absolute path to the folder containing the game and SMAPI logs.
|-
| <tt>Constants.SavesPath</tt>
| The absolute path to the [[Saves|save folder]].
|-
| <tt>Constants.CurrentSavePath</tt>
| The absolute path to the current save folder, if a save is loaded.
|-
| <tt>Constants.SaveFolderName</tt>
| The name of the current save folder (like <tt>Name_012345789</tt>), if a save is loaded.
|}
===Context===
The <tt>Context</tt> class provides information about the game state and player control:
{| class="wikitable"
|-
! value
! meaning
|-
| <tt>Context.IsWorldReady</tt>
| Whether the player has loaded a save and the world has finished initialising. Useful for ignoring events before the save is loaded.
|-
| <tt>Context.IsPlayerFree</tt>
| Whether <tt>Context.IsWorldReady</tt> and the player is free to act on the world (no menu is displayed, no cutscene is in progress, etc).
|-
| <tt>Context.CanPlayerMove</tt>
| Whether <tt>Context.IsPlayerFree</tt> and the player is free to move (e.g. not using a tool).
|-
| <tt>Context.IsMultiplayer</tt>
| {{SMAPI upcoming|2.6|content=Whether <tt>Context.IsWorldReady</tt>, and the player loaded the save in multiplayer mode (regardless of whether any other players are connected).}}
|-
| <tt>Context.IsMainPlayer</tt>
| {{SMAPI upcoming|2.6|content=Whether <tt>Context.IsWorldReady</tt>, and the player is the main player. This is always true in single-player, and true when hosting in multiplayer.}}
|}
===Dates===
Use <tt>SDate</tt> for calculating in-game dates. You start by creating a date:
<source lang="c#">
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
</source>
Then you can calculate offsets from any date:
<source lang="c#">
// 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
</source>
...and compare dates:
<source lang="c#">
var a = new SDate(01, "spring");
var b = new SDate(02, "spring");
if (a < b) // true
...
</source>
Note that <tt>SDate</tt> won't let you create invalid dates:
<source lang="C#">
// 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);
</source>
Once created, dates have a few properties you can use:
{| class="wikitable"
|-
! property
! meaning
|-
| <tt>Day</tt>
| The day of month.
|-
| <tt>Season</tt>
| The normalised season name.
|-
| <tt>Year</tt>
| The year number.
|-
| <tt>DayOfWeek</tt>
| The day of week (like <tt>Monday</tt>).
|-
| <tt>DaysSinceStart</tt>
| '''[SMAPI 2.2+]''' The number of days since the first day, inclusively (i.e. 01 spring Y1 = 1).
|}
===Semantic versions===
Use <tt>SemanticVersion</tt> to manipulate and compare versions per the [http://semver.org/ Semantic Versioning 2.0 standard]. Example usage:
<source lang="c#">
// 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
</source>
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.
==Utilities==
SMAPI provides some C# objects you can use to simplify your code.
===Constants===
The <tt>Constants</tt> class provides metadata about SMAPI and the game.
{| class="wikitable"
|-
! value
! meaning
|-
| <tt>Constants.ApiVersion</tt>
| The version of the running SMAPI instance.
|-
| <tt>Constants.MinimumGameVersion</tt><br /><tt>Constants.MaximumGameVersion</tt>
| The game versions supported by the running SMAPI instance.
|-
| <tt>Constants.ExecutionPath</tt>
| The absolute path to the <tt>Stardew Valley</tt> folder.
|-
| <tt>Constants.DataPath</tt>
| The absolute path to the game's data folder (which contains the [[Saves|save folder]]).
|-
| <tt>Constants.LogDir</tt>
| The absolute path to the folder containing the game and SMAPI logs.
|-
| <tt>Constants.SavesPath</tt>
| The absolute path to the [[Saves|save folder]].
|-
| <tt>Constants.CurrentSavePath</tt>
| The absolute path to the current save folder, if a save is loaded.
|-
| <tt>Constants.SaveFolderName</tt>
| The name of the current save folder (like <tt>Name_012345789</tt>), if a save is loaded.
|}
===Context===
The <tt>Context</tt> class provides information about the game state and player control:
{| class="wikitable"
|-
! value
! meaning
|-
| <tt>Context.IsWorldReady</tt>
| Whether the player has loaded a save and the world has finished initialising. Useful for ignoring events before the save is loaded.
|-
| <tt>Context.IsPlayerFree</tt>
| Whether <tt>Context.IsWorldReady</tt> and the player is free to act on the world (no menu is displayed, no cutscene is in progress, etc).
|-
| <tt>Context.CanPlayerMove</tt>
| Whether <tt>Context.IsPlayerFree</tt> and the player is free to move (e.g. not using a tool).
|-
| <tt>Context.IsMultiplayer</tt>
| {{SMAPI upcoming|2.6|content=Whether <tt>Context.IsWorldReady</tt>, and the player loaded the save in multiplayer mode (regardless of whether any other players are connected).}}
|-
| <tt>Context.IsMainPlayer</tt>
| {{SMAPI upcoming|2.6|content=Whether <tt>Context.IsWorldReady</tt>, and the player is the main player. This is always true in single-player, and true when hosting in multiplayer.}}
|}
===Dates===
Use <tt>SDate</tt> for calculating in-game dates. You start by creating a date:
<source lang="c#">
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
</source>
Then you can calculate offsets from any date:
<source lang="c#">
// 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
</source>
...and compare dates:
<source lang="c#">
var a = new SDate(01, "spring");
var b = new SDate(02, "spring");
if (a < b) // true
...
</source>
Note that <tt>SDate</tt> won't let you create invalid dates:
<source lang="C#">
// 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);
</source>
Once created, dates have a few properties you can use:
{| class="wikitable"
|-
! property
! meaning
|-
| <tt>Day</tt>
| The day of month.
|-
| <tt>Season</tt>
| The normalised season name.
|-
| <tt>Year</tt>
| The year number.
|-
| <tt>DayOfWeek</tt>
| The day of week (like <tt>Monday</tt>).
|-
| <tt>DaysSinceStart</tt>
| '''[SMAPI 2.2+]''' The number of days since the first day, inclusively (i.e. 01 spring Y1 = 1).
|}
===Semantic versions===
Use <tt>SemanticVersion</tt> to manipulate and compare versions per the [http://semver.org/ Semantic Versioning 2.0 standard]. Example usage:
<source lang="c#">
// 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
</source>
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.
