Setup & Guides

Install the package via npm:

Import and configure the API client:

const { ApiClient, HealthApi, AuthenticationApi, UsersApi } = require('@ughuuu/game_server');

// Initialize the API client
const apiClient = new ApiClient();
apiClient.basePath = 'http://localhost:4000';

Test your connection with a health check:

const healthApi = new HealthApi(apiClient);

const healthResponse = await healthApi.index();
console.log('Server is healthy:', healthResponse);

The API uses JWT tokens. Here's how to authenticate:

Email/Password Login:

const authApi = new AuthenticationApi(apiClient);

const loginResponse = await authApi.login({
  loginRequest: {
    email: 'user@example.com',
    password: 'password123'
  }
});

const { access_token, refresh_token, user_id } = loginResponse.data;

OAuth Flow (Discord, Google, Facebook):

// Step 1: Get authorization URL
const authResponse = await authApi.oauthRequest('discord');
const authUrl = authResponse.authorization_url;
const sessionId = authResponse.session_id;

// Step 2: Open URL in browser for user to authenticate
window.open(authUrl, '_blank');

// Step 3: Poll for completion
let sessionData;
do {
  await new Promise(resolve => setTimeout(resolve, 1000));
  sessionData = await authApi.oauthSessionStatus(sessionId);
} while (sessionData.status === 'pending');

  if (sessionData.status === 'completed') {
  const { access_token, refresh_token, user_id } = sessionData.data;
  console.log('OAuth successful!');
}

Using Access Tokens:

// Set authorization header for authenticated requests
apiClient.defaultHeaders = {
  'Authorization': `Bearer ${access_token}`
};

Get User Profile:

const usersApi = new UsersApi(apiClient);

const userProfile = await usersApi.getCurrentUser(`Bearer ${access_token}`);
console.log('User:', userProfile.data);

Refresh Token:

const refreshResponse = await authApi.refreshToken({
    refreshTokenRequest: {
    refresh_token: refresh_token
  }
});

const newAccessToken = refreshResponse.data.access_token;

Logout:

await authApi.logout(`Bearer ${access_token}`);
console.log('Logged out successfully');

Handle common errors appropriately:

try {
  const result = await someApiCall();
} catch (error) {
  if (error.status === 401) {
    // Token expired, refresh or re-authenticate
    console.log('Token expired');
  } else if (error.status === 403) {
    // Forbidden - insufficient permissions
    console.log('Access denied');
  } else if (error.status === 404) {
    // Resource not found
    console.log('Not found');
  } else {
    // Other errors
    console.error('API Error:', error);
  }
}

Work with lobbies for multiplayer matchmaking:

List Available Lobbies

const { LobbiesApi } = require('@ughuuu/game_server');
const lobbiesApi = new LobbiesApi(apiClient);

// List all public lobbies - note: the SDK returns the array directly
const lobbies = await lobbiesApi.listLobbies();
console.log('Available lobbies:', lobbies);

// Search lobbies by name/title
const searchResults = await lobbiesApi.listLobbies({ q: 'deathmatch' });
console.log('Search results:', searchResults);

Create a Lobby

// Create a new lobby (requires authentication via Authorization: Bearer <token>)
const newLobby = await lobbiesApi.createLobby({
title: 'My Game Room',
max_users: 4,
is_hidden: false,
metadata: { game_mode: 'deathmatch' }
});
// SDK returns the created lobby object directly
console.log('Created lobby:', newLobby);

Join / Leave

// Join a lobby by ID (authenticated)
await lobbiesApi.joinLobby(lobbyId);

// Join a password-protected lobby
await lobbiesApi.joinLobby(lobbyId, { password: 'secret123' });

// Leave the current lobby (authenticated)
await lobbiesApi.leaveLobby();
console.log('Left the lobby');

Update & Kick (host only)

// Update lobby settings (host only)
await lobbiesApi.updateLobby({
title: 'Updated Room Name',
max_users: 8,
is_locked: true
});

// Kick a user (host only)
await lobbiesApi.kickUser(123);
console.log('User kicked from lobby');

Friends

    // Send a friend request
const { FriendsApi } = require('@ughuuu/game_server');
const friendsApi = new FriendsApi(apiClient);

await friendsApi.create({ target_user_id: someOtherUserId });

