Quick Start Guide

Every great game begins with a solid server. Let’s build yours.

Setting up a server is straightforward. Follow these steps to get started quickly and efficiently.

Create Your First Portal

In Altruist, Portals are the entry points for client-server communication. Every multiplayer interaction happens through them.

Note:

The transport layer requires at least one portal to start with. Let's see how to create it.

src
Portals
SimpleGamePortal.cs
Program.cs
Portals/SimpleGamePortal.cs
using Altruist;
using Altruist.Gaming;
using Microsoft.Extensions.Logging;
using SimpleGame.Entities;

namespace Portals;

public class SimpleGamePortal : AltruistGameSessionPortal<SimpleSpaceship>
{
    public SimpleGamePortal(IPortalContext context, GameWorldCoordinator worldCoordinator, IPlayerService<SimpleSpaceship> playerService, ILoggerFactory loggerFactory) : base(context, worldCoordinator, playerService, loggerFactory)
    {
    }
}

Note:

Each game portal receives a player entity to determine the game type.
In this example, AltruistGamePortal<Spaceship> sets up a spaceship shooter.

What does this portal do?

It provides instant connectivity using a username and manages rooms/sessions automatically.

Setting Up the Server

Don't worry — it's extremely easy!

This example sets up a minimal game server that supports WebSocket communication, a physics engine (world simulation), and basic movement handling.

Minimal WebSocket Server

using Altruist;
using Altruist.Gaming;
using Altruist.Gaming.Engine;
using Altruist.Web;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Xna.Framework;
using Portals;
using SimpleGame.Entities;
using SimpleGame.Services;

// Create and configure the Altruist server
AltruistBuilder.Create(args)
    .SetupGameEngine(setup => setup
        .AddWorld(new MainWorldIndex(0, new Vector2(100, 100)))
        .EnableEngine(FrameRate.Hz30))
    // Set up WebSocket communication
    .WithWebsocket(setup => setup
        // Map endpoints to "portals" 
        .MapPortal<SimpleGamePortal>("/game") (communication handlers)
        // (can map multiple handlers to the same path)
        // .MapPortal<SimpleMovementPortal>("/game")
    )
    // Build and start the server
    .WebApp()
    .StartServer();

// World definition class
public class MainWorldIndex : WorldIndex
{
    public MainWorldIndex(int index, Vector2 size, Vector2? gravity = null) : base(index, size, gravity)
    {
    }
}
PartWhat it DoesWhy it's Needed
AltruistBuilder.Create(args)Creates the main server builder.Central place to configure the server (game engine, web, services).
.SetupGameEngine(...)Sets up the physics and game simulation system.Without a game engine, there’s no way to simulate world updates.
.AddWorld(new MainWorldIndex(...))Adds a physics world to the engine.Games are built on worlds — this defines their size, gravity, and index.
.EnableEngine(FrameRate.Hz30)Runs the simulation at 30 updates per defined unit.Keeps physics updates consistent and smooth.
.WithWebsocket(...)Enables WebSocket communication with clients.Players need a way to send/receive data to/from the server.
.MapPortal<SimpleGamePortal>("/game")Connects a Portal (network handler) to an endpoint.Portals define how incoming WebSocket messages are handled.
.WebApp()Tells Altruist to setup a web based application.Needed to serve WebSocket connections properly.
.StartServer()Starts the server and begins accepting connections.Finally brings everything online.

A Note About MainWorldIndex

  • A WorldIndex defines a physical simulation space.
  • It holds size (dimensions) and gravity settings.
  • index allows you to reference multiple worlds if you later want multi-world setups (for instance: overworld, dungeon, arenas).

In this example, gravity is set to zero (null), this doesn't mean no gravity. The default gravity is Vector(0, 9.81f)

To run it, use:

> dotnet run

...

[ALTRUIST-1.0] ⚡ WebSocket support activated. Ready to transmit data across the cosmos in real-time! 
[ALTRUIST-1.0] ⚡ Redis support activated. Ready to store and distribute data across realms with incredible speed! 
[ALTRUIST-1.0] 🔗 Subscribing to Redis Pub/Sub channels..
[ALTRUIST-1.0] ⚡ ScyllaDB support activated. Ready to store and manage your data efficiently! 

...

🔌 Opening SimpleGamePortal through /game

 The Portals Are Open! Connect At:                  
----------------------------------------------------
 💻 Address: ws://localhost:8080/game               
 📡 Transport: WebSocket                            
 💾 Cache: Redis                                    
 💾 Database: ScyllaDB                              
----------------------------------------------------
 ✨ Welcome, traveler! 🧙                          


[ALTRUIST-1.0] Now listening on: http://localhost:8080
[ALTRUIST-1.0] Application started. Press Ctrl+C to shut down.
[ALTRUIST-1.0] Hosting environment: Production

Explore Further

Want to see the Altruist Engine in action? Check out our resources:

  • Visit our GitHub repository for more examples, best practices, and real-world usage.
  • Try out our Simple Game Example — a ready-made starter project that we actively maintain to provide a strong skeleton for building your own game.

Note:

The Simple Game Example showcases real-time physics, movement, world simulation, and WebSocket communication — all powered by Altruist!