The Altruist Portal

Overview

Portals are the entry points for client connections. They define how requests and responses are handled. Each portal is plug-and-play, meaning it can provide default behaviors and features while being customizable to suit specific needs. Portals play a key role in managing interactions between clients and the game server.

Example: A Simple Game Portal

Here’s an example of a spaceship game portal:

using Altruist;
using Altruist.Gaming;
using Microsoft.Extensions.Logging;

namespace Portals;

public class SimpleGamePortal : AltruistGamePortal<Spaceship>
{
    public SimpleGamePortal(IPortalContext context, ILoggerFactory loggerFactory) : base(context, loggerFactory)
    {
        // Initialize the portal
    }

    // added for visibility, but provided by the AltruistGamePortal
    [Gate("leave-game")]
    public virtual Task ExitGameAsync(LeaveGamePacket message, string clientId);

    // added for visibility, but provided by the AltruistGamePortal
    [Gate("handshake")]
    public virtual Task HandshakeAsync(HandshakePacket message, string clientId);

    // added for visibility, but provided by the AltruistGamePortal
    [Gate("join-game")]
    public virtual Task JoinGameAsync(JoinGamePacket message, string clientId);
}

What is a Gate?

A Gate defines the event that the portal is receiving. Methods annotated with the [Gate] attribute correspond to specific actions or messages the portal will handle. These methods take two parameters:

  1. A packet (a message or data object) that extends IPacketBase.
  2. A clientId, representing the client that sent the message.

For example, in the code above:

  • The ExitGameAsync method listens for a leave-game event.
  • The HandshakeAsync method listens for a handshake event.
  • The JoinGameAsync method listens for a join-game event.

These are just example events that clients can trigger, and you can customize your portal to handle any set of events necessary for your game.

Note:

The clientId parameter allows you to identify the sender of the request, which can be helpful for managing sessions or sending targeted responses.

Message Routing in Portals

Portals in Altruist also provide basic message routing capabilities. This makes it easy to send messages to clients, rooms, or broadcast them globally.

Send Messages to Clients

To send a message to a specific client:

Router.Client.SendAsync(clientId, message);

Send Messages to Specific Room

To send a message to all clients in a specific room:

Router.Room.SendAsync(roomId, message);

Broadcast Messages

To send a message to all connected clients:

Router.Broadcast.SendAsync(message);

Exclude a Client from Broadcast

To broadcast a message but exclude a specific client:

Router.Broadcast.SendAsync(message, excludedClientId);

Portal Connection and Room Handling

Portals in Altruist also manage client connections and rooms. These are essential for organizing and managing game states.

Connection Management Methods

Method NameDescription
AddConnectionAsyncAdds a new client connection.
RemoveConnectionAsyncRemoves a client connection.
GetConnectionAsyncRetrieves a specific connection by its ID.
GetAllConnectionsAsyncRetrieves all active connections.
GetAllConnectionIdsAsyncRetrieves all connection IDs.

Room Management Methods

Method NameDescription
GetRoomAsyncRetrieves a room by its ID.
GetAllRoomsAsyncRetrieves all rooms.
GetConnectionsInRoomAsyncRetrieves all connections in a specific room.
FindAvailableRoomAsyncFinds an available room.
AddClientToRoomAsyncAdds a client to a specific room.
FindRoomForClientAsyncFinds the room associated with a specific client.
CreateRoomAsyncCreates a new room.
SaveRoomAsyncSaves the state of a room.
DeleteRoomAsyncDeletes a room.

Example: Adding Client to a Room

To add a client to a room:

var room = await portal.AddClientToRoomAsync(clientId, roomId);

This allows you to manage the clients within rooms, enabling features like team-based gameplay, private areas, or separate game sessions.

Note:

Rooms in Altruist provide an effective way to organize groups of clients for multiplayer games, chats, or other shared spaces.

By default, each player is automatically added to a global room. The system is designed to handle room capacity management efficiently. When the global room reaches its maximum capacity, the system will automatically open a new room to accommodate additional players, ensuring that all players are always assigned to a room without manual intervention.

This ensures that player load is balanced across multiple rooms and that players can always join without facing delays or over-crowding.

Summary

Portals are the core entry points in Altruist, defining how requests are handled and providing powerful features for message routing, connection management, and room handling. You can customize your portal by defining events using the [Gate] attribute and use built-in mechanisms for sending messages and organizing clients into rooms.

Note:

Remember: Portals are designed to be plug-and-play — you can add your custom behavior while leveraging default functionalities for faster development.