// List my friends
const friends = await friendsApi.listFriends();
console.log('Friends:', friends);

// Subscribe to real-time friend events via phoenix channels on socket
const socket = new Socket('/socket', { params: { token: accessToken } });
socket.connect();
const userChannel = socket.channel('user:' + userId, {});
await userChannel.join();
userChannel.on('friend_blocked', payload => console.log('Blocked:', payload));
userChannel.on('friend_unblocked', payload => console.log('Unblocked:', payload));

Realtime / subscribing to events

// The server exposes real-time events via Phoenix channels on the same socket
// (you must pass a valid JWT token when connecting).

// Using the phoenix JS client (https://www.npmjs.com/package/phoenix)
import { Socket } from 'phoenix';

const socket = new Socket('/socket', { params: { token: accessToken } });
socket.connect();

// === per-user updates ===
// join the "user:<userId>" topic to receive events about that user
const userChannel = socket.channel('user:' + userId, {});
await userChannel.join();
userChannel.on('updated', (payload) => {
console.log('My metadata changed', payload);
});

// === per-lobby updates ===
// join "lobby:<lobbyId>" to receive membership and lobby events
const lobbyChannel = socket.channel('lobby:' + lobbyId, {});
await lobbyChannel.join();

// Events forwarded from the server on the lobby:<id> channel:
// - 'user_joined'  => { user_id }
// - 'user_left'    => { user_id }
// - 'user_kicked'  => { user_id }
// - 'updated' => lobby object (full lobby payload, contains fields like title, max_users, metadata, etc.)
// - 'host_changed' => { new_host_id }

lobbyChannel.on('user_joined', ({ user_id }) => {
  console.log('User joined lobby', user_id)
})

lobbyChannel.on('user_left', ({ user_id }) => {
  console.log('User left lobby', user_id)
})

lobbyChannel.on('user_kicked', ({ user_id }) => {
  console.warn('User kicked from lobby', user_id)
})

// updated contains the full, serialized lobby object. To detect specific
// field changes (title changed, max_users changed, etc.) compare with the
// previous lobby state you have stored in the client.
let currentLobbyState = null
lobbyChannel.on('updated', (lobby) => {
  console.log('Lobby updated', lobby)

  if (currentLobbyState) {
    if (lobby.title !== currentLobbyState.title) {
      console.log('Lobby title changed:', currentLobbyState.title, '->', lobby.title)
    }
    if (lobby.max_users !== currentLobbyState.max_users) {
      console.log('Lobby max_users changed:', currentLobbyState.max_users, '->', lobby.max_users)
    }
    // Add any other field checks you care about here (is_locked, metadata, host_id, ...)
  }

  // Save latest state
  currentLobbyState = lobby
})

lobbyChannel.on('user_left', ({ user_id }) => console.log('User left', user_id));
lobbyChannel.on('user_kicked', ({ user_id }) => console.warn('You were kicked', user_id));
lobbyChannel.on('host_changed', ({ new_host_id }) => {
  console.log('Lobby host changed ->', new_host_id)
})
lobbyChannel.on('updated', (lobby) => console.log('Lobby updated', lobby));
lobbyChannel.on('host_changed', ({ new_host_id }) => console.log('Host changed', new_host_id));

Display leaderboards and player rankings (read-only from client, scores are submitted server-side):

List Leaderboards

const { LeaderboardsApi } = require('@ughuuu/game_server');
const leaderboardsApi = new LeaderboardsApi(apiClient);

// List all leaderboards (paginated)
const leaderboards = await leaderboardsApi.listLeaderboards({ page: 1, pageSize: 25 });
console.log('Leaderboards:', leaderboards.data);

// Filter to only active leaderboards
const activeOnly = await leaderboardsApi.listLeaderboards({ active: true });

Get Leaderboard Records

// Get top records for a leaderboard
const records = await leaderboardsApi.getLeaderboardRecords('weekly_score_2024_w48', {
  page: 1,
  pageSize: 25
});
console.log('Top players:', records.data);
// Each record includes: rank, user_id, display_name, score, metadata

// Get records around a specific user (for context)
const aroundMe = await leaderboardsApi.getRecordsAroundUser('weekly_score_2024_w48', userId, {
  limit: 5
});
console.log('Players around me:', aroundMe.data);

Get My Record (requires auth)

