Morpheus Actor function reference

The following is a list of functions related to Morpheus Actors, which you may find useful when writing your logic:

On the Morpheus Actor

The following are called on the MorpheusActor itself. Make sure to check the actor is not null!

• GetMorpheusActorLocation/Rotation/Velocity: shorthand helpers to get the fields from the morpheus actor - uses the equivalent of the old MorpheusActor->MorpheusActorMovementComponent->GetCurrentMovement, to get the values of the render target if applicable

• Get/SetCrowdMemberTransform: Gets or sets the transform used when this actor is rendered as a crowd member. Get returns the most recent transform set, even if the actor is not currently in the crowd. Set applies immediately if the actor is in the crowd, or will apply next time it enters.

  • Note: this is handled automatically if using MorpheusAnimatedSkeletalComponent.

• Teleport To: A morpheus actor specific teleport. Moves the MorpheusActor or its Render Target to a new location/rotation, and notifies the MorpheusMovement system not to interpolate to the new position (unlike a raw SetActorLocation). The actual actor moved is the current Render Target if one exists, otherwise the MorpheusActor itself. Can only be called from the machine with movement authority. Does not set the controller's control rotation — if teleporting a controlled character and wanting to move the camera, call SetControlRotation on the controller separately.

• GetEntityId: Returns the Morpheus entity ID (int64) for this actor.

Regarding the local machine type:

• IsOnConnectedClient: True if running on a client instance connected to a Morpheus server.

  • Note: includes worker and bot clients — use IsOnConnectedPlayerClient if you specifically want human player clients.

• IsOnDedicatedServer: True if running on a server instance; false on any client instance.

• GetIsOnBotClient: Returns whether the local connection that instantiated this actor is a bot client connection (see Bots), regardless of the actor's authoritative connection.

• GetIsOwnedByStreamingClient: Returns true if the actor's authoritative client is connected via streaming (e.g. GFN), as opposed to a native client.

• IsOnConnectedWorkerClient: True if the local client connection is a "worker client" (see Worker Clients)

• IsOnConnectedSentinel: True if running on a dedicated sentinel instance connected to a Morpheus server. (see Sentinel Clients)

