# RPCs

In Morpheus, Remote Procedure Calls (RPCs) are defined the same way as in vanilla Unreal, but have some important differences in behaviour.

As with all Morpheus networking, Morpheus RPCs are restricted to classes that inherit from `AMorpheusActor` or `UMorpheusActorComponent`. RPCs on other classes won't work.

### Arguments

RPCs can take any number of arguments.

RPC arguments can use the same types as standard Unreal networking, with one exception. Object references must be references to:

* Morpheus actors
* Morpheus actor components
* [Stably named objects](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicate-actor-properties-in-unreal-engine#stablynamedobjects)

### Server RPCs <a href="#morpheusrpcs-serverrpcs" id="morpheusrpcs-serverrpcs"></a>

In Morpheus, **any client can invoke any** `Server` **RPC on any** `AMorpheusActor`. The RPC is executed on the server. The server can also invoke a `Server` RPC itself, in which case it will be executed locally.

#### Helper functions

There are four special `AMorpheusActor` functions you can call from within the handler for a `Server` RPC:

1. `AuthoritativeClientCalledServerRpc` checks whether the RPC was invoked by the client which has authority over the actor. (You can use this to emulate the standard Unreal semantics, where only the authoritative client can call a `Server` RPC.)
2. `ServerCalledRpc` checks whether the RPC was invoked locally, i.e. by the server.
3. `ServerRPCCallerOwnsActor` accepts an `AMorpheusActor`. It checks whether the RPC was invoked by the connection which has authority over the given actor. This is useful for Singleton type actors that need an auth actor passed in to do their work.
4. `ServerGetRpcCallerConnection` returns the `AMorpheusConnection`which invoked the RPC - either a client or the server. (This becomes complicated when working with bots - see [here](https://docs.msquared.io/creation/features-and-tutorials/bots#calling-server-rpcs).)

There are also corresponding functions with the same names on `UMorpheusActorComponent`. Please note that if an RPC is called on the component, you should check these functions on the component directly, not the owning actor.

### Client RPCs <a href="#morpheusrpcs-clientrpcs" id="morpheusrpcs-clientrpcs"></a>

In Morpheus, **the server or any client can invoke any** `Client` **RPC on any** `AMorpheusActor`. The RPC is executed only on the **authoritative** client.

From within the handler of a `Client` RPC, you can use the `AMorpheusActor` function `ServerCalledRpc` to determine whether the RPC was invoked by the server. (You can use this to emulate the standard Unreal semantics, where only the server can call a `Client` RPC.)

### NetMulticast RPCs <a href="#morpheusrpcs-netmulticastrpcs" id="morpheusrpcs-netmulticastrpcs"></a>

In Morpheus, both server and client can call `NetMulticast` RPCs. A `NetMulticast` RPC will be executed locally when called and then, if invoked from...

* the authoritative server: it will also be executed on all clients with this `AMorpheusActor` in the foreground network level.
* the authoritative client: it will also be executed on the server *and* all clients with this `AMorpheusActor` in the foreground network level.
* a non-authoritative client: it won't be executed anywhere else.

From within the handler of a `NetMulticast` RPC, you can use the `AMorpheusActor` function `ServerCalledRpc` to determine if the server invoked the RPC. This can be used on the client to determine that the RPC was called by the server as opposed to another client, or on the server to handle the local execution of the RPC. Use the `AMorpheusActor` function `IsOnClient` to handle these cases separately.

### RPC Guarantees <a href="#morpheusrpcs-rpcguarantees" id="morpheusrpcs-rpcguarantees"></a>

*The Morpheus system has semantics and behaviour that may not be immediately obvious. This is a non-exhaustive list of semantics we offer for external developers to use as a reference, and for internal developers to refer to when making changes.*

Morpheus offers some ordering guarantees in order to try and match some Unreal semantics. See [this doc](https://github.com/improbable/morpheus-core/blob/master/morpheus/docs/guarantees.md) in the `morpheus-core` repository for more information on what these are and how we offer them. Because this repository is available to Improbable developers only, a subset of the doc relevant to Unreal development is exposed here:

#### Salient Ordered Channels <a href="#morpheusrpcs-salientorderedchannels" id="morpheusrpcs-salientorderedchannels"></a>

**Multicast RPCs from clients** and **Client Authoritative Entity Data** offers ordering when sent from the same client.

**Server to Client RPCs** and **Authoritative Client Entity Deletions** offers ordering as both will be sent from the server.

**Multicast RPCs from servers**, **Server Authoritative Entity Data** and **Server Authoritative Owner Only Entity Data** offers ordering as all will be sent from the server.

In other words, in Morpheus, RPCs of the same type on the same actor are **guaranteed** to be executed in the same order they were called. For example:

1. The server invokes two RPCs on `MorpheusActor_A`: first `NetMulticastRPC_1`, then `NetMulticastRPC_2`.
2. The client executes `NetMulticastRPC_1` first, then executes `NetMulticastRPC_2`.

#### Non-Ordered Channels <a href="#morpheusrpcs-non-orderedchannels" id="morpheusrpcs-non-orderedchannels"></a>

An example of a pair of channels that you might think would be ordered but are not is **Server Authoritative Entity Data** and **Authoritative Client Entity Deletions**.

In Morpheus, different types of RPCs are **NOT guaranteed** to be executed in the same order. For example:

1. The server invokes two RPCs on `MorpheusActor_A`: first `ClientRPC_1`, then `NetMulticastRPC_1`.
2. The client will **NOT** necessarily execute `ClientRPC_1` first.

#### Reliability <a href="#morpheusrpcs-reliability" id="morpheusrpcs-reliability"></a>

Morpheus RPCs are always **reliable** even if you marked them as **unreliable**.

As long as your client is **connected**, it will receive all RPCs sent to it.