114
edits
Changes
Modding:Modder Guide/APIs/Utilities (view source)
Revision as of 18:28, 19 February 2021
, 18:28, 19 February 2021Replace deprecated <source> tags with <syntaxhighlight> tags
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.
===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
// 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");
// 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:
| 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>
| 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>
|}
|}
===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");
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.