// Get current user's record with rank
const myRecord = await leaderboardsApi.getMyRecord('weekly_score_2024_w48');
if (myRecord.data) {
  console.log('My rank:', myRecord.data.rank);
  console.log('My score:', myRecord.data.score);
}

Download the Godot asset from the Asset Library (in Godot look for the "Gamend - Game Server" addon):

Typical usage inside Godot GDScript (pseudocode / example):

var gamend_api:= GamendApi.new()
var access_token := ""
var refresh_token := ""

# This function will be reused in future examples
func print_error_or_result(response: GamendResult):
	if response.error:
		print(response.error)
	else:
		print(response.response)

func _ready() -> void:
	var response :GamendResult= await gamend_api.health_index().finished
	print_error_or_result(response)

Authenticate using the same JWT-based API flow as other SDKs (get token from server login / OAuth).

var gamend_api:= GamendApi.new()
var access_token := ""
var refresh_token := ""

func _ready() -> void:
    # Request OAuth URL, open browser and login
    do_discord_auth()

	gamend_api.authorize(access_token)

func do_discord_auth():
	var response = await gamend_api.authenticate_oauth_request(GamendApi.PROVIDER_DISCORD).finished
	print_error_or_result(response)
	
	var authorization_url = response.response.data.authorization_url
	var session_id :String = response.response.data.session_id

	# Opening Auth URL
	OS.shell_open(authorization_url)
	for i in 60:
		print("CHECKING SESSION: ", session_id)
		response = await gamend_api.authenticate_oauth_session_status(session_id).finished
		print_error_or_result(response)
		if response.response.data.status == "completed":
			break

	access_token = response.response.data.data.access_token
	refresh_token = response.response.data.data.refresh_token

After logging in, you can now call any RPC or other protected functions.

var gamend_api:= GamendApi.new()

func _ready() -> void:
    # From previous example
    gamend_api.authorize(access_token)
    # ...
	
	response = await gamend_api.users_get_current_user().finished
	print_error_or_result(response)
	
	var call_hook := CallHookRequest.new()
  call_hook.plugin = "polyglot_hook"
	call_hook.fn = "hello"
	call_hook.args = ["1"]
	response = await gamend_api.hooks_call_hook(call_hook).finished
	print_error_or_result(response)

Place a JSON file somewhere in your project, for example:

theme/default_config.json

With the following:

{
  "title": "My Game",
  "tagline": "Play together",
  "css": "/assets/css/theme/theme.css",
  "logo": "/theme/logo.png",
  "banner": "/theme/banner.png"
}

The project uses an umbrella split to keep the domain logic, web UI, and the runnable application separate. This allows you to create custom hosts — standalone OTP applications that start the server with your own routes, pages, and supervision tree additions.

apps/
  game_server_core/     # Domain logic (schemas, contexts, migrations)
                        # No web dependency. Reusable across hosts.
  game_server_web/      # UI library (controllers, LiveViews, components,
                        # channels, endpoint). Does NOT start itself.
  game_server_host/     # Default runnable host. Starts the supervision tree.
                        # Extension point for forks.

The endpoint doesn't hardcode a router. Instead, it reads the router module from application config at runtime:

# GameServerWeb.Endpoint reads this at request time:
router = Application.get_env(:game_server_web, :router, GameServerWeb.Router)

# The host app sets it at boot:
Application.put_env(:game_server_web, :router, MyHost.Router, persistent: true)

This means the host controls routing without game_server_web knowing about it. You can add, remove, or replace any routes.

When multiple players trigger the same RPC concurrently (e.g. guessing a word, claiming a reward), you need to serialize access to shared state. GameServer.Lock wraps your code in a database advisory lock so only one process at a time executes for a given (namespace, resource_id) pair.

# In your hooks module RPC:
def rpc("word_guessed", [word], caller) do
  lobby_id = caller.lobby_id

  GameServer.Lock.serialize("word_guessed", lobby_id, fn ->
    # Only one process per lobby reaches here at a time
    {:ok, entry} = GameServer.KV.get("game_state", lobby_id: lobby_id)
    new_val = Map.update(entry.value, "guessed", [word], &[word | &1])
    GameServer.KV.put("game_state", new_val, %{}, lobby_id: lobby_id)
  end)
end

