Hyperion

Hyperion is a Minecraft game engine that can have 10,000+ players in one world. Our pilot event hopes to break the PvP Guinness World Record of (8825 by EVE Online). The architecture is ECS-driven using flecs via Flecs-Rust.

https://github.com/user-attachments/assets/64a4a8c7-f375-4821-a1c7-0efc69c1ae0b

Feature Status

Benchmarks

Test Environment:

• Machine: 2023 MacBook Pro Max 16" (14-cores)
• Chunk Render Distance: 32 (4225 total)
• Commit hash faac9117 run with HYPERION_PROFILE=release-full nix run .#bedwars
• Bot Launch Command: nix run .#bots -- 127.0.0.1:25565 {number}

The bulk of player-specific processing occurs in our proxy layer, which handles tasks like regional multicasting and can be horizontally scaled to maintain performance as player count grows.

Architecture

Overview

flowchart TB
    subgraph GameServer["Game Server (↕️ Scaled)"]
        direction TB
        subgraph BevyMT["Bevy Multi-threaded ECS"]
            direction LR
            IngressSys["Ingress System"] --> |"1 Game Tick (50ms)"| CoreSys["Core Systems (Game Engine)"] --> GameSys["Game Systems (Event Logic)"] --> EgressSys["Egress System"]
        end
        
        TokioIO["Tokio Async I/O"]
        TokioIO --> IngressSys
        EgressSys --> TokioIO
    end
    
    subgraph ProxyLayer["Proxy Layer (↔️ Scaled)"]
        direction TB
        Proxy1["Hyperion Proxy"]
        Proxy2["Hyperion Proxy"]
        ProxyN["Hyperion Proxy"]
        
        MulticastLogic["Regional Multicasting"]
    end
    
    subgraph AuthLayer["Authentication"]
        Velocity1["Velocity + ViaVersion"]
        Velocity2["Velocity + ViaVersion"]
        VelocityN["Velocity + ViaVersion"]
    end
    
    Player1_1((Player 1))
    Player1_2((Player 2))
    Player2_1((Player 3))
    Player2_2((Player 4))
    PlayerN_1((Player N-1))
    PlayerN_2((Player N))
    
    TokioIO <--> |"Rkyv-encoded"| Proxy1
    TokioIO <--> |"Rkyv-encoded"| Proxy2
    TokioIO <--> |"Rkyv-encoded"| ProxyN
    
    Proxy1 <--> Velocity1
    Proxy2 <--> Velocity2
    ProxyN <--> VelocityN
    
    Velocity1 --> Player1_1
    Velocity1 --> Player1_2
    Velocity2 --> Player2_1
    Velocity2 --> Player2_2
    VelocityN --> PlayerN_1
    VelocityN --> PlayerN_2
    
    classDef server fill:#f96,stroke:#333,stroke-width:4px
    classDef proxy fill:#9cf,stroke:#333,stroke-width:2px
    classDef auth fill:#fcf,stroke:#333,stroke-width:2px
    classDef ecs fill:#ff9,stroke:#333,stroke-width:3px
    classDef system fill:#ffd,stroke:#333,stroke-width:2px
    classDef async fill:#e7e7e7,stroke:#333,stroke-width:2px
    
    class GameServer server
    class BevyMT ecs
    class IngressSys,CoreSys,GameSys,EgressSys system
    class Proxy1,Proxy2,ProxyN proxy
    class Velocity1,Velocity2,VelocityN auth
    class TokioIO async

Proxy

sequenceDiagram
    participant P as Player
    participant PH as Proxy Handler
    participant B as Broadcast System
    participant S as Game Server

    Note over P,S: Player → Server Flow
    P->>PH: Player Packet
    PH->>S: Forward Immediately

    Note over P,S: Server → Player Flow
    S->>B: Server Packets

    Note over B: Broadcasting Decision
    alt Local Broadcast
        B->>P: Send to nearby players (BVH)
    else Channel Broadcast
        B->>P: Send to subscribed players
    else Global Broadcast
        B->>P: Send to all players
    else Unicast
        B->>P: Send to specific player
    end

Running

Network topology

Hyperion uses one game server which runs all game-related code (e.g. physics, game events). One or more proxies can connect to the game server. Players connect to one of the proxies.

For development and testing purposes, it is okay to run one game server and one proxy on the same server. When generating keys, you will need to change the key and certificate file names used below to avoid file name conflicts.

On a production environment, the game server and each proxy should run on separate servers for performance.

Generating keys and certificates

The connection between the game server and the proxies are encrypted through mTLS to ensure that the connection is secure and authenticate the proxies.

