Modding:Modder Guide/Game Fundamentals

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

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

Concepts

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:

Positions

The game uses three related coordinate systems:

• Things placed in the world have a tile position, relative to the top-left corner of the map.
• Things in the world may also have an absolute pixel position, relative to the top-left corner of the map. To convert a tile coordinate to a pixel coordinate, multiply it by Game1.tileSize; divide by Game1.tileSize for the reverse.
• Items are usually drawn on the screen using a screen pixel position, relative to the top-left corner of the visible screen. To convert an absolute pixel coordinate to a screen coordinate, subtract it from Game1.viewport.X and Game1.viewport.Y.

Net fields

A 'net type' is any of several classes which Stardew Valley uses to sync data between players, named for the Net prefix in their name. A net type can represent a simple value 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). Never implicitly case net fields to minimise bugs; instead, access the underlying value directly. Here's how to use 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).
NetPointDictionary<TValue, TNetValue>	Maps Point keys to instances of TValue (the underlying value type) and TNetValue (the synchronised net type). You can iterate key/value pairs like foreach (KeyValuePair<Point, TValue> pair in field.Pairs).
NetVector2Dictionary<TValue, TNetValue>	Maps 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<Vector2, TValue> pair in field.Pairs).

The build config NuGet package should detect most implicit conversions and show an appropriate build warning.

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	purpose
Game1.player	The current player.
Game1.currentLocation	The game location containing the current player. For a non-main player, may be null when transitioning between locations.
Game1.locations	All locations in the game. For a non-main player, use SMAPI's GetActiveLocations method instead.
Game1.timeOfDay Game1.dayOfMonth Game1.currentSeason Game1.year	The current time, day, season, and year. See also SMAPI's date utility.
Game1.itemsToShip	The items in the shipping bin.
Game1.activeClickableMenu	The modal menu being displayed. Creating an IClickableMenu subclass and assigning an instance to this field will display it.

← Troubleshooting

SMAPI Reference →