The namespace can be a predefined atom ( :lobby, :group, :party ) or any arbitrary string. Strings are hashed to stable integers to avoid collisions.

• Your custom routes are matched before upstream routes because they appear first in the router. If you want to replace an upstream page (e.g. the home page), just define the same path.
• Use forward \"/\", GameServerWeb.Router as the last line to delegate all unmatched routes. Remove it if you want to strip the upstream UI entirely.
• The upstream UI uses route helpers pointing at GameServerWeb.Router. If you remove routes that the UI links to, you'll get dead links — adjust the UI templates or provide replacement routes.
• To add your LiveViews alongside the upstream nav, you can customize layouts.ex in your host or override it via a template in your host's priv/static.
• All SDK context modules (Accounts, Lobbies, KV, Lock, etc.) work the same in any host — they operate on the shared database.

You need an Apple Developer Account ($99/year)

Go to Certificates, Identifiers & Profiles

1. Click the "+" button to create a new identifier
2. Select "App IDs" and click Continue
3. Select "App" type and click Continue
4. Enter a description (e.g., "Game Server")
5. Enter a Bundle ID (e.g., com.yourcompany.gameserver)
6. Scroll down and check "Sign in with Apple"
7. Click Continue and Register

Back in Certificates, Identifiers & Profiles:

1. Click "+" to create new identifier
2. Select "Services IDs" and click Continue
3. Enter description (e.g., "Game Server Web")
4. Enter identifier (e.g., com.yourcompany.gameserver.web) - This is your CLIENT_ID
5. Check "Sign in with Apple"
6. Click "Configure" next to Sign in with Apple
7. Select your App ID as the Primary App ID
8. Add these domains and redirect URLs:
   
   Domain: example.com

   Return URL: https://example.com/auth/apple/callback
9. Click Save, then Continue, then Register

In Certificates, Identifiers & Profiles, go to Keys:

1. Click "+" to create a new key
2. Enter a name (e.g., "Game Server Sign in with Apple Key")
3. Check "Sign in with Apple"
4. Click "Configure" next to Sign in with Apple
5. Select your App ID as the Primary App ID
6. Click Save, then Continue
7. Click Register
8. Download the .p8 file - you can only download this once!
9. Note the Key ID (e.g., ABC123XYZ) shown on the confirmation page

Find your Team ID:

1. Go to Membership Details
2. Your Team ID is listed there (10 characters, e.g., A1B2C3D4E5)

Set these environment variables:

After deploying with the secrets:

1. Go to your app's login page
2. Click "Sign in with Apple"
3. Authorize the application with your Apple ID
4. You should be redirected back and logged in

Place them under the web app's static folder so they are served at the web root:

Example files are included in the repo with a .example suffix.

• Served at: https://your-domain/.well-known/assetlinks.json and https://your-domain/.well-known/apple-app-site-association
• After adding or updating these files, restart or redeploy so they are included in the release

Visit the Steam Web API page at https://steamcommunity.com/dev and register your domain to get an API key.

Steam uses OpenID for sign-in. When registering your domain at steamcommunity.com/dev , enter your domain (e.g., example.com for production or localhost:4000 for development).

Set the following environment variable:

After configuring the API key:

1. Go to your app's login page
2. Click "Sign in with Steam"
3. Authorize with your Steam account
4. You should be redirected back and logged in

Note: For linking Steam to an existing account, go to /users/settings and click "Link Steam".

Go to the Discord Developer Portal

1. Click "New Application" in the top right
2. Give your app a name (e.g., "Game Server")
3. Go to the "OAuth2" → "General" tab

In the OAuth2 General settings, add these redirect URIs:

These are the URLs Discord will redirect users back to after authorization.

From the OAuth2 General tab, copy these values:

Set these environment variables:

After deploying with the secrets:

1. Go to your app's login page
2. Click "Sign in with Discord"
3. Authorize the application on Discord
4. You should be redirected back and logged in

Go to the Google Cloud Console

1. Click "Select a project" at the top
2. Click "New Project"
3. Enter a project name (e.g., "Game Server")
4. Click "Create"

In your Google Cloud project:

1. Go to "APIs & Services" → "Library"
2. Search for "Google People API"
3. Click on it and click "Enable"

Go to "APIs & Services" → "OAuth consent screen":

