Comprehensive guide to integrating Epic Online Services (EOS) with the Supabase UE5 Plugin. Covers EOS-powered authentication, presence, leaderboards, achievements, and player data storage for games published on the Epic Games Store and other EOS-supported platforms.
Epic Online Services (EOS) is Epic's cross-platform online service suite that provides authentication, social features, and backend services for games. The Supabase UE5 Plugin's EOS integration allows you to combine EOS services with Supabase's backend, letting you use EOS for platform-level features while leveraging Supabase for flexible data storage, real-time capabilities, and more.
The integration provides a unified layer that handles:
| EOS Service | Description |
|---|---|
| Authentication | Sign in players via EOS Connect, retrieve exchange codes, and pass EOS identity to Supabase |
| Presence & Social | Query and display friend presence, status, and rich presence data |
| Leaderboards | Read and write EOS leaderboard scores |
| Achievements | Unlock and query EOS achievements through the plugin |
| Player Data Storage | Store and retrieve cloud save data using EOS Player Data Storage API |
This means you can authenticate players through EOS (required for EGS titles), use EOS leaderboards for competitive features, and still have full access to Supabase's PostgreSQL database, real-time subscriptions, and edge functions.
Before enabling EOS integration, ensure you have the following:
| Requirement | Details |
|---|---|
| OnlineSubsystemEOS | The EOS Online Subsystem plugin must be enabled in your project. Available in UE5 by default. |
| EOS SDK | The Epic Online Services SDK must be installed and configured. See the Epic Games documentation for setup instructions. |
| EOS Connect Authentication | Players must be authenticated with EOS Connect before using EOS features. This is handled automatically by the OnlineSubsystem when the game launches through the Epic Games Launcher. |
| Supabase Project with EOS Auth Provider | Your Supabase project must have the EOS auth provider enabled. Configure this in the Supabase dashboard under Authentication > Providers > Epic Games. |
| EOS Product ID & Sandbox ID | You need valid EOS credentials from the Epic Games Developer Portal. |
| Supabase UE5 Plugin | v1.6.1 or later with EOS integration module included. |
Enable the EOS auth provider in your Supabase project:
EOS integration is controlled by a flag in the plugin's own Supabase.Build.cs. When enabled, the plugin compiles EOS code and adds the required module dependencies. Your project must also have the EOS Online Subsystem plugin enabled.
In the plugin's Source/Supabase/Supabase.Build.cs, set the EOS integration flag:
// In Source/Supabase/Supabase.Build.cs
bool bEnableEOSIntegration = true; // Flip to true to enable
When bEnableEOSIntegration is true, the plugin automatically:
WITH_EOS_SDK and SUPABASE_EOS_INTEGRATION preprocessor macrosOnlineSubsystem, OnlineSubsystemUtils, OnlineServices, and OnlineSubsystemEOS as dependenciesYour project only needs to depend on the Supabase module:
public class MyProject : ModuleRules
{
public MyProject(ReadOnlyTargetRules Target) : base(Target)
{
PublicDependencyModuleNames.AddRange(new string[]
{
"Supabase",
});
}
}
Note: There is no separate
SupabaseEOSmodule. All EOS code lives within theSupabasemodule and is conditionally compiled.
Ensure the required plugins are listed in your .uproject file:
{
"Plugins": [
{
"Name": "OnlineSubsystemEOS",
"Enabled": true
},
{
"Name": "OnlineSubsystemUtils",
"Enabled": true
},
{
"Name": "Supabase",
"Enabled": true
}
]
}
Configure the EOS Online Subsystem in your DefaultEngine.ini:
[/Script/Engine.GameEngine]
+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemEOS.NetDriverEOS",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")
[OnlineSubsystemEOS]
bEnabled=true
bUseEAS=true
bUseEOSConnect=true
CacheDir=CacheDir
[OnlineSubsystem]
DefaultPlatformService=EOS
| Setting | Type | Description |
|---|---|---|
bEnabled |
bool | Enables the EOS Online Subsystem |
bUseEAS |
bool | Enables Epic Account Services |
bUseEOSConnect |
bool | Enables EOS Connect authentication |
DefaultPlatformService |
string | Set to EOS to use EOS as the default online platform |
EOS integration code is conditionally compiled using preprocessor directives. This ensures your project compiles cleanly on platforms or configurations where EOS is not available:
#if WITH_EOS_SDK && SUPABASE_EOS_INTEGRATION
// EOS-specific code here
#include "EOS/SupabaseEOSIntegration.h"
void AMyPlayerController::BeginPlay()
{
Super::BeginPlay();
// Create and initialize EOS integration
USupabaseEOSIntegration* EOSIntegration = NewObject<USupabaseEOSIntegration>();
if (EOSIntegration->Initialize())
{
UE_LOG(LogTemp, Log, TEXT("EOS Platform initialized."));
}
}
#else
// Fallback for non-EOS builds
UE_LOG(LogTemp, Warning, TEXT("EOS integration not available in this build configuration."));
#endif
| Preprocessor Macro | Defined By | Description |
|---|---|---|
WITH_EOS_SDK |
Plugin Build.cs | Defined when bEnableEOSIntegration is true in Supabase.Build.cs |
SUPABASE_EOS_INTEGRATION |
Plugin Build.cs | Defined when bEnableEOSIntegration is true in Supabase.Build.cs |
Tip: Use these guards in any C++ code that references EOS types or headers. The plugin's Blueprint nodes for EOS features are automatically hidden when EOS is not available.
EOS authentication allows players to sign in through the Epic Games Launcher or EOS Connect. The plugin retrieves an EOS exchange code that can be passed to Supabase's LoginWithEOS() method for database access control.
| Capability | Description |
|---|---|
| EOS Platform Init | Initialize and shut down the EOS Platform |
| Exchange Code Retrieval | Authenticate via EOS and retrieve exchange codes |
| Supabase Token Exchange | Pass exchange codes to Supabase for JWT-based authentication |
| Auth Result Callbacks | FOnEOSAuthComplete delegate with full result data |
Quick Start:
#if WITH_EOS_SDK && SUPABASE_EOS_INTEGRATION
#include "EOS/SupabaseEOSIntegration.h"
// Create and initialize EOS integration
USupabaseEOSIntegration* EOSAuth = NewObject<USupabaseEOSIntegration>();
EOSAuth->Initialize();
// Bind to auth completion
EOSAuth->OnAuthComplete.AddLambda([](const FEOSAuthResult& Result)
{
if (Result.bWasSuccessful)
{
UE_LOG(LogTemp, Log, TEXT("EOS auth successful. Exchange Code: %s"), *Result.ExchangeCode);
// Pass Result.ExchangeCode to Supabase LoginWithEOS()
}
else
{
UE_LOG(LogTemp, Warning, TEXT("EOS auth failed: %s"), *Result.ErrorMessage);
}
});
// Trigger authentication
EOSAuth->Authenticate();
#endif
See the EOS Authentication page for full details.
Query and display player presence information from EOS, including online status, rich presence data, and friend lists.
| Capability | Description |
|---|---|
| Query Presence | Get online/offline/busy status of players |
| Rich Presence | Set and display custom presence data |
| Friend List | Retrieve the authenticated player's EOS friend list |
| Presence Subscriptions | Subscribe to real-time presence change notifications |
Quick Start:
#if WITH_EOS_SDK && SUPABASE_EOS_INTEGRATION
#include "EOS/SupabaseEOSPresence.h"
// Query a player's presence
USupabaseEOSPresence::QueryPresence(
TargetProductId,
TargetUserId,
FOnPresenceChanged::CreateLambda([](const FEOSPresenceData& PresenceData)
{
UE_LOG(LogTemp, Log, TEXT("Player status: %d"), (int32)PresenceData.Status);
UE_LOG(LogTemp, Log, TEXT("Rich Presence: %s"), *PresenceData.RichPresenceText);
})
);
#endif
See the Presence & Social page for full details.
Read and write leaderboard scores using EOS leaderboards.
| Capability | Description |
|---|---|
| Query Leaderboards | Fetch global, user, or filtered leaderboard rankings |
| Submit Scores | Upload player scores to EOS leaderboards |
| Leaderboard Definitions | Query available leaderboard definitions |
Status: This feature is in Preview. The API surface may change between minor versions. Recommended for testing and prototyping only.
Quick Start:
#if WITH_EOS_SDK && SUPABASE_EOS_INTEGRATION
#include "EOS/SupabaseEOSLeaderboards.h"
// Query a leaderboard
USupabaseEOSLeaderboards::QueryLeaderboard(
LeaderboardId,
FOnLeaderboardQueried::CreateLambda([](const TArray<FEOSLeaderboardRecord>& Records)
{
for (const auto& Record : Records)
{
UE_LOG(LogTemp, Log, TEXT("#%d: %s - Score: %d"),
Record.Rank, *Record.PlayerName, Record.Score);
}
})
);
#endif
See the Leaderboards page for full details.
Unlock and query achievements defined in the EOS Achievements interface.
| Capability | Description |
|---|---|
| Unlock Achievement | Unlock an achievement for the authenticated player |
| Query Achievements | Fetch the player's achievement progress |
| Achievement Definitions | Retrieve achievement metadata |
| Progress Tracking | Track incremental achievement progress |
Status: This feature is in Alpha. Expect breaking changes, limited functionality, and potential instability. Not recommended for production use.
Quick Start:
#if WITH_EOS_SDK && SUPABASE_EOS_INTEGRATION
#include "EOS/SupabaseEOSAchievements.h"
// Unlock an achievement (static method)
USupabaseEOSAchievements::UnlockAchievement(
AchievementId,
FSimpleDelegate::CreateLambda([]()
{
UE_LOG(LogTemp, Log, TEXT("Achievement unlocked!"));
}),
FSupabaseErrorDelegate::CreateLambda([](const FString& Error)
{
UE_LOG(LogTemp, Warning, TEXT("Failed to unlock achievement: %s"), *Error);
})
);
#endif
See the Achievements page for full details.
Store and retrieve cloud save data using EOS Player Data Storage, with P2P replication for offline availability.
| Capability | Description |
|---|---|
| Write Data | Save key-value data to EOS Player Data Storage |
| Read Data | Retrieve stored data by key |
| Delete Data | Remove stored data entries |
| Query Available Data | List all keys with metadata (size, timestamps) |
Note: Player Data Storage uses EOS's built-in P2P replication. Data is available offline and synced when connectivity is restored.
Quick Start:
#if WITH_EOS_SDK && SUPABASE_EOS_INTEGRATION
#include "EOS/SupabaseEOSPlayerData.h"
// Write player data
USupabaseEOSPlayerData::WritePlayerData(
"PlayerSettings",
"{\"volume\":0.8,\"difficulty\":\"hard\"}",
FSimpleDelegate::CreateLambda([]()
{
UE_LOG(LogTemp, Log, TEXT("Player data saved."));
}),
FSupabaseErrorDelegate::CreateLambda([](const FString& Error)
{
UE_LOG(LogTemp, Warning, TEXT("Failed to save: %s"), *Error);
})
);
#endif
See the Player Data Storage page for full details.
| Feature | Status | Stability | Production Ready |
|---|---|---|---|
| Authentication | Stable | Full API stability | Yes |
| Presence & Social | Stable | Full API stability | Yes |
| Leaderboards | Preview | Minor changes possible | Testing / prototyping |
| Achievements | Alpha | Breaking changes expected | Not recommended |
| Player Data Storage | Stable | Full API stability | Yes |
EOS SDK Version Compatibility: The plugin is tested against specific EOS SDK versions. Check the release notes for the current supported version. Using a mismatched SDK version may cause compilation or runtime errors.
Preview and Alpha Features: Leaderboards (Preview) and Achievements (Alpha) are under active development. APIs may change between versions without a deprecation period. Pin your plugin version if you depend on these features.
Platform Requirements: EOS integration requires the EOS Online Subsystem, which is only available on desktop platforms (Windows, macOS, Linux) and console platforms with EOS support. Mobile platforms may have limited functionality.
Conditional Compilation: Always guard EOS-specific code with #if WITH_EOS_SDK && SUPABASE_EOS_INTEGRATION to ensure your project compiles on all target platforms and configurations.
EOS Connect is Required: All EOS features require a valid EOS Connect authentication. If the player is not authenticated with EOS Connect, EOS features will return errors or default values.
Supabase Auth Provider: The EOS auth provider must be enabled in your Supabase project dashboard before authentication will work. Without this, token exchange will fail.
Build.cs Flag Location: The bEnableEOSIntegration flag is set in the plugin's Supabase.Build.cs (located at Source/Supabase/Supabase.Build.cs), not in your project's Build.cs. This is a plugin-internal compilation flag.
Object-Based API: USupabaseEOSIntegration is a UObject (not a UGameInstanceSubsystem). Create instances via NewObject<USupabaseEOSIntegration>(). The static utility classes (USupabaseEOSPresence, USupabaseEOSLeaderboards, USupabaseEOSAchievements, USupabaseEOSPlayerData) provide their methods as static functions.
| Page | Description |
|---|---|
| EOS Authentication | Full guide to EOS Connect sign-in and Supabase token exchange |
| Presence & Social | Querying presence, friend lists, and rich presence data |
| Leaderboards | EOS leaderboard queries, score submission, and caching |
| Achievements | Achievement unlocking, progress tracking, and definitions |
| Player Data Storage | EOS cloud storage for save data with P2P replication |