This page documents the (Feat) Multiplayer mod.

This mod adds (some level of) multiplayer support to The Planet Crafter.

Currently, this means the ability to play a world (new or existing save) by two or more players (host, clients).

• Install BepInEx.

• 🔽 Download the akarnokd-FeatMultiplayer.zip for both the host and client.

  • From NexusMods: https://www.nexusmods.com/planetcrafter/mods/29
  • From releases: https://github.com/akarnokd/ThePlanetCrafterMods/releases/latest

• Extract the zip into the BepInEx\plugins directory.

  • Please keep the folder inside the zip so you'll end up with BepInEx\plugins\akarnokd - (Feat) Multiplayer

• Ask the host for its IP address.

  • If running on the same network (both computers behind NAT or a router), have the host start the game, then on the right side, read off the IP address (without the port) on the main screen.

• On the client, open akarnokd.theplanetcraftermods.featmultiplayer.cfg, find [Client], and set HostAddress to the host's IP address. Example:

  [Client]
  
  ## The IP address where the Host can be located from the client.
  # Setting type: String
  # Default value: 
  HostAddress = 192.168.0.100
  

⚠️ The mod is under active development. Things may not work, things may get weird, things may get out of sync.

⚠️ Currently the mod doesn't support encrypted connections between the host and the client.

⚠️ Play with someone you trust. Not everything is validated yet and most client messages are accepted at face value.

⚠️ Backup your save!

⚠️ Patches the vanilla game all over the place so this mod and other mods may break each other.

The game and this mod creates log files in the game's save directory:

%USERPROFILE%\AppData\LocalLow\MijuGames\Planet Crafter

• Player.log (both sides)
• Player_Client_[name].log (client side only)
• Player_Host.log (host side only)

When reporting issues, please post these logs and if possible, post the save of the Host Survival-x.json as well.

The configuration file is in BepInEx\config\akarnokd.theplanetcraftermods.featmultiplayer.cfg

The following shortcuts work only when the player is not in an UI window. Some keys also require holding the Accessibility Key (default CTRL, vanilla settings):

• Host a co-op world by using one of the (existing or new) saves.
• Join a co-op world (up to 25 players, limited to 8 by default).
• The host world remembers the backpack and equipment of the client.
• See each other on the screen as Astronaut Avatar.
• See each other move around.
• Emote to each other.
• Change coloring of the host and client avatars via config.
• Sync up basic Terraformation status; i.e., grass, water shows for both players.
• Place buildings and items, such as machines, containers, furniture, etc.
• Place doors/windows on buildings
• Crafting
• Mine resources
• Grab items dropped to the ground
• Add and remove items to/from player-built containers
• Items dropped animate on the client side
• Doors open for the other player
• Unlock blueprint microchips; both players receive unlocks
• Set text on containers, labels
• Set colors on beacons
• Interacting with pre-placed chests (blue/golden)
• Terraformation speed
• UPnP port mapping
• Launching rockets by both parties
• See meteor shower and impacts on both sides
• Accessing machine inventories
• Asteroid resources syncing
• Grabbing vegetables or algae
• Seeing the same trees grow
• Sync of day-night cycle
• Sync environmental effects (storms, rains, etc)
• Equipping and unequipping equipment (client)
• Deconstructing on the client
• Game mode sync (chill, standard, intense, etc)
• Dying and death chests (standard only)
• Story elements (messages)
• See each other's flashlights
• Terrain greening upon joining the host
• Shredding items
• Recycling items
• DNA Manipulator
• Picking up larvae

