Elura

A modular Rust framework for online game servers.

Documentation · API reference · Crates.io

Elura separates client connections from game logic. Gateway processes own connections and sessions; World processes execute commands and manage player state. They can scale independently or run together as a monolith.

Features

TCP, UDP, WebSocket, WebTransport, and QUIC transports.
Distributed Gateway and World deployment, or a single-process monolith.
One-login HTTP access/refresh tokens with one-time ELR2 Session-ticket exchange.
Rooms, fixed-step simulation, AOI, replication, prediction, and lag compensation.
Optional Redis, SQL, Kubernetes, identity, notification, OTP, and payment integrations.

HTTP APIs alongside realtime connections

HTTP business APIs and ELR2 connections use separate credentials derived from one application login:

POST /elura/auth/login
  -> reusable HTTP access token
  -> rotating refresh token
  -> optional one-time Gateway login ticket

HTTP business request
  -> Authorization: Bearer <access token>

ELR2 connection
  -> AUTHENTICATE(<Gateway login or reconnect ticket>)

HttpAuthApi provides /elura/auth/login, /elura/auth/refresh, and /elura/game/session-ticket. With both the gateway and identity features enabled, IdentityHttpBackend connects the built-in IdentityService and its password, phone, OAuth2, WeChat, Douyin, and QuickSDK providers directly to this API. Applications implement only IdentityHttpPolicy to grant scopes and verify that a selected player belongs to the authenticated account. Custom identity systems can still implement HttpLoginBackend directly. HttpBearerAuth protects application-owned Axum routes such as payments, while the existing TCP, WebSocket, QUIC, and WebTransport Session flow remains unchanged.

let login_backend = Arc::new(IdentityHttpBackend::new(
    identity_service,
    Arc::new(GameIdentityPolicy::new(account_store)),
));
let auth_api = HttpAuthApi::new(http_tokens, tickets, shared_replay, login_backend);

The adapter performs existing-account login once. Registration and linking remain explicit application flows, which prevents one-time third-party authorization codes from being consumed twice by a fallback login-then-register sequence.

Refresh rotation uses the same ReplayStore contract as Gateway tickets. Inject a shared Redis implementation before running multiple HTTP or Gateway instances.

Mount the authentication API and protected business routes next to an existing realtime transport:

let payments = Router::new()
    .route("/elura/payments/orders", post(create_order))
    .route_layer(middleware::from_fn_with_state(
        auth_api.bearer_auth(),
        require_bearer,
    ));

Gateway::new(gateway_config)
    .replay_store(shared_replay.clone())
    .transport(TcpTransport::new(tcp_config)?)
    .http("0.0.0.0:8080", auth_api.router().merge(payments))
    .run(admin_config)
    .await?;

The HTTP listener and ELR2 listener are supervised together, but their authentication semantics remain independent. Payment handlers receive AuthenticatedHttp; realtime handlers continue to receive the server-owned ELR2 Session identity.

Quick start

Install the CLI and scaffold an application:

cargo install elura-cli --version 0.2.9
elura skill install
elura init all --dir .

Or add the framework directly:

[dependencies]
elura = "0.2.9"

The skill is installed in .agents/skills/elura-app-development for project-level coding agents. See the documentation for concepts, configuration, crate features, deployment, and tutorials.

Client SDKs

Generate standalone ELR2 client SDKs without depending on the server-side Elura crates:

elura init sdk --language rust --dir .
elura init sdk --language typescript --dir .
elura init sdk --language csharp --dir .
elura init sdk --language cpp --dir .

The Rust SDK is runtime-independent by default. Its frame encoding, authentication, reconnect, heartbeat, and Session Control APIs work without Tokio. WebSocket, UDP, and QUIC Datagram clients can use Elr2Codec::encode and Elr2Codec::decode directly.

Enable the optional tokio-codec feature when a Tokio byte stream needs ELR2 framing:

[dependencies]
elura-protocol = { path = "sdk/rust", features = ["tokio-codec"] }
futures-util = { version = "0.3", features = ["sink"] }
tokio = { version = "1", features = ["net", "macros", "rt-multi-thread"] }
tokio-util = { version = "0.7", features = ["codec"] }

use elura_protocol::Elr2Codec;
use tokio::net::TcpStream;
use tokio_util::codec::Framed;

let stream = TcpStream::connect(gateway_address).await?;
let connection = Framed::new(stream, Elr2Codec::default());

See tiny-network-game for authentication, request timeouts, reconnects, and application-route calls over Framed<TcpStream, Elr2Codec>.

Examples

tiny-network-game: an authoritative multiplayer movement demo.
realtime-gameplay: a transport-neutral gameplay pipeline walkthrough.

Development

Rust 1.97 or newer is required. Run the full verification suite with:

make verify

This checks formatting, Clippy, tests, Rustdoc, and package contents.

License

Elura is dual-licensed under your choice of:

elura-netcode 0.2.9