Modding:Modder Guide/Game Fundamentals - Revision history

imported>Pathoschild: /* Net fields */ remove pre-Stardew-Valley-1.6.9 info

2025-05-31T17:51:04Z

Net fields: remove pre-Stardew-Valley-1.6.9 info

← Older revision		Revision as of 17:51, 31 May 2025
Line 152:		Line 152:
	===Net fields===		===Net fields===
	A 'net type' is any of several classes which Stardew Valley uses to sync data between players, and a 'net field' is any field or property of those types. They're named for the <code>Net</code> prefix in their type names. Net types can represent simple values like <samp>NetBool</samp>, or complex values like <samp>NetFieldDictionary</samp>. The game will regularly collect all the net fields reachable from <samp>Game1.netWorldState</samp> and sync them with other players. That means that many mod changes will be synchronised automatically in multiplayer.		A 'net type' is any of several classes which Stardew Valley uses to sync data between players, and a 'net field' is any field or property of those types. They're named for the <code>Net</code> prefix in their type names. Net types can represent simple values like <samp>NetBool</samp>, or complex values like <samp>NetFieldDictionary</samp>. The game will regularly collect all the net fields reachable from <samp>Game1.netWorldState</samp> and sync them with other players. That means that many mod changes will be synchronised automatically in multiplayer.

	Although net fields can be implicitly converted to an equivalent value type (like <code>bool x = new NetBool(true)</code>), their conversion rules are counterintuitive and error-prone (''e.g.,'' <code>item?.category == null && item?.category != null</code> can both be true at once). To avoid bugs, never implicitly cast net fields; access the underlying value directly instead. The build config NuGet package should detect most implicit conversions and show an appropriate build warning.

	~~{{SMAPI upcoming\|1.6.9\|The game no longer has implicit conversion operators for net fields in 1.6.9.}}~~

	Here's how to access the data in some common net types:		Here's how to access the data in some common net types:

imported>Pathoschild: /* Farmhand shadow world */ document which locations are active by default

2025-05-26T21:35:39Z

Farmhand shadow world: document which locations are active by default

← Older revision		Revision as of 21:35, 26 May 2025
Line 174:		Line 174:

	===Farmhand shadow world===		===Farmhand shadow world===
	In [[multiplayer]], secondary players (''farmhands'') ~~don~~'~~t see most of the in-game locations~~. ~~Instead their~~ game creates a single-player copy of the world before they join~~, and then only fetches the [[farm\|farm area]] and their current location (called ''active locations'') from the host player~~. The unsynchronized locations often don't match what players within those locations see.		In [[multiplayer]], only the main player has access to all the locations in the game; the game then synchronizes a few of those locations (called ''active locations'') to secondary players (i.e. ''farmhands''). The default active locations are the farmhand's current location, farm, farm cave, main farmhouse (not cabins or cellars), and greenhouse.

			Otherwise a farmhand's game creates a single-player copy of the world before they join. The unsynchronized locations often don't match what players within those locations see.

	This has some significant implications for C# mods:		This has some significant implications for C# mods:

imported>Quicksilver at 22:32, 3 December 2024

2024-12-03T22:32:24Z

← Older revision		Revision as of 22:32, 3 December 2024
Line 325:		Line 325:

	[[es:Modding:Guía del Modder/Fundamentos del juego]]		[[es:Modding:Guía del Modder/Fundamentos del juego]]
	[[ru:Модификации:~~Моддер гайд~~/Основы игры]]		[[ru:Модификации:Руководство мододела/Основы игры]]
	[[zh:模组:制作指南/游戏基本架构]]		[[zh:模组:制作指南/游戏基本架构]]

imported>Pathoschild: /* Net fields */ note: implicit conversion operators removed in 1.6.9

2024-11-03T20:09:17Z

Net fields: note: implicit conversion operators removed in 1.6.9

← Older revision		Revision as of 20:09, 3 November 2024
Line 154:		Line 154:

	Although net fields can be implicitly converted to an equivalent value type (like <code>bool x = new NetBool(true)</code>), their conversion rules are counterintuitive and error-prone (''e.g.,'' <code>item?.category == null && item?.category != null</code> can both be true at once). To avoid bugs, never implicitly cast net fields; access the underlying value directly instead. The build config NuGet package should detect most implicit conversions and show an appropriate build warning.		Although net fields can be implicitly converted to an equivalent value type (like <code>bool x = new NetBool(true)</code>), their conversion rules are counterintuitive and error-prone (''e.g.,'' <code>item?.category == null && item?.category != null</code> can both be true at once). To avoid bugs, never implicitly cast net fields; access the underlying value directly instead. The build config NuGet package should detect most implicit conversions and show an appropriate build warning.

			{{SMAPI upcoming\|1.6.9\|The game no longer has implicit conversion operators for net fields in 1.6.9.}}

	Here's how to access the data in some common net types:		Here's how to access the data in some common net types:

imported>Pathoschild: remove {{upcoming|1.6}}

2024-04-06T18:06:35Z

remove {{upcoming|1.6}}

← Older revision		Revision as of 18:06, 6 April 2024
Line 180:		Line 180:
	* When a farmhand warps to a location, the game fetches the real location from the host player before the warp completes. For a short while, the farmhand may have a null <samp>currentLocation</samp> field while they're between locations.		* When a farmhand warps to a location, the game fetches the real location from the host player before the warp completes. For a short while, the farmhand may have a null <samp>currentLocation</samp> field while they're between locations.

	~~<br />{{upcoming\|1.6\|~~You can check whether a location is active using its <samp>IsActiveLocation</samp> method:		You can check whether a location is active using its <samp>IsActiveLocation</samp> method:
	<syntaxhighlight lang="c#">		<syntaxhighlight lang="c#">
	foreach (GameLocation location in Game1.locations)		foreach (GameLocation location in Game1.locations)
Line 190:		Line 190:
	}		}
	</syntaxhighlight>		</syntaxhighlight>
	}}

	==Main classes==		==Main classes==

imported>Pathoschild: /* Assets */ remove section (moved to Modding:Common data field types)

2024-02-19T17:32:30Z

Assets: remove section (moved to Modding:Common data field types)

← Older revision		Revision as of 17:32, 19 February 2024
Line 191:		Line 191:
	</syntaxhighlight>		</syntaxhighlight>
	}}		}}

	~~==Assets==~~
	~~===String keys===~~
	A ''string key'' uniquely identifies where to find translatable text, in the form <samp>{{t\|asset name}}:{{t\|key}}</samp>. For example, <code>Game1.content.LoadString("Strings\\StringsFromCSFiles:spring")</code> will look for a <samp>spring</samp> key in the <samp>Strings\StringsFromCSFiles</samp> file in the content folder (which contains "spring"). This is commonly used in the game code (via <code>Game1.content.LoadString</code>) and in data assets which need translatable text.

	==Main classes==		==Main classes==

imported>Pathoschild: /* General concepts */ remove unique string IDs (moved to Modding:Common data field types)

2024-02-19T17:32:04Z

General concepts: remove unique string IDs (moved to Modding:Common data field types)

