105,831
edits
Changes
Modding:Modder Guide/APIs/Multiplayer (view source)
Revision as of 00:40, 8 November 2021
, 00:40, 8 November 2021Text replacement - "''e.g.''," to "''e.g.,''"
===Get connected player info===
===Get connected player info===
You can see basic info about other players connected to the same server using the <tt>GetConnectedPlayer(playerID)</tt> and <tt>GetConnectedPlayers()</tt> methods. This is available immediately when the player connects (before the game even approves the connection). Most of the information is only available for players who are running SMAPI too. You can access these fields for each player:
You can see basic info about other players connected to the same server using the <samp>GetConnectedPlayer(playerID)</samp> and <samp>GetConnectedPlayers()</samp> methods. This is available immediately when the player connects (before the game even approves the connection). Most of the information is only available for players who are running SMAPI too. You can access these fields for each player:
{| class="wikitable"
{| class="wikitable"
|-
|-
! description
! description
|-
|-
| <tt>PlayerID</tt>
| <samp>PlayerID</samp>
| <tt>long</tt>
| <samp>long</samp>
| The player's unique multiplayer ID, which you can pass to game methods and fields that expect a unique player ID.
| The player's unique multiplayer ID, which you can pass to game methods and fields that expect a unique player ID.
|-
|-
| <tt>IsHost</tt>
| <samp>IsHost</samp>
| <tt>bool</tt>
| <samp>bool</samp>
| True if this player is hosting the server; false if they're a farmhand.
| True if this player is hosting the server; false if they're a farmhand.
|-
|-
| <tt>IsSplitScreen</tt>
| <samp>IsSplitScreen</samp>
| <tt>bool</tt>
| <samp>bool</samp>
| True if the player is running on the same computer in split-screen mode.
|-
|-
| <tt>HasSmapi</tt>
| <samp>HasSmapi</samp>
| <tt>bool</tt>
| <samp>bool</samp>
| Whether this player has SMAPI installed.
| Whether this player has SMAPI installed.
|-
|-
| <tt>Platform</tt>
| <samp>Platform</samp>
| <tt>GamePlatform</tt>
| <samp>GamePlatform</samp>
| (Requires SMAPI.) The player's operating system as a <tt>GamePlatform</tt> enum (one of <tt>Linux</tt>, <tt>Mac</tt>, or <tt>Windows</tt>).
| (Requires SMAPI.) The player's operating system as a <samp>GamePlatform</samp> enum (one of <samp>Linux</samp>, <samp>Mac</samp>, or <samp>Windows</samp>).
|-
|-
| <tt>GameVersion</tt>
| <samp>GameVersion</samp>
| <tt>ISemanticVersion</tt>
| <samp>ISemanticVersion</samp>
| (Requires SMAPI.) The version of the game they have installed (like {{#tag:tt|{{version|link=0}}}}).
| (Requires SMAPI.) The version of the game they have installed (like {{#tag:tt|{{version|link=0}}}}).
|-
|-
| <tt>ApiVersion</tt>
| <samp>ApiVersion</samp>
| <tt>ISemanticVersion</tt>
| <samp>ISemanticVersion</samp>
| (Requires SMAPI.) The version of SMAPI they have installed (like <tt>2.11</tt>).
| (Requires SMAPI.) The version of SMAPI they have installed (like <samp>2.11</samp>).
|-
|-
| <tt>Mods</tt>
| <samp>Mods</samp>
| <tt>IEnumerable<IMultiplayerPeerMod></tt>
| <samp>IEnumerable<IMultiplayerPeerMod></samp>
| (Requires SMAPI.) The mods they have installed. Each mod includes the name, unique ID, and version.
| (Requires SMAPI.) The mods they have installed. Each mod includes the name, unique ID, and version. This is null if the other player doesn't have SMAPI, or an empty list if they have SMAPI but no mods.
|-
|-
| <tt>ScreenID</tt>
| <samp>ScreenID</samp>
| <tt>int?</tt>
| <samp>int?</samp>
| The player's screen ID in split-screen mode, if <samp>IsSplitScreen</samp> is true.
|-
|-
| <tt>GetMod(id)</tt>
| <samp>GetMod(id)</samp>
| ''method'' returns <tt>IMultiplayerPeerMod</tt>
| ''method'' returns <samp>IMultiplayerPeerMod</samp>
| (Requires SMAPI.) A method which returns the mod with the given mod ID using the same case-insensitivity rules as SMAPI, if available. For example, this can be used to check if a mod is installed: <code>if (peer.GetMod("Pathoschild.ContentPatcher") != null)</code>.
| (Requires SMAPI.) A method which returns the mod with the given mod ID using the same case-insensitivity rules as SMAPI, if available. For example, this can be used to check if a mod is installed: <code>if (peer.GetMod("Pathoschild.ContentPatcher") != null)</code>.
|}
|}
===Send messages===
===Send messages===
You can send a message to mods on all connected computers (including the current one) using the <tt>SendMessage</tt> method. The destination can range from very narrow (e.g. one mod on one connected computer) to very broad (all mods on all computers). The message won't be sent back to the mod instance that sent it, but it can be sent to the same mod on other computers.
You can send a message to mods on all connected computers (including the current one) using the <samp>SendMessage</samp> method. The destination can range from very narrow (''e.g.,'' one mod on one connected computer) to very broad (all mods on all computers). The message won't be sent back to the mod instance that sent it, but it can be sent to the same mod on other computers.
When sending a message, you must specify three things:
When sending a message, you must specify three things:
* A data model, which contains the data you want to send. This can be a simple value (like a number or string), or a class instance. When using a class instance with custom constructors, make sure it has a default constructor too.
* The data you want to send. This can be a simple value (like a number or string), or a class instance. When using a class instance with custom constructors, make sure it has a default constructor too.
* A message type, so the destination mods can know which message it is. This doesn't need to be globally unique, since mods should check the originating mod ID.
* A message type, so the destination mods can know which message it is. This doesn't need to be globally unique, since mods should check the originating mod ID.
* Who should receive the message. You can specify any combination of player IDs and/or mod IDs. By default, the message is sent to all mods and players.
* Who should receive the message. You can specify any combination of player IDs and/or mod IDs. By default, the message is sent to all mods and players.
===Receive messages===
===Receive messages===
You can receive messages by listening to the <tt>helper.Events.Multiplayer.ModMessageReceived</tt> [[Modding:Modder Guide/APIs/Events|event]]. The event arguments specify who sent the message, and let you read the message into a matching data model.
You can receive messages by listening to the <samp>helper.Events.Multiplayer.ModMessageReceived</samp> [[Modding:Modder Guide/APIs/Events|event]]. The event arguments specify who sent the message, and let you read the message into a matching data model.
For example:
For example:
==Per-screen data==
==Per-screen data==
[[Multiplayer|Split-screen multiplayer]] swaps the entire game state between each player, so each mod runs across every player. For example, with four local players the [[Modding:Modder Guide/APIs/Events#GameLoop.UpdateTicked|<tt>UpdateTicked</tt>]] event would be raised four times per tick. The game manages its own state automatically (e.g. <tt>Game1.activeClickableMenu</tt>), but if your mod stores info in its own fields you may need to handle those yourself.
[[Multiplayer|Split-screen multiplayer]] swaps the entire game state between each player, so each mod runs across every player. For example, with four local players the [[Modding:Modder Guide/APIs/Events#GameLoop.UpdateTicked|<samp>UpdateTicked</samp>]] event would be raised four times per tick. The game manages its own state automatically (''e.g.,'' <samp>Game1.activeClickableMenu</samp>), but if your mod stores info in its own fields you may need to handle those yourself.
SMAPI provides <code>PerScreen<T></code> to make that easy. You use it by creating '''readonly''' fields for your values (which can be any value from <tt>int</tt> to entire class instances):
SMAPI provides <code>PerScreen<T></code> to make that easy. You use it by creating '''readonly''' fields for your values (which can be any value from <samp>int</samp> to entire class instances):
<syntaxhighlight lang="C#">
<syntaxhighlight lang="C#">
private readonly PerScreen<int> LastPlayerId = new PerScreen<int>(); // defaults to 0
private readonly PerScreen<int> LastPlayerId = new PerScreen<int>(); // defaults to 0
</syntaxhighlight>
</syntaxhighlight>
'''Tip:''' you should almost always mark a per-screen field <code>readonly</code>. Overwriting the entire field (instead of setting the <tt>Value</tt> property) will clear the data for all players, instead of setting it for the current one.
'''Tip:''' you should almost always mark a per-screen field <code>readonly</code>. Overwriting the entire field (instead of setting the <samp>Value</samp> property) will clear the data for all players, instead of setting it for the current one.
==See also==
==See also==
* [[Modding:Modder Guide/APIs/Events#Multiplayer|Multiplayer events]]
* [[Modding:Modder Guide/APIs/Events#Multiplayer|Multiplayer events]]