Modding:Modder Guide/APIs/Utilities - Revision history

imported>Sunbeam135: /* Input */

2026-01-09T14:31:13Z

Input

← Older revision		Revision as of 14:31, 9 January 2026
Line 234:		Line 234:
	SMAPI's <samp>SButton</samp> 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.

			[[ru:Модификации:Руководство мододела/API/Утилиты]]
	[[zh:模组:制作指南/APIs/Utilities]]		[[zh:模组:制作指南/APIs/Utilities]]

imported>VulpesLucida: zh link

2025-01-05T14:33:23Z

zh link

← Older revision		Revision as of 14:33, 5 January 2025
Line 233:		Line 233:
	==Input==		==Input==
	SMAPI's <samp>SButton</samp> 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.

			[[zh:模组:制作指南/APIs/Utilities]]

imported>Yariazen: /* Constants */ Updated to match SMAPI 4.0.6 Constants Class

2024-04-15T00:38:56Z

Constants: Updated to match SMAPI 4.0.6 Constants Class

← Older revision		Revision as of 00:38, 15 April 2024
Line 42:		Line 42:
	\| The game framework running the game (one of <samp>Xna</samp> or <samp>MonoGame</samp>).		\| The game framework running the game (one of <samp>Xna</samp> or <samp>MonoGame</samp>).
	\|-		\|-
	\| <samp>Constants.~~ExecutionPath~~</samp>		\| <samp>Constants.GamePath</samp>
	\| The absolute path to the <samp>Stardew Valley</samp> folder.		\| The absolute path to the <samp>Stardew Valley</samp> folder.
			\|-
			\| <samp>Constants.ContentPath</samp>
			\| The absolute path to the game's <samp>Content</samp> folder.
	\|-		\|-
	\| <samp>Constants.DataPath</samp>		\| <samp>Constants.DataPath</samp>

imported>Margotbean: Text replacement - "i.e. " to "''i.e.,'' "

2021-11-08T01:06:28Z

Text replacement - "i.e. " to "''i.e.,'' "

← Older revision		Revision as of 01:06, 8 November 2021
Line 175:		Line 175:
	\|-		\|-
	\| <samp>DaysSinceStart</samp>		\| <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).
	\|}		\|}

imported>Margotbean: Text replacement - "''e.g.''," to "''e.g.,''"

2021-11-08T00:39:55Z

Text replacement - "''e.g.''," to "''e.g.,''"

← Older revision		Revision as of 00:39, 8 November 2021
Line 80:		Line 80:
	\|-		\|-
	\| <samp>Context.CanPlayerMove</samp>		\| <samp>Context.CanPlayerMove</samp>
	\| Whether <samp>Context.IsPlayerFree</samp> 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).
	\|-		\|-
	\| <samp>Context.IsInDrawLoop</samp>		\| <samp>Context.IsInDrawLoop</samp>
Line 197:		Line 197:
	\|-		\|-
	\| <code>IsSlug</code>		\| <code>IsSlug</code>
	\| Get whether a string can be used as a 'slug', containing only basic characters that are safe in all contexts (''e.g.'', filenames, URLs, SMAPI IDs, etc).		\| Get whether a string can be used as a 'slug', containing only basic characters that are safe in all contexts (''e.g.,'' filenames, URLs, SMAPI IDs, etc).
	\|-		\|-
	\| <code>NormalizePath</code>		\| <code>NormalizePath</code>
Line 226:		Line 226:
	</syntaxhighlight>		</syntaxhighlight>

	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.		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.

	==Input==		==Input==
	SMAPI's <samp>SButton</samp> 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.

imported>Margotbean: Text replacement - "(e.g. " to "(''e.g.'', "

2021-11-07T23:41:21Z

Text replacement - "(e.g. " to "(''e.g.'', "

← Older revision		Revision as of 23:41, 7 November 2021
Line 80:		Line 80:
	\|-		\|-
	\| <samp>Context.CanPlayerMove</samp>		\| <samp>Context.CanPlayerMove</samp>
	\| Whether <samp>Context.IsPlayerFree</samp> 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).
	\|-		\|-
	\| <samp>Context.IsInDrawLoop</samp>		\| <samp>Context.IsInDrawLoop</samp>
Line 197:		Line 197:
	\|-		\|-
	\| <code>IsSlug</code>		\| <code>IsSlug</code>
	\| Get whether a string can be used as a 'slug', containing only basic characters that are safe in all contexts (e.g. filenames, URLs, SMAPI IDs, etc).		\| Get whether a string can be used as a 'slug', containing only basic characters that are safe in all contexts (''e.g.'', filenames, URLs, SMAPI IDs, etc).
	\|-		\|-
	\| <code>NormalizePath</code>		\| <code>NormalizePath</code>