[!WARNING] All private keys must be stored securely, and it is strongly recommended to generate the private keys on the server that will use them instead of transferring them over the Internet. Malicious proxies that have access to a private key can circumvent player authentication and can cause the game server to exhibit undefined behavior which can potentially lead to arbitrary code execution on the game server. If any private key has been compromised, redo this section to create new keys.

Create a private certificate authority (CA)

A server should be picked to store the certificate authority keys and will be referred to as the cetificate authority server. Since the game server and all proxies are considered to be trusted, any of these servers may be used for this purpose.

On the certificate authority server, generate a key and certificate by running:

openssl req -new -nodes -newkey rsa:4096 -keyout root_ca.pem -x509 -out root_ca.crt -days 365

OpenSSL will ask for information when running the command. All fields can be left empty.

The -days field specifies when the certificate will expire. It will expire in 365 days in the above command, but this can be modified as needed.

root_ca.crt is the root CA cert and should be copied to the game server and all proxy servers. When running the game server or the proxy, make sure to pass --root-ca-cert root_ca.crt as a command line flag.

Generate server keys and certificates

Follow these instructions for the game server and each proxy server. The server will be referred to as the target server.

On the target server, run:

openssl req -nodes -newkey rsa:4096 -keyout server_private_key.pem -out server.csr

OpenSSL will ask for information when running the command. All fields can be left empty.

Afterwards, transfer server.csr to the certificate authority server. On the certificate authority server, run:

openssl x509 -req -in server.csr -CA root_ca.crt -CAkey root_ca.pem -CAcreateserial -out server.crt -days 365 -sha256 -extfile <(printf "subjectAltName=DNS:example.com,IP:127.0.0.1")

Replace example.com with the target server's domain name and replace 127.0.0.1 with the IP address that will be used by other servers to connect to the target server. If the IP or domain provided is incorrect, connections will fail with the error "invalid peer certificate: certificate not valid for name ...".

The -days field specifies when the certificate will expire. It will expire in 365 days in the above command, but this can be modified as needed.

Then, transfer server.crt to the target server.

server.csr and server.crt on the certificate authority server and server.csr on the target server are no longer needed and may be deleted.

server.crt is the target server's certificate and server_private_key.pem is the target server's private key. When running the game server or the proxy, make sure to pass --cert server.crt --private-key server_private_key.pem as a command line flag.

Without cloning

nix run github:hyperion-mc/hyperion#bedwars
nix run github:hyperion-mc/hyperion#hyperion-proxy

From a clone

The game server and the proxy are two processes that authenticate to each other with mTLS, so generate throwaway development certificates once:

nix run .#certs

Then run the event you want. Each event under events/ is its own run app that supervises the whole stack with process-compose: the proxy starts after the game server, each restarts on failure, and one Ctrl-C stops everything. Connect a Minecraft 1.20.1 client to localhost:25565.

nix run .#bedwars   # or: nix run .#smash

nix run with no target runs .#bedwars. Build optimised instead with HYPERION_PROFILE=release-full nix run .#bedwars.

Two checkouts on one machine both want 25565, 35565 and process-compose's own 8080. HYPERION_PLAYER_PORT and HYPERION_SERVER_PORT move the second one out of the way, and the process-compose port follows the player port:

HYPERION_PLAYER_PORT=25567 HYPERION_SERVER_PORT=35567 nix run .#bedwars

Point bots at it with nix run .#bots -- 127.0.0.1:25565 100.

Development

Every command is a flake app, so nix is the only thing you need installed.

nix build .#bedwars builds a release binary. nix run .#flake-gate is the whole nix gate: it builds every check the flake exposes, which is every app (proving each passes shellcheck and its tools resolve) plus the sandboxed end-to-end gates and the generated-source comparisons. Which of those CI enforces, and the named exceptions with the evidence behind each, is nix/ci/flake-gate.nix. If you would rather use cargo directly, nix develop gives you a shell with the pinned toolchain and the cargo subcommands the apps use.

Features

Language: Rust
Goal: Game engine for massive events
Structure: Bevy ECS

Platform Details:

• Version: Minecraft 1.20.1
• Proxy Support: Velocity
• Proximity Voice: Simple Voice Chat
• Max estimated player count: ~176,056

Note: This feature list represents core functionality. Hyperion is designed to be modular meaning you can implement your own mechanics and replace the core mechanics with your own.

Star History

Thank you for your hard work[^1] @CuzImClicks, @Indra-db, @james-j-obrien, @Ruben2424, @SanderMertens, @Tebarem, and @TestingPlant.

[^1]: alphabetically ordered