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 } = 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 } = 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('friends: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_updates:<userId>" topic to receive events about that user
const userChannel = socket.channel('user_updates:' + userId, {});
await userChannel.join();
userChannel.on('metadata_updated', (payload) => {
console.log('My metadata changed', payload);
});

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

// events forwarded from the server: user_joined, user_left, user_kicked, lobby_updated, host_changed
lobbyChannel.on('user_joined', ({ user_id }) => console.log('User joined', user_id));
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('lobby_updated', (lobby) => console.log('Lobby updated', lobby));
lobbyChannel.on('host_changed', ({ new_host_id }) => console.log('Host changed', new_host_id));

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.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": "/theme/theme.css",
  "logo": "/theme/logo.png",
  "banner": "/theme/banner.png"
}

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

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+ 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

Set the DATABASE_URL environment variable:

The app will automatically detect PostgreSQL when DATABASE_URL is set and contains "postgresql://".

You can also set individual database connection variables:

Popular PostgreSQL hosting options: