Changes

Jump to navigation Jump to search

Modding:Modder Guide/Game Fundamentals (view source)

Revision as of 18:06, 6 April 2024

12,686 bytes added ,  6 April
remove {{upcoming|1.6}}
Line 1: Line 1: −
←[[Modding:Index|Index]]
+
{{../header}}
    
This page explains some of the Stardew Valley fundamentals that are useful for modders. See also [[Modding:Common tasks]].
 
This page explains some of the Stardew Valley fundamentals that are useful for modders. See also [[Modding:Common tasks]].
   −
==Data structures==
+
==General concepts==
 +
===Time format===
 +
The in-game time of day is tracked using a version of [[wikipedia:24-hour clock|24-hour format]] informally called "26-hour time", measured in 10-minute intervals. This is the format used by <samp>Game1.timeOfDay</samp> in a [[Modding:Modder Guide/Get Started|C# mod]] or <samp><nowiki>{{Time}}</nowiki></samp> in a [[Modding:Content Patcher|Content Patcher pack]].
 +
 
 +
Sample times:
 +
{| class="wikitable"
 +
|-
 +
! time value
 +
! display text
 +
|-
 +
| 600
 +
| 6:00 am
 +
|-
 +
| 1250
 +
| 12:50 am
 +
|-
 +
| 1300
 +
| 1:00 pm
 +
|-
 +
| 2600
 +
| 2:00 am (before sleeping)
 +
|}
 +
 
 +
The internal time will continue incrementing forever until you sleep (e.g. 6am the next day would be 3000 in that case).
 +
 
 +
===Tiles===
 +
The world is laid out as a grid of ''tiles''. Each tile has an (x, y) coordinate which represents its position on the map, where (0, 0) is the top-left tile. The ''x'' value increases towards the right, and ''y'' increases downwards. For example:
 +
 
 +
[[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===
 +
The game uses three related coordinate systems:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! coordinate system
 +
! relative to
 +
! notes
 +
|-
 +
| tile position
 +
| top-left corner of the map
 +
| measured in [[#Tiles|tiles]]; used when placing things on the map (''e.g.,'' <samp>location.Objects</samp> uses tile positions).
 +
|-
 +
| absolute position
 +
| top-left corner of the map
 +
| measured in pixels; used when more granular measurements are needed (''e.g.,'' NPC movement).
 +
|-
 +
| screen position
 +
| top-left corner of the visible screen
 +
| measured in pixels; used when drawing to the screen.
 +
|}
 +
 
 +
Here's how to convert between them (there are also helpful methods in Utility for some of these):
 +
 
 +
{| class="wikitable"
 +
|-
 +
!colspan="3"| conversion
 +
! formula
 +
|-
 +
| absolute || → || screen
 +
| <code>x - Game1.viewport.X, y - Game1.viewport.Y</code>
 +
|-
 +
| absolute || → || tile
 +
| <code>x / Game1.tileSize, y / Game1.tileSize</code>
 +
|-
 +
| screen || → || absolute
 +
| <code>x + Game1.viewport.X, y + Game1.viewport.Y</code>
 +
|-
 +
| screen || → || tile
 +
| <code>(x + Game1.viewport.X) / Game1.tileSize, (y + Game1.viewport.Y) / Game1.tileSize</code>
 +
|-
 +
| tile || → || absolute
 +
| <code>x * Game1.tileSize, y * Game1.tileSize</code>
 +
|-
 +
| tile || → || screen
 +
| <code>(x * Game1.tileSize) - Game1.viewport.X, (y * Game1.tileSize) - Game1.viewport.Y</code>
 +
|}
 +
 
 +
===Zoom level===
 +
The player can set an in-game zoom level between 75% and 200%, which adjusted the size of all pixels shown on the screen. For example, here's a player with the same window size at different zoom levels:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! min zoom level (75%)
 +
! max zoom level (200%)
 +
|-
 +
| [[File:Zoom level 75.png|300px]]
 +
| [[File:Zoom level 200.png|300px]]
 +
|}
 +
 
 +
; Effect on SMAPI mods
 +
: In game code, this is represented by the <samp>Game1.options.zoomLevel</samp> field. Coordinates are generally adjusted for zoom level automatically, so you rarely need to account for this; but you can convert an unadjusted coordinate using <code>position * (1f / Game1.options.zoomLevel)</code> if needed.
 +
 
 +
===UI scaling===
 +
The player can scale the UI between 75% and 150%, separately from and alongside the [[#Zoom level|zoom level]]. That adjusts the size of pixels shown on the screen for UI elements only. For example, here's a player with the same window size at different UI scaling levels:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! min UI scale (75%)
 +
! max UI scale (150%)
 +
|-
 +
| [[File:UI scale 75.png|300px]]
 +
| [[File:UI scale 150.png|300px]]
 +
|}
 +
 
 +
; Effect on SMAPI mods
 +
: The game has two distinct scaling modes depending on the context: ''UI mode'' and ''non-UI mode''. You can check <samp>Game1.uiMode</samp> to know which mode is active. You should be careful not to mix UI and non-UI coordinates to avoid tricky calculations; for example, do all your work in one coordinate system and then convert them once.
 +
 
 +
: A quick reference of common scenarios:
 +
: {| class="wikitable"
 +
|-
 +
! context
 +
! scaling mode which applies
 +
|-
 +
| clickable menus
 +
| UI mode (usually)
 +
|-
 +
| HUD elements
 +
| UI mode
 +
|-
 +
| [[Modding:Modder Guide/APIs/Events#Display.RenderingActiveMenu|<samp>RenderingActiveMenu</samp>]]<br />[[Modding:Modder Guide/APIs/Events#Display.RenderedActiveMenu|<samp>RenderedActiveMenu</samp>]]
 +
| UI mode
 +
|-
 +
| [[Modding:Modder Guide/APIs/Events#Display.Rendering|<samp>Rendering</samp>]]<br />[[Modding:Modder Guide/APIs/Events#Display.Rendering|<samp>Rendered</samp>]]
 +
| depends on the context; check <samp>Game1.uiMode</samp>
 +
|-
 +
| <samp>draw</samp> method for world objects
 +
| non-UI mode
 +
|-
 +
| tile (non-pixel) coordinates
 +
| not affected by UI scaling
 +
|}
 +
 
 +
: If you need to draw UI when the game isn't in UI mode, you can explicitly set UI scaling mode:
 +
: <syntaxhighlight lang="c#">Game1.game1.InUIMode(() =>
 +
{
 +
  // your UI draw code here
 +
});
 +
</syntaxhighlight>
 +
 
 +
: In UI mode, you should usually replace <samp>Game1.viewport</samp> with <samp>Game1.uiViewport</samp>. '''Don't''' do this if you'll adjust the positions for UI scaling separately, since double-conversion will give you incorrect results. You can convert between UI and non-UI coordinates using <samp>Utility.ModifyCoordinatesForUIScale</samp> and <samp>Utility.ModifyCoordinatesFromUIScale</samp>.
 +
 
 +
: 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.
 +
 
 +
==Multiplayer concepts for C# mods==
 
===Net fields===
 
===Net fields===
−
{{upcoming|1.3}}
+
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.
 +
 
 +
Here's how to access the data in some common net types:
 +
{| class="wikitable"
 +
|-
 +
! net type
 +
! description
 +
|-
 +
| <samp>NetBool</samp><br /><samp>NetColor</samp><br /><samp>NetFloat</samp><br /><samp>NetInt</samp><br /><samp>NetPoint</samp><br /><samp>NetString</samp>
 +
| A simple synchronised value. Access the value using <samp>field.Value</samp>.
 +
|-
 +
| <samp>NetCollection&lt;T&gt;</samp><br /><samp>NetList&lt;T&gt;</samp><br /><samp>NetObjectList&lt;T&gt;</samp>
 +
| A list of <samp>T</samp> values. This implements the standard interfaces like [https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.ienumerable-1 <samp>IEnumerable&lt;T&gt;</samp>] and [https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.ilist-1 <samp>IList&lt;T&gt;</samp>], so you can iterate it directly like <code>foreach (T value in field)</code>.
 +
|-
 +
| <samp>NetLongDictionary&lt;TValue, TNetValue&gt;</samp><br /><samp>NetPointDictionary&lt;TValue, TNetValue&gt;</samp><br /><samp>NetVector2Dictionary&lt;TValue, TNetValue&gt;</samp>
 +
| Maps <samp>Long</samp>, <samp>Point</samp>, or <samp>Vector2</samp> keys to instances of <samp>TValue</samp> (the underlying value type) and <samp>TNetValue</samp> (the synchronised net type). You can iterate key/value pairs like <code>foreach (KeyValuePair<Long, TValue> pair in field.Pairs)</code> (replacing <samp>Long</samp> with <samp>Point</samp> or <samp>Vector2</samp> if needed).
 +
|}
 +
 
 +
===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.
   −
A 'net type' is any of several classes which Stardew Valley uses to sync data between players, named for the <code>Net</code> prefix in their name. A net type can represent a simple value like <tt>NetBool</tt>, or complex values like <tt>NetFieldDictionary</tt>. The game will regularly collect all the net fields reachable from <tt>Game1.netWorldState</tt> and sync them with other players. That means that many mod changes will be synchronised automatically in multiplayer.
+
This has some significant implications for C# mods:
 +
* The <samp>Game1.locations</samp> list shows both active and shadow locations. While mods can access the shadow locations, these don't reflect the real data on the server and any changes to them won't be synced to the host.
 +
* There may be duplicate copies of NPCs, horses, etc in the shadow world. Only those in active locations are 'real'.
 +
* Game methods (like <samp>Game1.getCharacterByName</samp>) may not correctly distinguish between the 'real' and 'shadow' copies.
 +
* 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.
   −
Net fields can implicitly convert to their underlying value type (like <code>bool x = new NetBool(true)</code>), but their conversion rules can be counterintuitive and error-prone. For example, <code>item?.category == null && item?.category != null</code> can both be true at once. '''Always avoid implicit casts to minimise bugs.''' Instead, access the underlying value using <tt>.Value</tt> (or <tt>.Pairs</tt> on a net dictionary):
+
You can check whether a location is active using its <samp>IsActiveLocation</samp> method:
−
: <source lang="C#">
+
<syntaxhighlight lang="c#">
−
NetString str = new NetString("bar");
+
foreach (GameLocation location in Game1.locations)
−
if (str.Value == "bar") // true
+
{
−
</source>
+
    if (!location.IsActiveLocation())
 +
        continue; // shadow location
   −
The build config NuGet package should detect most implicit conversions and show an appropriate build warning.
+
    ...
 +
}
 +
</syntaxhighlight>
    
==Main classes==
 
==Main classes==
 
===Game1===
 
===Game1===
−
<tt>Game1</tt> is the game's core logic. Most of the game state is tracked through this class. Here are some of the most useful fields:
+
<samp>Game1</samp> is the game's core logic. Most of the game state is tracked through this class. Here are some of the most useful fields:
    
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
 
! field
 
! field
 +
! type
 
! purpose
 
! purpose
 
|-
 
|-
−
| <tt>Game1.player</tt>
+
| <samp>Game1.player</samp>
 +
| <samp>Farmer</samp>
 
| The current player.
 
| The current player.
 
|-
 
|-
−
| <tt>Game1.currentLocation</tt>
+
| <samp>Game1.currentLocation</samp>
−
| The game location containing the current player. '''For a non-main player, may be <tt>null</tt> when transitioning between locations.'''
+
| <samp>[[#GameLocation|GameLocation]]</samp>
 +
| The game location containing the current player. '''For a non-main player, may be <samp>null</samp> when transitioning between locations.'''
 
|-
 
|-
−
| <tt>Game1.locations</tt>
+
| <samp>Game1.locations</samp>
−
| All locations in the game. '''For a non-main player, use [[Modding:Modder Guide/APIs/Multiplayer#GetActiveLocations|SMAPI's <tt>GetActiveLocations</tt> method]] instead.'''
+
| <samp>IList&lt;[[#GameLocation|GameLocation]]&gt;</samp>
 +
| All locations in the game. '''For a non-main player, use [[Modding:Modder Guide/APIs/Multiplayer#Get_active_locations|SMAPI's <samp>GetActiveLocations</samp> method]] instead.'''
 
|-
 
|-
−
| <tt>Game1.timeOfDay</tt><br /><tt>Game1.dayOfMonth</tt><br /><tt>Game1.currentSeason</tt><br /><tt>Game1.year</tt>
+
| <samp>Game1.timeOfDay</samp><br /><samp>Game1.dayOfMonth</samp><br /><samp>Game1.currentSeason</samp><br /><samp>Game1.year</samp>
 +
| <samp>int</samp><br /><samp>int</samp><br /><samp>string</samp><br /><samp>int</samp>
 
| The current time, day, season, and year. See also [[Modding:Modder Guide/APIs/Utilities#Dates|SMAPI's date utility]].
 
| The current time, day, season, and year. See also [[Modding:Modder Guide/APIs/Utilities#Dates|SMAPI's date utility]].
 
|-
 
|-
−
| <tt>Game1.itemsToShip</tt>
+
| <samp>Game1.itemsToShip</samp>
−
| The items in the shipping bin.
+
| <samp>IList&lt;Item&gt;</samp>
 +
| Do not use (this is part of the save logic). See <samp>Game1.getFarm().getShippingBin(Farmer)</samp> instead.
 
|-
 
|-
−
| <tt>Game1.activeClickableMenu</tt>
+
| <samp>Game1.activeClickableMenu</samp>
−
| The modal menu being displayed. Creating an <tt>IClickableMenu</tt> subclass and assigning an instance to this field will display it.
+
| <samp>IClickableMenu</samp>
 +
| The modal menu being displayed. Creating an <samp>IClickableMenu</samp> subclass and assigning an instance to this field will display it.
 
|}
 
|}
   −
[[Category:Modding]]
+
===<span id="GameLocation"></span>GameLocation et al===
 +
<ul>
 +
<li><samp>GameLocation</samp> represents an in-game location players can visit. Each location has a map (the tile layout), objects, trees, characters, etc. Here are some of the most useful fields for any location:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! type
 +
! purpose
 +
|-
 +
| <samp>Name</samp>
 +
| <samp>string</samp>
 +
| The unique name for this location. (This isn't unique for constructed building interiors like cabins; see <samp>uniqueName</samp> instead.)
 +
|-
 +
| <samp>IsFarm</samp>
 +
| <samp>bool</samp>
 +
| Whether this is a farm, where crops can be planted.
 +
|-
 +
| <samp>IsGreenhouse</samp>
 +
| <samp>bool</samp>
 +
| Whether this is a greenhouse, where crops can be planted and grown all year.
 +
|-
 +
| <samp>IsOutdoors</samp>
 +
| <samp>bool</samp>
 +
| Whether the location is outdoors (as opposed to a greenhouse, building, etc).
 +
|-
 +
| <samp>characters</samp>
 +
| [[#Net fields|<samp>NetCollection</samp>]] of <samp>NPC</samp>
 +
| The villagers, pets, horses, and monsters in the location.
 +
|-
 +
| <samp>critters</samp>
 +
| <samp>List</samp> of <samp>Critter</samp>
 +
| The temporary birds, squirrels, or other critters in the location.
 +
|-
 +
| <samp>debris</samp>
 +
| [[#Net fields|<samp>NetCollection</samp>]] of <samp>Debris</samp>
 +
| The floating items in the location.
 +
|-
 +
| <samp>farmers</samp>
 +
| <samp>FarmerCollection</samp>
 +
| The players in the location.
 +
|-
 +
| <samp>Objects</samp>
 +
| <samp>OverlaidDictionary</samp>
 +
| The placed fences, crafting machines, and other objects in the current location. (<samp>OverlaidDictionary</samp> is basically a [[#Net fields|<samp>NetVector2Dictionary</samp>]] with logic added to show certain quest items over pre-existing objects.)
 +
|-
 +
| <samp>terrainFeatures</samp>
 +
| [[#Net fields|<samp>NetVector2Dictionary</samp>]] of <samp>TerrainFeature</samp>
 +
| The trees, fruit trees, tall grass, tilled dirt (including crops), and flooring in the location. For each pair, the key is their tile position and the value is the terrain feature instance.
 +
|-
 +
| <samp>waterTiles</samp>
 +
| <samp>bool[,]</samp>
 +
| A multi-dimensional array which indicates whether each tile on the map is a lake/river tile. For example, <code>if (location.waterTiles[10, 20])</code> checks the tile at [[#Tiles|position]] (10, 20).
 +
|}</li>
 +
 
 +
<li><samp>BuildableGameLocation</samp> is a subclass of <samp>GameLocation</samp> for locations where players can construct buildings. In the vanilla game, only the farm is a buildable location. Here are the most useful fields:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! type
 +
! purpose
 +
|-
 +
| <samp>buildings</samp>
 +
| [[#Net fields|<samp>NetCollection</samp>]] of <samp>Building</samp>
 +
| The buildings in the location.
 +
|}</li>
 +
 
 +
<li><samp>Farm</samp> is a subclass of both <samp>GameLocation</samp> and <samp>BuildableGameLocation</samp> for locations where the player can have animals and grow crops. In the vanilla, there's only one farm location (accessed using <code>Game1.getFarm()</code>). Here are its most useful properties:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! type
 +
! purpose
 +
|-
 +
| <samp>animals</samp>
 +
| [[#Net fields|<samp>NetLongDictionary</samp>]] of <samp>FarmAnimal</samp>
 +
| The farm animals currently in the location.
 +
|-
 +
| <samp>resourceClumps</samp>
 +
| [[#Net fields|<samp>NetCollection</samp>]] of <samp>ResourceClump</samp>
 +
| The giant crops, large stumps, boulders, and meteorites in the location.
 +
|-
 +
| <samp>piecesOfHay</samp>
 +
| [[#Net fields|<samp>NetInt</samp>]]
 +
| The amount of hay stored in silos.
 +
|-
 +
| <samp>shippingBin</samp>
 +
| [[#Net fields|<samp>NetCollection</samp>]] of <samp>Item</samp>
 +
| The items in the shipping bin.
 +
|}</li>
 +
 
 +
<li>There are a number of subclasses for specific location (like <samp>AdventureGuild</samp>) which have fields useful for specific cases.</li>
 +
</ul>
 +
 
 +
[[es:Modding:Guía del Modder/Fundamentos del juego]]
 +
[[ru:Модификации:Моддер гайд/Основы игры]]
 +
[[zh:模组:制作指南/游戏基本架构]]
Pathoschild
translators
8,404

edits

Retrieved from "https://stardewvalleywiki.com/Special:MobileDiff/70959...164768"

Navigation menu