1. Select "External" user type
2. Click "Create"
3. Fill in app name (e.g., "Game Server")
4. Add your email as user support email
5. Add authorized domains (e.g., example.com)
6. Add developer contact email
7. Click "Save and Continue"
8. Add scopes: email, profile
9. Click "Save and Continue"
10. Add test users if needed (optional for development)

Go to "APIs & Services" → "Credentials":

1. Click "Create Credentials" → "OAuth client ID"
2. Select "Web application"
3. Enter a name (e.g., "Game Server Web")
4. Add authorized redirect URIs:
   
   Development: http://localhost:4000/auth/google/callback

   Production: https://example.com/auth/google/callback
5. Click "Create"
6. Copy the Client ID and Client Secret

Set these environment variables:

After deploying with the secrets:

1. Go to your app's login page
2. Click "Sign in with Google"
3. Choose your Google account
4. You should be redirected back and logged in

Go to the Facebook Developers Portal

1. Click "My Apps" in the top right
2. Click "Create App"
3. Select the use case that fits your needs (often "Other" or "Authenticate and request data from users with Facebook Login")
4. Click "Next"
5. Select app type (usually "Business" for most web apps, or "None" if available)
6. Click "Next"
7. Enter app name (e.g., "Game Server")
8. Enter contact email
9. Click "Create App"

In your Facebook App dashboard:

1. Find "Facebook Login" in the product list
2. Click "Set Up"
3. Select "Web" as the platform
4. Enter your site URL (e.g., https://example.com)
5. Click "Save" and continue

Go to "Facebook Login" → "Settings":

1. Add these Valid OAuth Redirect URIs:
   
   Development: http://localhost:4000/auth/facebook/callback

   Production: https://example.com/auth/facebook/callback
2. Click "Save Changes"

Go to "Settings" → "Basic":

1. Copy the "App ID" (this is your Client ID)
2. Click "Show" next to "App Secret" and copy it (this is your Client Secret)

For production use, switch to live mode:

1. Complete all required fields in "Settings" → "Basic"
2. Add a Privacy Policy URL
3. Add a Terms of Service URL (optional)
4. Select a category for your app
5. Toggle the switch at the top from "Development" to "Live"

Set these environment variables:

After deploying with the secrets:

1. Go to your app's login page
2. Click "Sign in with Facebook"
3. Authorize the application with your Facebook account
4. You should be redirected back and logged in

Recommended providers:

Set these environment variables based on your provider:

For other providers, adjust the SMTP settings accordingly. The app will automatically detect when email is configured.

Go to the Sentry Dashboard

1. Sign up or log in to Sentry
2. Create a new project
3. Select "Phoenix" or "Elixir" as the platform
4. Name your project (e.g., "Game Server")

After creating the project, copy the DSN from the settings:

1. Go to Project Settings → Client Keys (DSN)
2. Copy the DSN value

Set the SENTRY_DSN environment variable:

After deploying with the DSN:

1. Deploy your application
2. Check the admin config page - Sentry should show as "Configured"
3. Test error reporting by running: mix sentry.send_test_event
4. Check your Sentry dashboard for the test event

By default, production runs a single-level local cache (fastest for a single instance).

Tip: CACHE_L2 only matters when CACHE_MODE=multi.

Use a single local cache level:

Enable a two-level cache: L1 local + L2 shared/sharded.

Redis is shared across nodes. Partitioned requires Erlang clustering between nodes.

If you use CACHE_L2=partitioned, nodes must be able to connect to each other via Erlang distribution.

Notes: All nodes must share the same RELEASE_COOKIE, and each node must have a unique RELEASE_NODE. If you use CACHE_L2=redis, you typically do not need Erlang clustering.

Single instance is the simplest and the default. When you scale out to multiple instances, you typically need:

• A shared database (PostgreSQL recommended)
• A shared cache (Redis recommended since L2 doesn't require Erlang distribution)

Docker Compose is a simple way to run the app with PostgreSQL and Redis.

If you want to use CACHE_L2=partitioned under Compose, you also need to configure Erlang distribution + node discovery for your app containers.

Set the DATABASE_URL environment variable:

The app will automatically detect PostgreSQL when DATABASE_URL is set or when POSTGRES_HOST and POSTGRES_USER environment variables are configured.

You can also set individual database connection variables:

Popular PostgreSQL hosting options: