Networking

Spark's networking layer is an abstraction that routes commands through a provider. In single-player, commands execute locally. In multiplayer, a custom provider can route them to a server. Your game logic stays the same either way.

Architecture

The networking system has three pieces:

1. INetworkProvider: The interface that all providers implement.

2. NetworkProviderBase: An abstract base class with reflection-based command dispatch.

3. LocalNetworkProvider: The default provider for single-player/offline games.

INetworkProvider

public interface INetworkProvider
{
    bool IsServer { get; }
    void ExecuteCommand(ICommand command);
    void RegisterHandler<T>(ICommandHandler<T> handler) where T : ICommand;
}

Member	Description
IsServer	Whether this instance has authority. True in single-player, depends on role in multiplayer.
ExecuteCommand(ICommand)	Dispatches a command to its registered handler.
RegisterHandler<T>(handler)	Associates a handler with a command type.

NetworkProviderBase

The abstract base class stores handlers in a Dictionary<Type, object> and uses reflection to invoke the correct Handle() method when a command is executed:

public abstract class NetworkProviderBase : INetworkProvider
{
    private Dictionary<Type, object> _handlers = new();

    public abstract bool IsServer { get; }

    public void RegisterHandler<T>(ICommandHandler<T> handler) where T : ICommand
    {
        _handlers[typeof(T)] = handler;
    }

    public void ExecuteCommand(ICommand command)
    {
        var commandType = command.GetType();
        if (_handlers.TryGetValue(commandType, out var handler))
        {
            // Reflection-based dispatch to Handle(T command)
            var method = handler.GetType().GetMethod("Handle");
            method.Invoke(handler, new object[] { command });
        }
    }
}

When you create a custom provider, inherit from NetworkProviderBase and override RegisterDefaultHandlers():

public abstract class NetworkProviderBase : INetworkProvider
{
    protected abstract void RegisterDefaultHandlers();
}

LocalNetworkProvider

The default provider used in single-player games. It:

• Auto-registers at BeforeSceneLoad if no other provider is set

• Executes commands immediately and synchronously

• Always reports IsServer => true

• Registers the built-in DragDropCommandHandler

You don't need to do anything to use it. It's set up automatically.

Setting Up a Network Provider

To use a custom provider (for multiplayer), register it before any plugins try to execute commands:

[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
private static void SetupNetworking()
{
    var provider = new MyMultiplayerProvider();
    Spark.SetNetworkProvider(provider);
}

Listen for provider readiness:

Spark.OnNetworkProviderReady += (provider) =>
{
    Debug.Log($"Network provider ready. IsServer: {provider.IsServer}");
};

Implementing a Custom Network Provider

Here is a skeleton for a multiplayer provider:

public class MyMultiplayerProvider : NetworkProviderBase
{
    public override bool IsServer => _isServer;
    private bool _isServer;

    public MyMultiplayerProvider(bool isServer)
    {
        _isServer = isServer;
        RegisterDefaultHandlers();
    }

    protected override void RegisterDefaultHandlers()
    {
        // Register handlers for built-in commands
        RegisterHandler<DragDropCommand>(new DragDropCommandHandler());
    }

    public override void ExecuteCommand(ICommand command)
    {
        if (_isServer)
        {
            // Server: execute locally
            base.ExecuteCommand(command);
        }
        else
        {
            // Client: serialize and send to server
            byte[] data = Serialize(command);
            SendToServer(data);
        }
    }

    // Called when the server receives a command from a client
    public void OnCommandReceived(byte[] data)
    {
        ICommand command = Deserialize(data);
        base.ExecuteCommand(command);
    }
}

The key idea is that ExecuteCommand on the client sends the command over the network, while the server calls base.ExecuteCommand() to dispatch it locally through the handler.

Command Serialization

For multiplayer, commands need to be serializable. This is why commands should use simple types (strings, ints, floats, bools) and entry IDs instead of direct object references.

// Good: all fields are serializable
public class DealDamageCommand : ICommand
{
    public string AttackerId { get; set; }  // Entity ID string
    public string TargetId { get; set; }    // Entity ID string
    public string AbilityId { get; set; }   // Database entry ID
    public float Damage { get; set; }
}

// Bad: contains Unity references that can't be serialized over the network
public class BadCommand : ICommand
{
    public GameObject Target { get; set; }
    public Transform SpawnPoint { get; set; }
}

Best Practices

• Design commands for serialization from the start, even if you are building single-player.

• Use Spark.Network?.ExecuteCommand() with the null-conditional operator. This gracefully handles the case where no provider is set.

• Register command handlers in your plugin's RegisterPlugin() method.

• For multiplayer, validate commands on the server. Don't trust client input.

• Keep the LocalNetworkProvider as your development default. Swap to a multiplayer provider when your networking layer is ready.