Line 226:		Line 226:
	</syntaxhighlight>		</syntaxhighlight>

	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.		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.

	==Input==		==Input==
	SMAPI's <samp>SButton</samp> 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.

imported>Margotbean: Text replacement - "tt>" to "samp>"

2021-11-04T18:48:44Z

Text replacement - "tt>" to "samp>"

Show changes

imported>Pathoschild: /* Constants */ + GameFramework in SMAPI 3.9.5

2021-03-21T21:02:15Z

Constants: + GameFramework in SMAPI 3.9.5

← Older revision		Revision as of 21:02, 21 March 2021
Line 38:		Line 38:
	\| <tt>Constants.TargetPlatform</tt>		\| <tt>Constants.TargetPlatform</tt>
	\| 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 <tt>Android</tt>, <tt>Linux</tt>, <tt>Mac</tt>, or <tt>Windows</tt>).
			\|-
			\| <tt>Constants.GameFramework</tt>
			\| The game framework running the game (one of <tt>Xna</tt> or <tt>MonoGame</tt>).
	\|-		\|-
	\| <tt>Constants.ExecutionPath</tt>		\| <tt>Constants.ExecutionPath</tt>

imported>Pathoschild: /* Context */ add new context values

2021-03-04T03:38:40Z

Context: add new context values

← Older revision		Revision as of 03:38, 4 March 2021
Line 59:		Line 59:

	===Context===		===Context===
	The <tt>Context</tt> class provides information about the game state and player control:		The <tt>Context</tt> class provides information about the game state and player control.

	{\| class="wikitable"		; Game/player state:
			: {\| class="wikitable"
	\|-		\|-
	! value		! value
Line 77:		Line 78:
	\| <tt>Context.CanPlayerMove</tt>		\| <tt>Context.CanPlayerMove</tt>
	\| Whether <tt>Context.IsPlayerFree</tt> and the player is free to move (e.g. not using a tool).		\| Whether <tt>Context.IsPlayerFree</tt> and the player is free to move (e.g. not using a tool).
			\|-
			\| <tt>Context.IsInDrawLoop</tt>
			\| 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.
			\|}

			; [[Multiplayer]]:
			: {\| class="wikitable"
			\|-
			! value
			! meaning
	\|-		\|-
	\| <tt>Context.IsMultiplayer</tt>		\| <tt>Context.IsMultiplayer</tt>
	\| Whether <tt>Context.IsWorldReady</tt>, and the ~~player~~ loaded ~~the save~~ in multiplayer mode (regardless of whether any other players are connected).		\| 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.
			\|-
			\| <tt>Context.IsSplitScreen</tt>
			\| Whether <tt>Context.IsMultiplayer</tt> and the ''current player'' is in split-screen mode. This doesn't apply for remote players.
			\|-
			\| <tt>Context.HasRemotePlayers</tt>
			\| Whether <tt>Context.IsMultiplayer</tt> and any players are connected over the network.
	\|-		\|-
	\| <tt>Context.IsMainPlayer</tt>		\| <tt>Context.IsMainPlayer</tt>
	\| 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 <tt>Context.IsWorldReady</tt>, and the player is the main player. This is always true in single-player, and true when hosting in multiplayer.
			\|-
			\| <tt>Context.IsOnHostComputer</tt>
			\| Whether the current player is on the host computer. This is true when <tt>Context.IsMainPlayer</tt>, or for farmhands in split-screen mode.
			\|-
			\| <tt>Context.ScreenId</tt>
			\| 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).
	\|}		\|}

imported>RetroEdit: Replace deprecated tags with tags

2021-02-19T18:28:30Z

Replace deprecated <source> tags with <syntaxhighlight> tags