← Older revision		Revision as of 17:32, 19 February 2024
Line 148:		Line 148:

	: You can test whether your mod accounts for this correctly by setting the zoom to maximum and the UI scale to minimum (''i.e.,'' have them at opposite values) or vice versa; in particular check any logic which handles pixel positions, like menus clicking.		: You can test whether your mod accounts for this correctly by setting the zoom to maximum and the UI scale to minimum (''i.e.,'' have them at opposite values) or vice versa; in particular check any logic which handles pixel positions, like menus clicking.

	~~===Unique string IDs===~~
	~~{{upcoming\|1.6}}~~

	The game identifies data using unique string IDs. For example, <code>Town</code> is the unique ID for the [[Pelican Town]] location; no other location can use that ID. The IDs are used for a wide range of purposes, from internal game logic to [[Modding:Content Patcher\|content pack edits]].

	~~Best practices for mods:~~
	* Use namespaced IDs prefixed with your [[Modding:Modder Guide/APIs/Manifest#Basic fields\|mod's unique ID]]. For example, if your mod ID is <code>Example.PufferchickMod</code> and you're adding a pufferchick plushy, your item ID would look like <code>Example.PufferchickMod_PufferchickPlushy</code> (or optionally <code><nowiki>{{ModId}}_PufferchickPlushy</nowiki></code> in a [[Modding:Content Patcher\|Content Patcher pack]]). Although the game doesn't validate the ID format, you're '''strongly encouraged''' to use this exact format to maintain good mod compatibility, avoid ID conflicts, and allow automatically determining which mod added custom content.
	* Only use alphanumeric (a–z, A–Z, 0–9), underscore (<code>_</code>), and dot (<code>.</code>) characters in string IDs. This is important because they're often used in places where some characters have special meaning (like file names or [[Modding:Game state queries\|game state queries]]).

	==Multiplayer concepts for C# mods==		==Multiplayer concepts for C# mods==

imported>Pathoschild: /* Unique string IDs */ mention Content Patcher's {{ModId}}

2024-01-20T06:42:17Z

Unique string IDs: mention Content Patcher's {{ModId}}

← Older revision		Revision as of 06:42, 20 January 2024
Line 155:		Line 155:

	Best practices for mods:		Best practices for mods:
	* Use namespaced IDs prefixed with your [[Modding:Modder Guide/APIs/Manifest#Basic fields\|mod's unique ID]]. For example, if your mod ID is <code>Example.PufferchickMod</code> and you're adding a pufferchick plushy, your item ID would look like <code>Example.PufferchickMod_PufferchickPlushy</code>. Although the game doesn't validate the ID format, you're '''strongly encouraged''' to use this exact format to maintain good mod compatibility, avoid ID conflicts, and allow automatically determining which mod added custom content.		* Use namespaced IDs prefixed with your [[Modding:Modder Guide/APIs/Manifest#Basic fields\|mod's unique ID]]. For example, if your mod ID is <code>Example.PufferchickMod</code> and you're adding a pufferchick plushy, your item ID would look like <code>Example.PufferchickMod_PufferchickPlushy</code> (or optionally <code><nowiki>{{ModId}}_PufferchickPlushy</nowiki></code> in a [[Modding:Content Patcher\|Content Patcher pack]]). Although the game doesn't validate the ID format, you're '''strongly encouraged''' to use this exact format to maintain good mod compatibility, avoid ID conflicts, and allow automatically determining which mod added custom content.
	* Only use alphanumeric (a–z, A–Z, 0–9), underscore (<code>_</code>), and dot (<code>.</code>) characters in string IDs. This is important because they're often used in places where some characters have special meaning (like file names or [[Modding:Game state queries\|game state queries]]).		* Only use alphanumeric (a–z, A–Z, 0–9), underscore (<code>_</code>), and dot (<code>.</code>) characters in string IDs. This is important because they're often used in places where some characters have special meaning (like file names or [[Modding:Game state queries\|game state queries]]).

imported>Pathoschild: /* General concepts */ + unique string IDs

2023-11-23T00:12:43Z

General concepts: + unique string IDs

← Older revision		Revision as of 00:12, 23 November 2023
Line 148:		Line 148:

	: You can test whether your mod accounts for this correctly by setting the zoom to maximum and the UI scale to minimum (''i.e.,'' have them at opposite values) or vice versa; in particular check any logic which handles pixel positions, like menus clicking.		: You can test whether your mod accounts for this correctly by setting the zoom to maximum and the UI scale to minimum (''i.e.,'' have them at opposite values) or vice versa; in particular check any logic which handles pixel positions, like menus clicking.

			===Unique string IDs===
			{{upcoming\|1.6}}

			The game identifies data using unique string IDs. For example, <code>Town</code> is the unique ID for the [[Pelican Town]] location; no other location can use that ID. The IDs are used for a wide range of purposes, from internal game logic to [[Modding:Content Patcher\|content pack edits]].

			Best practices for mods:
			* Use namespaced IDs prefixed with your [[Modding:Modder Guide/APIs/Manifest#Basic fields\|mod's unique ID]]. For example, if your mod ID is <code>Example.PufferchickMod</code> and you're adding a pufferchick plushy, your item ID would look like <code>Example.PufferchickMod_PufferchickPlushy</code>. Although the game doesn't validate the ID format, you're '''strongly encouraged''' to use this exact format to maintain good mod compatibility, avoid ID conflicts, and allow automatically determining which mod added custom content.
			* Only use alphanumeric (a–z, A–Z, 0–9), underscore (<code>_</code>), and dot (<code>.</code>) characters in string IDs. This is important because they're often used in places where some characters have special meaning (like file names or [[Modding:Game state queries\|game state queries]]).

	==Multiplayer concepts for C# mods==		==Multiplayer concepts for C# mods==

imported>Pathoschild: /* Tiles */ + use Debug Mod to see tile coordinates in-game

2023-09-08T15:39:38Z

Tiles: + use Debug Mod to see tile coordinates in-game

← Older revision		Revision as of 15:39, 8 September 2023
Line 32:		Line 32:

	[[File:Modding - creating an XNB mod - tile coordinates.png]]		[[File:Modding - creating an XNB mod - tile coordinates.png]]

			You can use the {{Nexus mod\|679\|Debug Mode}} mod to see tile coordinates in-game.

	===Positions===		===Positions===