Difference between revisions of "Modding:Modder Guide/Game Fundamentals"
Pathoschild (talk | contribs) (+ modder guide header) |
Pathoschild (talk | contribs) (+ tiles and positions) |
||
Line 3: | Line 3: | ||
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]]. | ||
− | == | + | ==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: | ||
+ | [[File:Modding - creating an XNB mod - tile coordinates.png]] | ||
+ | |||
+ | ===Positions=== | ||
+ | The game uses three related coordinate systems: | ||
+ | * Things placed in the world have a ''[[#Tiles|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 <tt>Game1.tileSize</tt>; divide by <tt>Game1.tileSize</tt> 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 <tt>Game1.viewport.X</tt> and <tt>Game1.viewport.Y</tt>. | ||
+ | |||
===Net fields=== | ===Net fields=== | ||
{{upcoming|1.3}} | {{upcoming|1.3}} |
Revision as of 23:55, 1 June 2018
- Get started
- Game fundamentals
- Test & troubleshoot
- Release
- API reference
- Basic SMAPI APIs:
- Advanced SMAPI APIs:
- Specific guides
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.
Net fields can implicitly convert to their underlying value type (like bool x = new NetBool(true)
), but their conversion rules can be counterintuitive and error-prone. For example, item?.category == null && item?.category != null
can both be true at once. Always avoid implicit casts to minimise bugs. Instead, access the underlying value using .Value (or .Pairs on a net dictionary):
NetString str = new NetString("bar"); if (str.Value == "bar") // true
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. |