107,472
edits
Changes
Jump to navigation
Jump to search
mLine 6:
Line 6: − + Line 14:
Line 14: − + Line 23:
Line 23: − + Line 30:
Line 30: − + − + − + − + − + − + − + − + − + − + − + − + − + − + − + Line 70:
Line 70: − + − + − + − + − + − + − + Line 92:
Line 92: − + − + − + − + − + − + − + − + − + − + − + Line 113:
Line 113: − + Line 144:
Line 144: − + Line 159:
Line 159: − + − + − + − + − + − + − + − + − + Line 209:
Line 209: − + − + Line 229:
Line 229: − +
Modding:Modder Guide/APIs/Utilities (view source)
Revision as of 18:48, 4 November 2021
, 18:48, 4 November 2021Text replacement - "tt>" to "samp>"
===Mod path===
===Mod path===
Before handling mod folder paths, be aware that:
Before handling mod folder paths, be aware that:
* The '''mod's folder path is not consistent'''. The game is installed to different folders, Nexus mods are often unzipped into a folder like <tt>Mods/Your Mod Name 1.27.5-541-1-27-5-1598664794/YourModFolder</tt> by default, and players can organize their mod folders like <tt>Mods/For single-player/YourModFolder</tt>.
* The '''mod's folder path is not consistent'''. The game is installed to different folders, Nexus mods are often unzipped into a folder like <samp>Mods/Your Mod Name 1.27.5-541-1-27-5-1598664794/YourModFolder</samp> by default, and players can organize their mod folders like <samp>Mods/For single-player/YourModFolder</samp>.
* Paths are formatted differently on Linux/Mac/Android vs Windows.
* Paths are formatted differently on Linux/Mac/Android vs Windows.
</syntaxhighlight>
</syntaxhighlight>
If you really need a full path, you should use <tt>this.Helper.DirectoryPath</tt> and <tt>Path.Combine</tt> to get it:
If you really need a full path, you should use <samp>this.Helper.DirectoryPath</samp> and <samp>Path.Combine</samp> to get it:
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
string path = Path.Combine(this.Helper.DirectoryPath, "assets", "data.json"); // "assets/data.json" in the current mod's folder
string path = Path.Combine(this.Helper.DirectoryPath, "assets", "data.json"); // "assets/data.json" in the current mod's folder
===Constants===
===Constants===
The <tt>Constants</tt> class provides metadata about SMAPI and the game.
The <samp>Constants</samp> class provides metadata about SMAPI and the game.
{| class="wikitable"
{| class="wikitable"
! meaning
! meaning
|-
|-
| <tt>Constants.ApiVersion</tt>
| <samp>Constants.ApiVersion</samp>
| The version of the running SMAPI instance.
| The version of the running SMAPI instance.
|-
|-
| <tt>Constants.MinimumGameVersion</tt><br /><tt>Constants.MaximumGameVersion</tt>
| <samp>Constants.MinimumGameVersion</samp><br /><samp>Constants.MaximumGameVersion</samp>
| The game versions supported by the running SMAPI instance.
| The game versions supported by the running SMAPI instance.
|-
|-
| <tt>Constants.TargetPlatform</tt>
| <samp>Constants.TargetPlatform</samp>
| The current operating system (one of <tt>Android</tt>, <tt>Linux</tt>, <tt>Mac</tt>, or <tt>Windows</tt>).
| The current operating system (one of <samp>Android</samp>, <samp>Linux</samp>, <samp>Mac</samp>, or <samp>Windows</samp>).
|-
|-
| <tt>Constants.GameFramework</tt>
| <samp>Constants.GameFramework</samp>
| The game framework running the game (one of <tt>Xna</tt> or <tt>MonoGame</tt>).
| The game framework running the game (one of <samp>Xna</samp> or <samp>MonoGame</samp>).
|-
|-
| <tt>Constants.ExecutionPath</tt>
| <samp>Constants.ExecutionPath</samp>
| The absolute path to the <tt>Stardew Valley</tt> folder.
| The absolute path to the <samp>Stardew Valley</samp> folder.
|-
|-
| <tt>Constants.DataPath</tt>
| <samp>Constants.DataPath</samp>
| The absolute path to the game's data folder (which contains the [[Saves|save folder]]).
| The absolute path to the game's data folder (which contains the [[Saves|save folder]]).
|-
|-
| <tt>Constants.LogDir</tt>
| <samp>Constants.LogDir</samp>
| The absolute path to the folder containing the game and SMAPI logs.
| The absolute path to the folder containing the game and SMAPI logs.
|-
|-
| <tt>Constants.SavesPath</tt>
| <samp>Constants.SavesPath</samp>
| The absolute path to the [[Saves|save folder]].
| The absolute path to the [[Saves|save folder]].
|-
|-
| <tt>Constants.CurrentSavePath</tt>
| <samp>Constants.CurrentSavePath</samp>
| The absolute path to the current save folder, if a save is loaded.
| The absolute path to the current save folder, if a save is loaded.
|-
|-
| <tt>Constants.SaveFolderName</tt>
| <samp>Constants.SaveFolderName</samp>
| The name of the current save folder (like <tt>Name_012345789</tt>), if a save is loaded.
| The name of the current save folder (like <samp>Name_012345789</samp>), if a save is loaded.
|}
|}
===Context===
===Context===
The <tt>Context</tt> class provides information about the game state and player control.
The <samp>Context</samp> class provides information about the game state and player control.
; Game/player state:
; Game/player state:
! meaning
! meaning
|-
|-
| <tt>Context.IsGameLaunched</tt>
| <samp>Context.IsGameLaunched</samp>
| Whether the game has been launched and initialised. This becomes true immediately before the first update tick.
| Whether the game has been launched and initialised. This becomes true immediately before the first update tick.
|-
|-
| <tt>Context.IsWorldReady</tt>
| <samp>Context.IsWorldReady</samp>
| Whether the player has loaded a save and the world has finished initialising. Useful for ignoring events before the save is loaded.
| 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>
| <samp>Context.IsPlayerFree</samp>
| 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).
| Whether <samp>Context.IsWorldReady</samp> and the player is free to act on the world (no menu is displayed, no cutscene is in progress, etc).
|-
|-
| <tt>Context.CanPlayerMove</tt>
| <samp>Context.CanPlayerMove</samp>
| Whether <tt>Context.IsPlayerFree</tt> and the player is free to move (e.g. not using a tool).
| Whether <samp>Context.IsPlayerFree</samp> and the player is free to move (e.g. not using a tool).
|-
|-
| <tt>Context.IsInDrawLoop</tt>
| <samp>Context.IsInDrawLoop</samp>
| Whether the game is currently running the draw loop. This isn't relevant to most mods, since you should use [[Modding:Modder Guide/APIs/Events|display events]] to draw to the screen.
| Whether the game is currently running the draw loop. This isn't relevant to most mods, since you should use [[Modding:Modder Guide/APIs/Events|display events]] to draw to the screen.
|}
|}
! meaning
! meaning
|-
|-
| <tt>Context.IsMultiplayer</tt>
| <samp>Context.IsMultiplayer</samp>
| Whether <tt>Context.IsWorldReady</tt>, and the world was loaded in multiplayer mode (regardless of whether any other players are connected) or is currently in split-screen mode.
| Whether <samp>Context.IsWorldReady</samp>, and the world was loaded in multiplayer mode (regardless of whether any other players are connected) or is currently in split-screen mode.
|-
|-
| <tt>Context.IsSplitScreen</tt>
| <samp>Context.IsSplitScreen</samp>
| Whether <tt>Context.IsMultiplayer</tt> and the ''current player'' is in split-screen mode. This doesn't apply for remote players.
| Whether <samp>Context.IsMultiplayer</samp> and the ''current player'' is in split-screen mode. This doesn't apply for remote players.
|-
|-
| <tt>Context.HasRemotePlayers</tt>
| <samp>Context.HasRemotePlayers</samp>
| Whether <tt>Context.IsMultiplayer</tt> and any players are connected over the network.
| Whether <samp>Context.IsMultiplayer</samp> and any players are connected over the network.
|-
|-
| <tt>Context.IsMainPlayer</tt>
| <samp>Context.IsMainPlayer</samp>
| 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.
| Whether <samp>Context.IsWorldReady</samp>, and the player is the main player. This is always true in single-player, and true when hosting in multiplayer.
|-
|-
| <tt>Context.IsOnHostComputer</tt>
| <samp>Context.IsOnHostComputer</samp>
| Whether the current player is on the host computer. This is true when <tt>Context.IsMainPlayer</tt>, or for farmhands in split-screen mode.
| Whether the current player is on the host computer. This is true when <samp>Context.IsMainPlayer</samp>, or for farmhands in split-screen mode.
|-
|-
| <tt>Context.ScreenId</tt>
| <samp>Context.ScreenId</samp>
| The unique ID of the current screen in split-screen mode. The main player always has ID 0. A screen is always assigned a new ID when it's opened (so a player who quits and rejoins will get a new screen ID).
| The unique ID of the current screen in split-screen mode. The main player always has ID 0. A screen is always assigned a new ID when it's opened (so a player who quits and rejoins will get a new screen ID).
|}
|}
==Helpers==
==Helpers==
===Dates===
===Dates===
Use <tt>SDate</tt> for calculating in-game dates. You start by creating a date:
Use <samp>SDate</samp> for calculating in-game dates. You start by creating a date:
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
var date = SDate.Now(); // current date
var date = SDate.Now(); // current date
</syntaxhighlight>
</syntaxhighlight>
Note that <tt>SDate</tt> won't let you create invalid dates:
Note that <samp>SDate</samp> won't let you create invalid dates:
<syntaxhighlight lang="C#">
<syntaxhighlight lang="C#">
// ArgumentException: Invalid day '30', must be a value from 1 to 28.
// ArgumentException: Invalid day '30', must be a value from 1 to 28.
! meaning
! meaning
|-
|-
| <tt>Day</tt>
| <samp>Day</samp>
| The day of month.
| The day of month.
|-
|-
| <tt>Season</tt>
| <samp>Season</samp>
| The normalised season name.
| The normalised season name.
|-
|-
| <tt>SeasonIndex</tt>
| <samp>SeasonIndex</samp>
| The zero-based season index recognised by game methods like <tt>Utility.getSeasonNameFromNumber</tt>.
| The zero-based season index recognised by game methods like <samp>Utility.getSeasonNameFromNumber</samp>.
|-
|-
| <tt>Year</tt>
| <samp>Year</samp>
| The year number.
| The year number.
|-
|-
| <tt>DayOfWeek</tt>
| <samp>DayOfWeek</samp>
| The day of week (like <tt>Monday</tt>).
| The day of week (like <samp>Monday</samp>).
|-
|-
| <tt>DaysSinceStart</tt>
| <samp>DaysSinceStart</samp>
| The number of days since the first day, inclusively (i.e. 01 spring Y1 = 1).
| The number of days since the first day, inclusively (i.e. 01 spring Y1 = 1).
|}
|}
===File paths===
===File paths===
<tt>PathUtilities</tt> provides utility methods for working with file paths and [[Modding:Modder Guide/APIs/Content|asset names]], complementing the <tt>Path</tt> class provided by .NET:
<samp>PathUtilities</samp> provides utility methods for working with file paths and [[Modding:Modder Guide/APIs/Content|asset names]], complementing the <samp>Path</samp> class provided by .NET:
{| class="wikitable"
{| class="wikitable"
===Per-screen data===
===Per-screen data===
SMAPI's <code>PerScreen<T></code> utility manages a separate value for each local screen in split-screen mode. See [[Modding:Modder Guide/APIs/Multiplayer#Per-screen data|<tt>PerScreen<T></tt> in the multiplayer API]] for details.
SMAPI's <code>PerScreen<T></code> utility manages a separate value for each local screen in split-screen mode. See [[Modding:Modder Guide/APIs/Multiplayer#Per-screen data|<samp>PerScreen<T></samp> in the multiplayer API]] for details.
===Semantic versions===
===Semantic versions===
Use <tt>SemanticVersion</tt> to manipulate and compare versions per the [http://semver.org/ Semantic Versioning 2.0 standard]. Example usage:
Use <samp>SemanticVersion</samp> to manipulate and compare versions per the [http://semver.org/ Semantic Versioning 2.0 standard]. Example usage:
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
// build version from parts
// build version from parts
==Input==
==Input==
SMAPI's <tt>SButton</tt> constants uniquely represent controller, keyboard, and mouse button presses or clicks. See the [[../Input|Input]] page for more info.
SMAPI's <samp>SButton</samp> constants uniquely represent controller, keyboard, and mouse button presses or clicks. See the [[../Input|Input]] page for more info.