• IsOnConnectedPlayerClient: True if the local client connection is specifically for a human player (i.e. not a worker, a bot or the like)

  • This is useful if you have logic that only needs to be done for human players, and not for bots/NPCs. (Just checking "is on client" or "is not on dedicated server" would include any type of machine which isn't the server)

Regarding the Morpheus Actor's "Connection"

• GetLocalClientConnection: Returns the AMorpheusClientConnection which the MorpheusActor is on. Returns nullptr on the server, or if no connection has been established yet. Cast to a concrete subclass (e.g. AM_DedicatedSentinelConnection, AM_WorkerConnection) to check the connection role.

• GetSentinelConnection: Returns the sentinel client connection that has sentinel authority over this actor. Server only.

• GetServerConnection: Returns the server connection if called on the server, otherwise nullptr.

Regarding the Actor's "Authority"

• SwitchMorpheusAuthority: Controls Blueprint execution flow based on what authority the local game instance has over this actor. Branches into:

  • Server — this game instance is the server.

  • Authoritative Client — this game instance has a client connection (including trusted connections) with authority over this actor's ClientAuthoritative properties.

  • Client — this game instance is a client whose connections have no authority over this actor.

    • Note: "Client connections" includes sentinel, worker, and bot clients — use IsOnConnectedPlayerClient() if you need to distinguish human players specifically.

• HasSentinelAuthority: Returns true if this machine is the sentinel and has authority over the sentinel properties and RPCs of this actor.

• GetHasFullServerAuthority: Returns true if the actor is fully server authoritative (i.e. has no authoritative client connection). Also returns true on clients when the server is fully authoritative.

• GetAnyLocalConnectionsHaveClientAuthority: Returns true if any of this game instance's client connections has authority over this actor. This is the preferred check for most game logic to check you are on the authoritative client.

  • Note: if this actor was spawned on the server with no client connection, the server is considered to have "client authority".

Regarding "attachments"

This is distinct to character having e.g. meshes attached to them - we can use the following functions to "attach" one Morpheus Acvtor to another. This allows the two to smoothly update their positions together across our networking. Used e.g. for passengers inside vehicles.

• MorpheusAttachTo: Auth-client only. Attaches this MorpheusActor to the given AttachParent at the specified socket, and replicates the attachment to all other clients. Attaches to the parent's render target actor if one exists, otherwise directly to the parent. Not supported if AttachParent is in the crowd.

• MorpheusDetach: Detaches this MorpheusActor from its Morpheus attach parent and replicates the detachment to all clients.

• IsMorpheusAttached: Returns true if this MorpheusActor currently has a valid Morpheus attach parent.

• GetMorpheusAttachSocket: Returns the name of the socket this actor is attached to on its parent, or None if not attached.

• GetMorpheusAttachParent: Returns the MorpheusActor this actor is attached to, or nullptr if not attached.

Regarding the actor's Net Relevancy Levels

For more details on these, see Net Relevancy Levels

• SetNetRelevancyGroup: Changes the actor into the target group. Its net relevancy level will be prioritized and set accordingly.

• NOTE: Make sure your actor's MinimumNetRelevancyLevel satisfies all the network levels the new group uses.

• GetNetRelevancyGroupType and GetNetRelevancyCustomGroupName can be used to get the current net relevancy group.

• SetIs/IsForcedintoForeground: Gets or sets whether this actor is forced into the foreground on the local machine (assuming there is capacity for the actor in the foreground bucket.

• Set/Get/ClearNetRelevancyPriorityOverride: Allows you to manually set the net relevancy priority of actors, so you can configure which in a group should be in foreground, midground etc.

Helper Functions

Some helper functions relating to Morpheus Actors:

Spawning morpheus actors

• SpawnMorpheusActorWithSplitAuthority: Spawns the MorpheusActor of the provided class with split authority.

  • The provided ClientConnection will have authority over the ClientAuthoritative properties of the spawned MorpheusActor, and receive Client RPCs to this actor

  • The server will have authority over the ServerAuthoritative properties and control the lifetime of this MorpheusActor.

  • Server only.

  • If you call the regular SpawnActor method (on the server) for a MorpheusActor, it will spawn an actor with full server authority, instead of split authority with a client connection.

Navigating between the actors associated with an entity

A networked actor in Morpheus Networking will have a Morpheus Actor. It may also have a separate "Render Target Actor", or a "Controller". The following helpers allow for easier navigation between the relevant classes associated with the same "entity":

• GetMorpheusActor: Returns the associated MorpheusActor for the given Actor (defaults to 'self').

  • Works when passed the Render Target actor, a Controller, or a collider proxy - all will resolve to the corresponding MorpheusActor.

• GetRenderTargetActor: Returns the current Actor used by the given MorpheusActor's RenderTargetComponent.

  • NOTE: can return nullptr, e.g. if the current EMorpheusRenderTargetType is not Actor.

• GetRenderTargetFromActor: Returns the Render Target Actor when passed an actor that is either a Render Target itself, or a Morpheus Actor, otherwise will return nullptr.

• GetContextualController: Gets either the regular actor controller for the actor if it's not a MorpheusActor, or the render target's controller if it is a MorpheusActor; a single one-size-fits-most method when you could get passed either an actor or an MA

• GetContextualActorLocation/Rotation/ForwardVector: Gets either the location/rotation/forward vector from the regular actor if it's not a MorpheusActor, from the render target if it is a MorpheusActor and there's a render target, or from the MorpheusActor's if not; a single one-size-fits-most method when you could get passed either an actor or an MA.

• GetFirstLocalClientConnection: Returns the AMorpheusClientConnection of the first Player Controller's Pawn in the world context.

  • NOTE: May be null if called too early. Needs to wait for bootflow conditions. (See The Bootflow Subsystem)

• GetMorpheusActorInCurrentConnection: Given a MorpheusActor and a connection, finds the corresponding MorpheusActor on that connection (if one exists).

  • Used e.g. for bots, where there are multiple connections, and therefore multiple MorpheusActor instances for the same entity per client.

Getting the authoritative Morpheus Actors

We have a few assorted helper functions to quickly get the authoritative Morpheus Actors for the current connection/machine:

• GetAuthoritativeMorpheusActors: Returns the MorpheusActors of all characters we are authoritative over.

  • Finds characters by iterating controllers, so uncontrolled characters will be missed.

  • Takes an optional IgnoredMorpheusActors array, to filter for particular actors.

• GetAuthoritativePawns: Same as above, but returns the APawn classes we are authoritative over.

• GetAuthoritativeCharacters: Same as above, but casting to ACharacter

• GetFirstAuthoritativeCharacter: Returns the first ACharacter we are authoritative over (or nullptr if none)

  • Effectively returns the first element from GetAuthoritativeCharacters, if there is one.

• GetFirstAuthoritativeActorComponent: Takes a ComponentType class, and returns the component on the first authoritative morpheus actor that has it

  • (Uses GetAuthoritativeMorpheusActors and iterates over it under the hood)

• ExpectingMorpheusConnectionType: Returns true if the world is expecting a connection of the provided type, using our world settings' MorpheusConnectionSettingsComponent. Can be called before bootflow completion, to check if we are e.g. expecting a player client.