• Story events (should trigger meteor events, but never got that far in testing).
• Spawning of special larvae
• The new machines of 0.5.005 (I can't even name them, sorry).

• No jetpack effects
• Asteroid rocks not in sync or not visible
• Sky backdrop sync (moons can look out of phase)

👀 See also: known issues.

Depending on what other mods do to the game, some of them may or may not work properly, at all, or even break this mod. See the sections below for working, non-working and unknown mods.

ℹ️ All sorts of mods can be found here:

• https://planet-crafter.fandom.com/wiki/Modding#Current_Mods
• https://www.nexusmods.com/planetcrafter/mods/

Legend:

• 🌵 works, but some action needs to be taken
• 🆗 works, can be on either or both host and client
• 👻 ghost only

• ¹ Detects the multiplayer mod and disables itself on the client in multiplayer games.
• ² Install on both the host and the client. Ensure their configs match on all sides.
• ³ Spawning items doesn't last on the client because the host will delete such objects.

Legend:

• 🌵 doesn't work on its own but there might be a workaround
• ⛔ doesn't work at all and can't be fixed from this end

• ¹ May work when the (Cheat) Machine Remote Deposit mod of mine is also installed.
• ² Runs with its own state and bypasses the vanilla day-night cycle.
• ³ Dying on the client may not work properly, free crafting might not work.
• ⁴ Conflicting overrides (TryToCraftInWorld, AddItemInEquipment, RemoveItemFromEquipment).
• ⁵ Creates objects on the client (CheckForNearbyMinables).
• ⁶ Very likely conflicting overrides (Asteroid_CreateImpact_Patch).
• ⁷ Conflicting overrides; the host has to deduce materials.
• ⁸ Creates objects on the client (WorldObjectsHandler.CreateXXX use).
• ⁹ Modifies inventory size on the client, patches equipment change callbacks (not used on client).
• ¹⁰ Quickload borks the gamestate and network state on both host or client.
• ¹¹ Conflicting overrides.

Anything not listed in the previous two sections not yet tested with this mod.

I haven't decided about these yet.

• Ingame chat.
• Expose message sending and receiving via API to mods.

Yes.

It does as of version 0.2.0.0

We don't have a full player model and I couldn't get anything other than these flat-images to work.

There could be a problem reaching your nearby router or NAT device, it doesn't support UPnP, or you are not behind NAT/router. If your router does support UPnP, you may need to manually add port mapping in the device's setup.

The mod specifies a public API that can be used for

• detecting the current mode (singleplayer or multiplayer),
• creating and processing custom messages,
• sending standard objects as messages,
• retrieving client backpack and equipment inventories.

They are defined as delegate fields on the FeatMultiplayer.Plugin class to avoid paying the cost of reflective method calls for softly-depending mods.

Also the delegates use standard types only so that other mods don't have to depend on the binary/dll of the multiplayer mod for custom types.

First of all, a third party mod should define a (soft) dependency on this mod via the BepInDepencency annotation:

FeatMultiplayerApi.cs

I recommend taking the class by source and using it in your project so it doesn't need a hard dependency on the multiplayer mod's dll.

FeatMultiplayerApi mApi = FeatMultiplayerApi.Create();

if (mApi.IsAvailable()) {
    Logger.LogInfo("Multiplayer mod found!");

    Logger.LogInfo("Current state: " + mApi.GetState());
}

using BepInEx;

[BepInDependency(modFeatMultiplayerGuid, BepInDependency.DependencyFlags.SoftDependency)]
class SomePlugin : BaseUnityPlugin {

    const string modFeatMultiplayerGuid 
         = "akarnokd.theplanetcraftermods.featmultiplayer";

}

(I recommend using a const string for this as we'll need the mod's Guid next.)

Next, in preferably the Awake method, locate the the multiplayer mod's plugin object, and read off the fields starting with api.

using BepInEx.Bootstrap;

private void Awake() 
{

    if (Chainloader.PluginInfos.TryGetValue(
            modFeatMultiplayerGuid, out BepInEx.PluginInfo pi)) 
    {

        Func<string> apiGetMultiplayerMode = GetApi(pi, "apiGetMultiplayerMode");

        Func<string, int> apiCountByGroupId = GetApi(pi, "apiCountByGroupId");

        Action<Func<int, string, ConcurrentQueue<object>, bool>> apiAddMessageParser
              = GetApi(pi, "apiAddMessageParser");

        Action<Func<object, bool>> apiAddMessageReceiver
              = GetApi(pi, "apiAddMessageReceiver");

        Action<int, object> apiSend = GetApi(pi, "apiSend");

        Action<int> apiSignal = GetApi(pi, "apiSignal");

        Action<int, WorldObject> apiSendWorldObject = GetApi(pi, "apiSendWorldObject");

        Action<object, Action<object>> apiSuppressInventoryChangeWhile
              = GetApi(pi, "apiSuppressInventoryChangeWhile");

        Func<int, Inventory> apiGetClientBackpack
              = GetApi(pi, "apiGetClientBackpack");

        Func<int, Inventory> apiGetClientEquipment
              = GetApi(pi, "apiGetClientEquipment");
    }   

    // For convenience
    static T GetApi<T>(BepInEx.PluginInfo pi, string name) 
    {
        return (T)AccessTools.Field(pi.Instance.GetType(), name).GetValue(null);
    }
}

Of course, put the values into a (static) field inside your plugin.

Returns the current mode in string format: MainMenu, SinglePlayer, CoopHost or CoopClient.

Usage suggestion: call it in patched methods to check if multiplayer-specific behavior is necessary.

switch (apiGetMultiplayerMode()) 
{
    case "CoopHost": 
    {
        // Custom host behavior
        break;
    }
    case "CoopClient":
    {
        // Custom client behavior
        break;
    }
}

Returns the count of existing WorldObject under a specific group identifier string.

This is more effective than counting them via WorldObjectsHandler.GetAllWorldObjects() as the multiplayer mod already tracks these counts.

int biomassRockets = apiCountByGroupId("RocketBiomass1");

Registers a Func object that will be called when a non-standard message is parsed for a client on the background thread.

This function will receive the client identifier, the raw message string and a queue to talk to the UI thread. The function should return true if it successfully identified and parsed the message so no other parsers need to be tried.

🚫 Multi-client is currently not supported so the clientId parameter is ignored.

// register the method
apiAddMessageParser(ParseMyMessage);

// the custom object parsed
class MyMessage {
    int clientId;
    string content;
}

// the parser
static bool ParseMyMessage(int clientId, string str, ConcurrentQueue<object> queue) {
    if (str.StartsWith("MyMessage=")) 
    {
        queue.Enqueue(new MyMessage() 
        {
            clientId = clientId,
            content = str.Substring(10)
        });
        return true;
    }
    return false;
}

Registers a Func that will receive the non-standard parsed message object and perform the necessary actions on the UI thread.

This function will receive the parsed message object and should return true if it successfully processed the message.

// register the method
apiAddMessageReceiver(ReceiveMyMessage);

// the receiver
static bool ReceiveMyMessage(object obj)
{
    if (obj is MyMessage myMessage) {
        MijuTools.Managers.GetManager<BaseHudHandler>()
            .DisplayCursorText("", 3f, myMessage.content);
        return true;
    }
    return false;
}

Queues up an object to be sent to a particular or all clients.

The object should implement ToString in a way that can be identified by a parser on the other side.

⚠️ The only requirement is that the string returned by ToString does not accidentally contain the newline \n character as it is used to identify the boundaries of messages.

ℹ️ In CoopClient mode, the clientId parameter should be zero, indicating the target is the host. In CoopHost mode, a clientId of zero means broadcast to all clients; non-zero targets a specific client.

🚫 Multi-client is currently not supported so the clientId parameter is ignored.

ℹ️ The string conversion will happen on the background thread.

ℹ️ The message is only queued and may not be sent immediately. Use the apiSignal to send it out over the network immediately.

ℹ️ To send a WorldObject, use apiSendWorldObject.

int clientId = 0; // all clients or to the host.
apiSend(clientId, new MyMessageToSend() { content = "Hello world!" });

class MyMessageToSend {
    string content;
    public override string ToString()
    {
        return "MyMessage=" + content + "\n";
    }
}

You can also create the string upfront and send it directly:

apiSend(0, "MyMessage=Hello World!\n");

Signals the network stack to send out any queued-up messages immediately.

Usually this should be called right after an apiSend call.

🚫 Multi-client is currently not supported so the clientId parameter is ignored.

apiSend(0, "MyMessage=Hello World!\n");

apiSignal(0);

Sends a WorldObject out immediately to the target client.

🚫 Multi-client is currently not supported so the clientId parameter is ignored.

ℹ️ there is no need to call apiSignal after this method.

using SpaceCraft;

Group group = GroupsHandler.GetGroupViaId("Iron");
WorldObject wo = WorldObjectsHandler.CreateNewWorldObject(group, 0);

apiSendWorldObject(wo);

Allows performing an action and not send out the related inventory change messages.

It takes an object and an action, which will receive the former object when executing.

Inventory inventory = InventoriesHandler.GetInventoryById(1);
apiSuppressInventoryChangeWhile(inventory, AddToInventory);

static void AddToInventory(object inv) 
{
    var inventory = inv as Inventory;

    Group group = GroupsHandler.GetGroupViaId("Iron");
    WorldObject wo = WorldObjectsHandler.CreateNewWorldObject(group, 0);
    apiSendWorldObject(wo);

    inventory.AddItem(wo);
}

On the host, it returns the given client's shadow backpack inventory, or null if not present.

Use it to put items into the client's inventory.

🚫 Multi-client is currently not supported so the clientId parameter is ignored.

Inventory inv = apiGetClientBackpack(1);
if (inv != null) 
{
    apiSuppressInventoryChangeWhile(inventory, AddToInventory);
}

On the host, it returns the given client's shadow equipment inventory, or null if not present.

Use it to put equipment into the client's equipment slots.

🚫 Multi-client is currently not supported so the clientId parameter is ignored.

Inventory inv = apiGetClientEquipment(1);
if (inv != null) 
{
    Group group = GroupsHandler.GetGroupViaId("Backpack1");
    WorldObject wo = WorldObjectsHandler.CreateNewWorldObject(group, 0);
    apiSendWorldObject(wo);

    inv.AddItem(wo);
}

Host only. Sends the entire inventory object to the client, including its size and content.

ℹ️ The inventory gets automatically created on the client if it didn't exist.

🚫 Multi-client is currently not supported so the clientId parameter is ignored.

ℹ️ The message is only queued and may not be sent immediately. Use the apiSignal to send it out over the network immediately.

Inventory inv = apiGetClientEquipment(1);

inv.GetInsideWorldObjects().Clear();
inv.SetSize(6);

apiSendInventory(1, inv);
apiSignal(1);