Key Concepts

• An Actor is a lightweight, isolated unit of execution on the server, implemented with Akka.NET. Actors host Entities and handle their lifecycle and messaging.
• An Entity is a server-side object that encapsulates game logic and state. Entities communicate with each other via messages and can optionally persist their state in the database.
• A Model is a class that stores an Entity's persistent state. Some Models are shared with and replicated to the client (e.g., PlayerModel), while others are server-only.

Overview

There are many cases where it makes more sense to implement a game feature on the server instead of having it in shared code. Most common are the following:

• Sensitive or otherwise 'cheatable' game mechanics that you don't want to make accessible to the client.
• Services that are shared between multiple players and can be called upon from the client on a necessity basis.

In our own tutorials we have a few examples:

• In the Wordle Tutorial we use server-only configs to store the daily answers.
• In Implementing Cheat-Proof Randomization, the player can request a randomized reward from the server.

Server programming can be used to build guilds, leaderboards, matchmaking, async PvP, battle passes and so on.

The server is built on three core building blocks — Actors, Entities, and Models — which are described in detail below.

The Blueprint

You can add new server functionality in two ways:

• Extending the existing Actor code - You can add new logic my extending your existing code, like adding a new server action to the player Actor for example, to query a cheat proof randomizer or other server-side service.
• Creating new Actors to host custom Entities - If you wish to add an entirely new feature that doesn't fit with any Actors and Entities you already have, you can create entirely new kinds of Entities, like we'll explore on this page.

Actors, Entities and Models

To build and add new functionality to your game specific to the server, it's fundamental to understand the building blocks of the Metaplay SDK's server model.

The server consists primarily of Akka.NET actors that implement Entities that can communicate with each other or with the client through Models to implement gameplay loops.

Actors

Actors are like lightweight threads running independently on the server, implemented with Akka.NET. They run the Entities logic, and spawn when Entities are woken up. They exist only on the server and can be used to run server-only operations. Actors can send Akka.NET messages to other actors or to themselves, to implement timers, for example. While actors are a fundamental part of the server architecture, you rarely need to work with them directly — the SDK provides base classes like PersistedEntityActor that handle the actor lifecycle and messaging plumbing for you, so most of your work happens at the Entity and Model level.

Entities

Entities are server-side objects that encapsulate game logic and state, and can communicate with each other via messages. They are hosted inside actors and are activated on demand by the server, for example when a player starts a session or when a game admin inspects a player in the LiveOps Dashboard. Some Entities are persistent and backed by database state, while others are non-persistent and exist only while running, depending on their role.

• If Entities need to be modified by gameplay events happening in the client they can be attached to Models, and synchronize with the changes being sent from the client.

• Entities can communicate with each other and pass data around using the protocols described in Deep Dive: Entity-to-Entity Communication. Entities can transmit and receive messages between each other, usually for backend operations.

• Entities can be either persisted (backed in database when their Actor isn't active) or ephemeral (their state is forgotten when the Actor shuts down).

You can find more details about creating Entities in the Custom Entities page.

Models

Models are classes that store persistent state in the database and are owned and validated by the server. They can be modified through server-validated operations, and changes are automatically persisted and synchronized. Some Models are shared with the client and replicated to it, while others are server-only and never exposed to the client.

A common example is the PlayerModel class, used to keep track of a single player's state, with changes generally being initiated by the client. They can be used for other types of Entities such as the GuildModel, that represents a multiplayer guild.

Models are generally how most game logic is expressed, and are commonly modified in two ways: Ticks and Actions. Ticks are executed periodically (usually a few times per second), while actions are triggered through gameplay, usually as a result of player input.

Models are part of Entities, but not all Entities have models.

Custom Entities and Actors

You can create custom entities, actors and models in the server. Custom entities serve as encapsulated, shared units of computation that you can use for any purposes. In practice, if you need to share state between players, you need to add an entity between them. You can get a dedicated how-to in the Custom Entities page.