Modding:Modder Guide/Game Fundamentals

From Stardew Valley Wiki
Jump to navigation Jump to search

Creating SMAPI mods SMAPI mascot.png

← Modding:Index

This page explains some of the Stardew Valley fundamentals that are useful for modders. See also Modding:Common tasks.

General concepts

Time format

The in-game time of day is tracked using a version of 24-hour format informally called "26-hour time", measured in 10-minute intervals. This is the format used by Game1.timeOfDay in a C# mod or {{Time}} in a Content Patcher pack.

Sample times:

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:

Modding - creating an XNB mod - tile coordinates.png

You can use the Debug Mode mod to see tile coordinates in-game.

Positions

The game uses three related coordinate systems:

coordinate system relative to notes
tile position top-left corner of the map measured in tiles; used when placing things on the map (e.g., location.Objects 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):

conversion formula
absolute → screen x - Game1.viewport.X, y - Game1.viewport.Y
absolute → tile x / Game1.tileSize, y / Game1.tileSize
screen → absolute x + Game1.viewport.X, y + Game1.viewport.Y
screen → tile (x + Game1.viewport.X) / Game1.tileSize, (y + Game1.viewport.Y) / Game1.tileSize
tile → absolute x * Game1.tileSize, y * Game1.tileSize
tile → screen (x * Game1.tileSize) - Game1.viewport.X, (y * Game1.tileSize) - Game1.viewport.Y

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:

min zoom level (75%) max zoom level (200%)
Zoom level 75.png Zoom level 200.png
Effect on SMAPI mods
In game code, this is represented by the Game1.options.zoomLevel 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 position * (1f / Game1.options.zoomLevel) if needed.

UI scaling

The player can scale the UI between 75% and 150%, separately from and alongside the 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:

min UI scale (75%) max UI scale (150%)
UI scale 75.png UI scale 150.png
Effect on SMAPI mods
The game has two distinct scaling modes depending on the context: UI mode and non-UI mode. You can check Game1.uiMode 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:
context scaling mode which applies
clickable menus UI mode (usually)
HUD elements UI mode
RenderingActiveMenu
RenderedActiveMenu 		UI mode
Rendering
Rendered 		depends on the context; check Game1.uiMode
draw 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:
Game1.game1.InUIMode(() =>
{
   // your UI draw code here
});
In UI mode, you should usually replace Game1.viewport with Game1.uiViewport. 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 Utility.ModifyCoordinatesForUIScale and Utility.ModifyCoordinatesFromUIScale.
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

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 Net prefix in their type names. Net types can represent simple values like NetBool, or complex values like NetFieldDictionary. The game will regularly collect all the net fields reachable from Game1.netWorldState 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 bool x = new NetBool(true)), their conversion rules are counterintuitive and error-prone (e.g., item?.category == null && item?.category != null 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:

net type description
NetBool
NetColor
NetFloat
NetInt
NetPoint
NetString 		A simple synchronised value. Access the value using field.Value.
NetCollection<T>
NetList<T>
NetObjectList<T> 		A list of T values. This implements the standard interfaces like IEnumerable<T> and IList<T>, so you can iterate it directly like foreach (T value in field).
NetLongDictionary<TValue, TNetValue>
NetPointDictionary<TValue, TNetValue>
NetVector2Dictionary<TValue, TNetValue> 		Maps Long, Point, or Vector2 keys to instances of TValue (the underlying value type) and TNetValue (the synchronised net type). You can iterate key/value pairs like foreach (KeyValuePair<Long, TValue> pair in field.Pairs) (replacing Long with Point or Vector2 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 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.

This has some significant implications for C# mods:

  • The Game1.locations 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 Game1.getCharacterByName) 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 currentLocation field while they're between locations.

You can check whether a location is active using its IsActiveLocation method: 

foreach (GameLocation location in Game1.locations)
{
    if (!location.IsActiveLocation())
        continue; // shadow location

    ...
}

Main classes

Game1

Game1 is the game's core logic. Most of the game state is tracked through this class. Here are some of the most useful fields:

field type purpose
Game1.player Farmer The current player.
Game1.currentLocation GameLocation The game location containing the current player. For a non-main player, may be null when transitioning between locations.
Game1.locations IList<GameLocation> All locations in the game. For a non-main player, use SMAPI's GetActiveLocations method instead.
Game1.timeOfDay
Game1.dayOfMonth
Game1.currentSeason
Game1.year 		int
int
string
int 		The current time, day, season, and year. See also SMAPI's date utility.
Game1.itemsToShip IList<Item> Do not use (this is part of the save logic). See Game1.getFarm().getShippingBin(Farmer) instead.
Game1.activeClickableMenu IClickableMenu The modal menu being displayed. Creating an IClickableMenu subclass and assigning an instance to this field will display it.

GameLocation et al

  • GameLocation 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:
    field type purpose
    Name string The unique name for this location. (This isn't unique for constructed building interiors like cabins; see uniqueName instead.)
    IsFarm bool Whether this is a farm, where crops can be planted.
    IsGreenhouse bool Whether this is a greenhouse, where crops can be planted and grown all year.
    IsOutdoors bool Whether the location is outdoors (as opposed to a greenhouse, building, etc).
    characters NetCollection of NPC The villagers, pets, horses, and monsters in the location.
    critters List of Critter The temporary birds, squirrels, or other critters in the location.
    debris NetCollection of Debris The floating items in the location.
    farmers FarmerCollection The players in the location.
    Objects OverlaidDictionary The placed fences, crafting machines, and other objects in the current location. (OverlaidDictionary is basically a NetVector2Dictionary with logic added to show certain quest items over pre-existing objects.)
    terrainFeatures NetVector2Dictionary of TerrainFeature 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.
    waterTiles bool[,] A multi-dimensional array which indicates whether each tile on the map is a lake/river tile. For example, if (location.waterTiles[10, 20]) checks the tile at position (10, 20).
  • BuildableGameLocation is a subclass of GameLocation for locations where players can construct buildings. In the vanilla game, only the farm is a buildable location. Here are the most useful fields:
    field type purpose
    buildings NetCollection of Building The buildings in the location.
  • Farm is a subclass of both GameLocation and BuildableGameLocation for locations where the player can have animals and grow crops. In the vanilla, there's only one farm location (accessed using Game1.getFarm()). Here are its most useful properties:
    field type purpose
    animals NetLongDictionary of FarmAnimal The farm animals currently in the location.
    resourceClumps NetCollection of ResourceClump The giant crops, large stumps, boulders, and meteorites in the location.
    piecesOfHay NetInt The amount of hay stored in silos.
    shippingBin NetCollection of Item The items in the shipping bin.
  • There are a number of subclasses for specific location (like AdventureGuild) which have fields useful for specific cases.
Retrieved from "https://stardewvalleywiki.com/mediawiki/index.php?title=Modding:Modder_Guide/Game_Fundamentals&oldid=164768"