Security & Validation

Here is another example of what we can do now:

@WebSocketGateway()
export class GameGateway
{
  @SubscribeMessage(ClientEvents.LobbyCreate)
  onLobbyCreate(client: AuthenticatedSocket, data: LobbyCreateDto): WsResponse<ServerPayloads[ServerEvents.GameMessage]

We have a complete code autocompletion based on the return type! This will certainly make your life easier, believe me.

Hey! In your example, did you start implementing the game? What is "LobbyCreateDto"? And what is an "AuthenticatedSocket"? They were not in the previous examples!

I know, I know, we will see what these elements are, don't worry, we are taking small steps to understand different concepts. It's important to grasp them well first. When you see the big picture, hopefully, everything will fit together and make sense! :)

So, what is an "AuthenticatedSocket"?

Well, it is very likely that you will need to authenticate your users in your application/games. This step can be done when a client wants to connect to your server. On your gateway, implement the interface "OnGatewayConnection":

@WebSocketGateway()
export class GameGateway implements OnGatewayConnection
{
  async handleConnection(client: Socket, ...args: any[]): Promise<void>

Now we can authenticate our users. We know that each client has gone through this step. To be explicit in the code, I treat them as "authenticated," and they now have a new type.

export type AuthenticatedSocket = Socket & {
  data: {
    lobby: null | Lobby;
  };

  emit: <T>

As you can see, in the key data (which is a convenient key provided by Socket.IO on the Socket object, you can put whatever you want there), I declare a subkey lobby, which will be used later to attach a lobby to the client.
I've also replaced the emit method to explicitly have the enumeration ServerEvents as the type of emitted event.

And the validation?

In order to validate incoming data correctly, add two packages:

NestJS is a great tool that allows you to automatically validate incoming data transmitted with an event, for this, you will need to create your own DTO (Data Transfer Object), this MUST be a class, TypeScript once compiled does not store metadata on generics or interfaces of your DTOs, so this can cause your validation to fail, do not take risks, use classes.

Here is the validation class for creating the lobby :

I also annotate my gateway with my validation channel :

Great ! Incoming data is now validated ! Always ensure to validate user inputs !

Okay, I get it, so we first cover the basics, and then we move on to the actual implementation ?

You are absolutely right ! It is important to understand the basics of the tools you are using, once that's done, you are ready to implement your own business logic.

A Bit of Theory

You can find different types of games ;

• Single-player Game

• Multiplayer Game

• Online Multiplayer Game

• Massively Multiplayer Online Game (MMO)

A single-player game does not involve interaction with a server, you play on your client and everything is integrated, game interactions are predefined. (e.g.: The Witcher)

A multiplayer game can be played by multiple players at the same time, still without any server involved, this is local multiplayer: all players play on the same machine, from the same game client (e.g.: Cuphead)

An online multiplayer game can be played by several players simultaneously, since it is online, it involves one or more servers, clients communicate via persistent connection protocols (TCP / UDP / WS / ...) to the server(s) and vice versa to play. (e.g.: Fall Guys) Here is our use case.

Finally, MMOs, which follow the same principle as above but must accommodate (potentially) millions of players, they also use server distribution based on population, shards, and layered world zones, which implies much more complex concepts. (e.g.: World of Warcraft) But in our case, this is not necessary! :)

I highly recommend checking out the videos from the GDC (Game Developers Conference) if you're interested in such topics. (some videos explain these concepts in much more depth, it's fascinating!)

Okay, so what's the problem with our browser game?

Well, we have a server, we have clients, we have a way to communicate between both in real-time, now we need to know how to implement lobbies for players to join and play the game!

Once we implement the lobbies, you will have accomplished a huge part, from there you can implement your game logic and invite users to play ! :)

Lobby Management, Part 1

As I mentioned at the beginning of the article, I've implemented lobbies and the game in a way that makes sense to me, using the knowledge gained from my previous experiences with Unity and how I imagine online lobbies/games are managed. You are more than welcome to comment and share your own implementation if it's different.

For my use case, we can have a lot of players all playing at the same time, but not necessarily in the same "lobby", which means we need to separate each "instance" individually.

This way, if players A, B, and C are in lobby 1 playing, their actions will not have consequences on the game of players D, E, and F who are in lobby 2.

If we want lobbies, then it would be nice to have a LobbyManager that will manage these lobbies.

Let's start by declaring that !

