Modding:Modder Guide/Game Fundamentals

From Stardew Valley Wiki
< Modding:Modder Guide
Revision as of 16:06, 15 September 2018 by Pathoschild (talk | contribs) (→‎Positions: add conversion formulas, reformat for readability)
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.

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: Modding - creating an XNB mod - tile coordinates.png

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:

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

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).

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().shippingBin 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 (private) 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=75381"