← Older revision		Revision as of 18:28, 19 February 2021
Line 10:		Line 10:

	You don't need to worry about that when using SMAPI APIs, which take relative paths and automatically fix the format if needed:		You don't need to worry about that when using SMAPI APIs, which take relative paths and automatically fix the format if needed:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	var data = this.Helper.Data.ReadJsonFile<SomeDataModel>("assets/data.json");		var data = this.Helper.Data.ReadJsonFile<SomeDataModel>("assets/data.json");
	</~~source~~>		</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 <tt>this.Helper.DirectoryPath</tt> and <tt>Path.Combine</tt> to get it:
	<~~source~~ 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
	var file = new FileInfo(path);		var file = new FileInfo(path);
	</~~source~~>		</syntaxhighlight>

	See ''[[#Constants\|Constants]]'' for other paths like the game folder.		See ''[[#Constants\|Constants]]'' for other paths like the game folder.
Line 88:		Line 88:
	===Dates===		===Dates===
	Use <tt>SDate</tt> for calculating in-game dates. You start by creating a date:		Use <tt>SDate</tt> for calculating in-game dates. You start by creating a date:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	var date = SDate.Now(); // current date		var date = SDate.Now(); // current date
	var date = new SDate(28, "spring"); // date in the current year		var date = new SDate(28, "spring"); // date in the current year
	var date = new SDate(28, "spring", 2); // date in the given year		var date = new SDate(28, "spring", 2); // date in the given year
	var date = SDate.From(Game1.Date); // from a game date		var date = SDate.From(Game1.Date); // from a game date
	</~~source~~>		</syntaxhighlight>

	Then you can calculate offsets from any date:		Then you can calculate offsets from any date:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	// add days		// add days
	new SDate(28, "spring", 1).AddDays(370); // 06 fall in year 4		new SDate(28, "spring", 1).AddDays(370); // 06 fall in year 4
Line 102:		Line 102:
	// subtract days		// subtract days
	new SDate(01, "spring", 2).AddDays(-1); // 28 winter in year 1		new SDate(01, "spring", 2).AddDays(-1); // 28 winter in year 1
	</~~source~~>		</syntaxhighlight>

	...and compare dates:		...and compare dates:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	var a = new SDate(01, "spring");		var a = new SDate(01, "spring");
	var b = new SDate(02, "spring");		var b = new SDate(02, "spring");
	if (a < b) // true		if (a < b) // true
	...		...
	</~~source~~>		</syntaxhighlight>

	...and get a translated date string:		...and get a translated date string:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	var date = new SDate(15, "summer");		var date = new SDate(15, "summer");
	string message = $"See you on {date.ToLocaleString(withYear: false)}!"; // See you on Summer 15!		string message = $"See you on {date.ToLocaleString(withYear: false)}!"; // See you on Summer 15!
	</~~source~~>		</syntaxhighlight>

	Note that <tt>SDate</tt> won't let you create invalid dates:		Note that <tt>SDate</tt> won't let you create invalid dates:
	<~~source~~ 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.
	new SDate(30, "spring");		new SDate(30, "spring");
Line 125:		Line 125:
	// ArithmeticException: Adding -1 days to 01 spring Y1 would result in invalid date 28 winter Y0.		// ArithmeticException: Adding -1 days to 01 spring Y1 would result in invalid date 28 winter Y0.
	new SDate(01, "spring", 1).AddDays(-1);		new SDate(01, "spring", 1).AddDays(-1);
	</~~source~~>		</syntaxhighlight>

	Once created, dates have a few properties you can use:		Once created, dates have a few properties you can use:
Line 163:		Line 163:
	\| Split a path into its delimited segments, like <code>/usr/bin/example</code> → <code>usr</code>, <code>bin</code>, and <code>example</code>. For example:		\| Split a path into its delimited segments, like <code>/usr/bin/example</code> → <code>usr</code>, <code>bin</code>, and <code>example</code>. For example:

	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	string[] segments = PathUtilities.GetSegments(Constants.ExecutionPath);		string[] segments = PathUtilities.GetSegments(Constants.ExecutionPath);
	</~~source~~>		</syntaxhighlight>
	\|-		\|-
	\| <code>IsSafeRelativePath</code>		\| <code>IsSafeRelativePath</code>
Line 176:		Line 176:
	\| Normalize file paths or asset names to match the format used by the current OS. For example:		\| Normalize file paths or asset names to match the format used by the current OS. For example:

	<~~source~~ lang="c#">string path = PathUtilities.NormalizePathSeparators(@"Characters\Dialogue//Abigail");		<syntaxhighlight lang="c#">string path = PathUtilities.NormalizePathSeparators(@"Characters\Dialogue//Abigail");
	// Linux/Mac: "Characters/Dialogue/Abigail"		// Linux/Mac: "Characters/Dialogue/Abigail"
	// Windows: "Characters\Dialogue\Abigail"		// Windows: "Characters\Dialogue\Abigail"
	</~~source~~>		</syntaxhighlight>
	\|}		\|}

Line 187:		Line 187:
	===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 <tt>SemanticVersion</tt> to manipulate and compare versions per the [http://semver.org/ Semantic Versioning 2.0 standard]. Example usage:
	<~~source~~ lang="c#">		<syntaxhighlight lang="c#">
	// build version from parts		// build version from parts
	ISemanticVersion version = new SemanticVersion(5, 1, 0, "beta");		ISemanticVersion version = new SemanticVersion(5, 1, 0, "beta");
Line 198:		Line 198:
	new SemanticVersion("5.10").IsNewerThan("5.10-beta"); // true		new SemanticVersion("5.10").IsNewerThan("5.10-beta"); // true
	new SemanticVersion("5.1").IsBetween("5.0", "5.2"); // true		new SemanticVersion("5.1").IsBetween("5.0", "5.2"); // true
	</~~source~~>		</syntaxhighlight>

	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.		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.