export class LobbyManager
{
public server: Server;

private readonly lobbies: Map<Lobby['id'], Lobby> = new Map<Lobby['id']

Lots of things are happening, let's see one by one what they do.

• I declare a public property server, which will hold the Socket.IO WebSocket server (and it is assigned from the afterInit hook during server initialization), wsserver is necessary to perform operations from lobbies to emit to clients for example.

• I declare another property lobbies, this is a map that contains all the ongoing lobbies, mapped by their identifier.

• I declare two methods initializeSocket and terminateSocket, I like to attach such methods to handlers, this way I can "prepare" the client socket (I call it when the client has connected and authenticated successfully) but also execute code, the same behavior when a client disconnects for any reason (I call terminate this time).

• I declare the method createLobby, I think you guessed what this method does.

• I declare the method joinLobby, I think you guessed what this method does as well.

• I declare the method lobbiesCleaner, this method is responsible for cleaning / clearing lobbies periodically after a certain time to avoid memory leaks (NodeJS and JavaScript are great tools but remember it's a long-running process, if you keep storing references to objects and data, at some point you will run out of memory and your server will crash). (You may notice that I annotated it with @Cron(), NestJS being so cool, it will execute this method for us every 5 minutes!)

I won't necessarily show every implementation so as not to visually clutter, if you want to check the actual code, you can find the complete repository here.

Let's see how we would create a lobby :

1. A client connects to the server

2. The player wants to start a new lobby, clicks a button to create a lobby

3. The client sends the event instruction "client.lobby.create" to the server

4. The server receives the instruction, it can perform all checks and validation to create this lobby (maybe we want only administrators to create lobbies ? We want to check if the client is not in another lobby ? etc...)

5. The server creates the lobby and sends a success event

Wait, wait, wait, you're always talking about servers and how to handle incoming events, but I still don't know how to handle the client side, how do I connect to the server ?!

Yes, you're right, let's move on to the frontend a bit to see how to play with WebSockets and React, that way you'll have a complete overview of the communication !

Client-Side Event Management

In this chapter, we will see how I implemented client-side event management using React, if you are not using this framework, you can still follow along but you will probably need to adapt to your own situation.

To interact with the WebSocket API, on React, I wrote a wrapper class around the socket client, with which I created a custom context provider to wrap my application.

Why?

This approach allows me several things ;

• Access the socket client from anywhere in the application

• Control when I want the socket to connect

• Attach custom behaviors to the socket client (what happens if I get kicked by the server? what happens if the client receives exceptions? ...)

• Attach listeners (to listen to events from the server)

• Declare my own emit method (with the ClientEvents enumeration enforced and the ability to input outgoing data)

You can find all of this here.

Then, from your components, you can do things like this:

export default function Game() {
const {sm} = useSocketManager();

const onPing = () => {
sm.emit({
event: ClientEvents.Ping,
});
};

return (
<div>
<button onClick={onPing}>ping</button>
</div>

If you try this code, open your console, go to the Network tab, and check the WebSocket connection, you will see the client sending pings and the server (if you have the subscriber shown previously implemented) responding pongs!

Yeah, that's cool, but how do I send data with the event?

Just set it as the "data" key in the event.emit() object:

This will send the time with the event! :)

Okay, and what about incoming events from the server?

For that, you need to declare listeners on the client, you can do it like this :

export default function GameManager() {
const {sm} = useSocketManager();

useEffect(() => {
const onPong: Listener<ServerPayloads[ServerEvents.Pong]> = async (data) => {
showNotification({
message: data.message,
});
};

sm.registerListener(ServerEvents.Pong, onPong);

return () => {
sm.removeListener(ServerEvents.Pong, onPong);
};
}, []);

return (
<div>...</div>

This example will display a notification (pong) every time the server sends a pong event to the client !

Be careful not to register the same listener or the same event multiple times, you would duplicate the behavior. (and maybe introduce side effects) Also, remember to remove the listeners once the component is unmounted (that could create side effects or memory leaks).

Finally, if you have "global" events, you can listen to them on higher-order components, with a state management library, you will be able to easily share updates to other components.

In the example, I have global events that I listen to on the GameManager.tsx component. For the state management library, I used Recoil.

After all this, I think we've covered the client side, I highly encourage you to check the links and look at the game example to see how it is implemented exactly.

Now, back to lobby management!

Lobby Management, Part 2

Let's recall the steps to create a lobby :

1. A client connects to the server

2. The player wants to start a new lobby, clicks a button to create a lobby

3. The client sends the event instruction "client.lobby.create" to the server

4. The server receives the instruction, it can perform all checks and validation to create this lobby (maybe we want only administrators to create lobbies ? We want to check if the client is not in another lobby ? etc...)

5. The server creates the lobby and sends a success event

Well, I guess we can start implementing this !

Starting with the gateway :

Server gateway, with a bit more code, including the subscriber for creating the lobby :

@UsePipes(new WsValidationPipe())
@WebSocketGateway()
export class GameGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect
{
constructor(
private readonly lobbyManager: LobbyManager,
)
{
}

afterInit(server: Server): any
{
// Passer l'instance du serveur aux gestionnaires
this.lobbyManager.server = server;

this.logger.log('Serveur de jeu initialisé !');
}

async handleConnection(client: Socket, ...args: any[]): Promise<void>
{
// Appeler les initialiseurs pour configurer le socket
this.lobbyManager.initializeSocket(client as AuthenticatedSocket); }

async handleDisconnect(client: AuthenticatedSocket): Promise<void>
{
// Gérer la terminaison du socket
this.lobbyManager.terminateSocket(client);
}

@SubscribeMessage(ClientEvents.LobbyCreate)
onLobbyCreate(client: AuthenticatedSocket, data: LobbyCreateDto): WsResponse<ServerPayloads[ServerEvents.GameMessage]

Our LobbyManager :

export class LobbyManager
{
public server: Server;

private readonly lobbies: Map<Lobby['id'], Lobby> = new Map<Lobby['id']

And we created a lobby! :D

Wait, what's a "Lobby"? I still don't know what's inside...

Well, it's quite informative yes, a lobby is also a class, it is responsible for grouping clients, managing them, and also sending events to its clients, let's see what's inside!

export class Lobby
{
public readonly id: string = v4();

public readonly createdAt: Date = new Date();

public readonly clients: Map<Socket['id'], AuthenticatedSocket> = new Map<Socket['id'], AuthenticatedSocket>();

public readonly instance: Instance = new Instance(this);

constructor(
private readonly server: Server,
public readonly maxClients: number,
)
{
}

public addClient(client: AuthenticatedSocket): void
{
this.clients.set(client.id, client);
client.join(this.id);
client.data.lobby = this;

// TODO: autre logique

this.dispatchLobbyState();
}

public removeClient(client: AuthenticatedSocket): void
{
this.clients.delete(client.id);
client.leave(this.id);
client.data.lobby = null;

// TODO: autre logique

this.dispatchLobbyState();
}

public dispatchLobbyState(): void
{
// TODO: Comment un lobby est-il représenté aux clients ?
}

public dispatchToLobby<T>

Here, we see several things, let's go through them ;

• I declare a property id, it makes sense, we want to identify our lobbies.* I declare a property createdAt, it will be used later by the LobbyManager, to clean up the lobbies.

• I declare a property clients, it contains a map of each client associated with this lobby.

• I declare a property instance, this is another class, it is actually the game implementation, I differentiate it from the lobby since the lobby is supposed to manage clients and state distribution operations, but the actual game logic resides in the Instance class. (This approach also makes your code more reusable, respecting the SRP principle, it is easier to port this piece of code for other projects too)

• You may notice that in the constructor, I declare two properties, one to pass the server WebSocket (from the LobbyManager, remember that this is necessary because the lobby will need to send messages to the Socket.IO rooms, and also a maxClients which is, as its name indicates, the maximum number of clients for this lobby.

• I declare two methods addClient and removeClient, I think you guess what they do. Feel free to attach custom logic if you need; if someone joins the lobby, maybe you want to alert the other players? same if someone leaves?

• Finally, I declare two last methods; dispatchLobbyState and dispatchToLobby, the latter is used to send messages to players in the lobby, the former I use to automatically retrieve basic information about the lobby to send to players (like the number of connected players, the progress of the instance, ...) anything you want.

You can find the exact implementation of this file here.

Additionally, to be explicit about what happens here; the client gives the instruction to create a lobby, the server executes it and adds the client directly to this lobby, so the client is in a lobby, and as the client side was listening to whether the client was in a lobby or not, its display updated automatically!

To give you a little exercise, implement the "join a lobby" behavior yourself, it's a great starting point to play with every domain we've seen before. (client, api, server, gateway, lobby) Of course, if you don't want to, you can always check the example to see how I did it.

That's a lot to digest so far, feel free to go through the example project to see how it's done. If you want to take a break, go ahead, I'll wait. :)

Instance Implementation

Are you back? Great! We can continue then, there isn't much left to see, I promise!

The instance implementation is the game itself, but we don't care that much to be honest, for the example project it is a really simple game to train memory, nothing fancy, the only thing I wanted to talk about is its interactions with clients (players) and the lobby.

In the example project, players can only take one action, which is to reveal cards, let's see how it handles this.

On the client side, we use the same interface, passing the index of the card as data to tell the server which one we revealed.

Then, in the gateway, we will listen to this event :

As you can see from the subscriber, I first check if the client is in a lobby, if not, I return an error. I could have chosen not to return this error and simply do :

But for demonstration purposes, it is interesting to show how you can generate errors. (These are handled and displayed to end users via SocketManager.ts, but you can adjust this behavior to handle them yourself)

Then, from the Instance class :

You can see that we pass the cardIndex variable and the client object, the first is to identify which card should be revealed, the client needs to know who performed the action. Once all the game logic is executed, we make a call to our Lobby.dispatchLobbyState() method, this will ensure that clients receive an updated state of the game.

If you are curious to know the actual implementation of the game, you can find it here.

And that's about it, you now know how to create a simple online multiplayer game based on the lobby! I invite you to check the project example to see how it is implemented, refine it, break it and play with it.

Of course, the project example remains very simple, but it’s up to you to create more complex and interesting games and applications, you can play with timers, intervals, interact with a database, there’s not much limit! :)

Lobby Management, Part 3

You talked about cleaning up lobbies, what exactly does it do?

NodeJS is a smart tool, it automatically manages memory for you (and for me), but in some cases, you need to be cautious.

export class LobbyManager
{
private readonly lobbies: Map<Lobby['id'], Lobby> = new Map<Lobby['id']

Here, we declared a map to keep track of lobbies, but that also means we are keeping references to all these lobby objects.

NodeJS will allocate more and more memory every time it needs it, until you run out of memory (no more memory). But NodeJS also manages memory for you, it will "detect" what is no longer used and will "garbage collect" it.

Here is an amazing introduction to garbage collection (in Ruby, but the concept is pretty much the same in any language)

But as you have seen, our map is used to reference the lobbies, so what would happen if players were to launch millions of lobbies? You will need to periodically clean up (delete) lobbies so that the garbage collector sees that you are no longer referencing them, thus cleaning them up.

To manage this, we will rely on NestJS task schedulers. I will let you install the necessary packages and configure accordingly.

Then, it’s really simple ;

export class LobbyManager
{
private readonly lobbies: Map<Lobby['id'], Lobby> = new Map<Lobby['id'], Lobby>();

// Nettoyer périodiquement les lobbies
@Cron('*/5 * * * *')
private lobbiesCleaner(): void
{
for (const [lobbyId, lobby] of this.lobbies) {
const now = (new Date()).getTime();
const lobbyCreatedAt = lobby.createdAt.getTime();
const lobbyLifetime = now - lobbyCreatedAt;

if (lobbyLifetime > LOBBY_MAX_LIFETIME) {
lobby.dispatchToLobby<ServerPayloads[ServerEvents.GameMessage]

We ask NestJS to execute this method every 5 minutes thanks to the @Cron() annotation, which will perform a check on each lobby to see if the lobby's lifespan has expired or not, if so, we remove the lobby from the map, which makes it no longer referenced.

This implementation is really simple but works well, you just need to find what the right lobby lifespan value is.

Of course, depending on your game/application, you may need to completely change how you manage lobbies, perhaps store them in a database and keep them alive only when players are present. It's up to you to decide, just be sure to monitor your service resources.

We also did not address reconnection, the example project remains very simple, but to give you a hint on that, you can attach your user credentials to the lobby and check upon connection if they are already members of a lobby to attach them back.

Conclusion

This was a long article, a lot to go over and digest, but you’ve made it to the end, congratulations! :)

I did not cover deployment aspects as it is not the most interesting part, but if you are curious, you can check the example project. It provides basic Docker container configurations.

You are free to reuse my implementation, adjust it, or be inspired by it. This may require adjustments based on your personal use case. Also, keep in mind that this game implementation does not fit into the game loop model (https://gameprogrammingpatterns.com/game-loop.html) that you would see in game engines like Unreal or Unity. Here, the game reacts to user inputs (or your own timers you may implement on the server side) and does not continue by itself. Depending on your needs, you might need to implement a game loop (for example, if you want to create a world where players can move and interact).

Having used a heavily object-oriented approach with an opinionated framework like NestJS for server-side management has worked quite well, and I was able to scale and manage much larger projects this way. If you've implemented such applications/games before, I’m curious to hear your feedback !

One last note: never trust or validate user inputs on the client side. Always take base inputs from clients and validate them on the server side. That way, players cannot cheat (at least not too easily).

Thank you for reading, and have a great day!