Epic Online Services Godot (EOSG)

Easiest way to use Epic Online Services in Godot 4.3 (includes demo project)

Supports Windows x64, Linux x64/arm64, Android x64/arm64, MacOS, iOS arm64 (iphone/simulator)

Disclaimer: This project is NOT affiliated with Epic Games Inc or Godot Engine. It doesn't endorse Epic Online Services. This project and sample Godot scenes are provided solely for educational purposes and may or may not comply with Epic Games' Design Guidelines, if you plan to release a game make sure you read the Guidelines and any other steps needed to release a public game like asking for user consent, option to delete user data, website with privacy policy and license, etc.

This plugin has two main systems:

High Level EOS (Recommended)

The High Level Epic Online Services provides easy to use methods and signals to interact with EOS recommended for beginners.
GDExtension EOS

The GDExtension EOS provides advanced EOS usage not recommended for beginners. See EOS and IEOS classes.

High Level Epic Online Services

Following are the main classes in High Level Epic Online Services. They also have documentation in the Godot Editor:

HPlatform
HAuth
HAchievements
HFriends
HStats
HLeaderboards
HLobbies
HLog

A basic example of using High Level EOS:

# In main script
extends Node

func _ready() -> void:
	var init_opts = EOS.Platform.InitializeOptions.new()
	init_opts.product_name = "PRODUCT_NAME_HERE"
	init_opts.product_version = "PRODUCT_VERSION_HERE"

	var create_opts = EOS.Platform.CreateOptions.new()
	create_opts.product_id = "PRODUCT_ID_HERE"
	create_opts.sandbox_id = "SANDBOX_ID_HERE"
	create_opts.deployment_id = "DEPLOYMENT_ID_HERE"
	create_opts.client_id = "CLIENT_ID_HERE"
	create_opts.client_secret = "CLIENT_SECRET_HERE"
	create_opts.encryption_key = "ENCRYPTION_KEY_HERE"

	# Enable Social Overlay on Windows
	if OS.get_name() == "Windows":
		create_opts.flags = EOS.Platform.PlatformFlags.WindowsEnableOverlayOpengl

	# Initialize the SDK
	var init_res := await HPlatform.initialize_async(init_opts)
	if not EOS.is_success(init_res):
		printerr("Failed to initialize EOS SDK: ", EOS.result_str(init_res))
		return
	
	# Create platform
	var create_success := await HPlatform.create_platform_async(create_opts)
	if not create_success:
		printerr("Failed to create EOS Platform")
		return

	# Setup Logs from EOS
	HPlatform.log_msg.connect(_on_eos_log_msg)
	var log_ret := HPlatform.set_eos_log_level(EOS.Logging.LogCategory.AllCategories, EOS.Logging.LogLevel.Verbose)
	if not log_ret:
		printerr("Failed to set logging level")
		return

	HAuth.logged_in.connect(_on_logged_in)

	# During development use the devauth tool to login
	HAuth.login_devtool_async("localhost:4545", "CREDENTIAL_NAME_HERE")

	# Only on mobile device (Login without any credentials)
	# await HAuth.login_anonymous_async()


func _on_logged_in():
	print("Logged in successfully: product_user_id=%s" % HAuth.product_user_id)

	# Example: Get top records for a leaderboard
	var records := await HLeaderboards.get_leaderboard_records_async("LEADERBOARD_ID_HERE")
	print(records)


func _on_eos_log_msg(msg: EOS.Logging.Message) -> void:
	print("SDK %s | %s" % [msg.category, msg.message])

GDextension Epic Online Services

Features

Authentication (Epic Games, Steam, Discord, Anonymous etc)
Social Overlay on Windows
Achievements
Stats & Leaderboards
Lobby, Sessions and Multiplayer
Voice
Metrics
Mods
Player/Title data storage
Progression Snapshot
Reports and Sanctions
Ecommerce (Ecom Epic Games Store)
AntiCheat

View Current Project Status

Simple P2P Example

A simple demo showcasing P2P multiplayer using Epic Online Services: Click Here

Support Development

Making this project took a lot of time and effort, reading the Epic Online Services documentation countless times and testing each method in Godot. I would really appreciate if you could support the project in any way.

Github Sponsor

Want to support in other ways? Contact me on Discord: `@3ddelano`

Join the Discord server for discussing suggestions or bugs: 3ddelano Cafe

Demo Video (Youtube)

Watch the playlist

Documentation (Coming Soon)

Screenshots

Windows
Android
iOS
Cross platform lobbies
- iOS
- macOS

How does it work

This project uses GDExtension to wrap the Epic Online Services C SDK so that it can be easily used in Godot using GDScript, C#, etc with similar class hierarchy and static type support. It makes use of signals for sending events like user login, logout, achievement unlock, etc.

Installation

This is a regular plugin for Godot 4.3. To install the plugin follow the steps below:

Method 1: Install from Asset Library

Asset Library link: View the plugin on Godot Asset Library
In the Godot editor, navigate to the AssetLib tab, and in the search bar type EOSG.
Click on the plugin with name Epic Online Services Godot (EOSG) by 3ddelano
In the popup that opens, click the Download button.
Once the download is done, click the Install button.
Goto Project->Project Settings->Plugins and enable the Epic Online Services Godot 4.3 (EOSG) plugin.
Restart the godot editor.
You can now use the plugin. Head to the Documentation for more information on how to use the plugin.

Method 2: Install from GitHub

Goto the Releases section and download the latest release
Extract the zip file and copy the addons/epic-online-services-godot folder into the res://addons/ folder of your project. If the res://addons does not exist, create it.
In the Godot editor, goto Project->Project Settings->Plugins and enable the Epic Online Services Godot 4.3 (EOSG) plugin.
Restart the godot editor.
You can now use the plugin. Head to the Documentation for more information on how to use the plugin.

Development Setup

Pre-requisites

Godot Engine 4.3 (Get it here Godot Engine Download)
Epic Online Services C SDK (Download from Epic Developer Portal)
Make sure you have accepted the Terms and Conditions for Epic Online Services
A product registered with Epic Games Services (Make one for free Epic Developer Portal)

To develop this plugin, follow the below steps:

Download/clone the repository.
Extract the EOS C SDK zip downloaded from Epic Games, rename it to eos-sdk and paste it in the thirdparty/ folder. Refer to the below folder structure.
Build the GDExtension plugin in debug mode (With debug symbols)
```
# In root folder
scons platform=<platform> target=template_debug dev_build=yes
```
Eg. scons platform=windows target=template_debug dev_build=yes

Build the GDExtension plugin for release (Optimized)

# In root folder
scons platform=windows target=template_release

The built GDExtension library will be in the res://addons/epic-online-services-godot/bin/ folder of the sample project.

Debugging GDExtension on MacOS

If you get an error Not allowed to attach to process trying to debug GDExtension on MacOS using LLDB. Run the below command:

codesign --entitlements debug-entitlements.plist -f -s - /Applications/Godot.app/Contents/MacOS/Godot

How to run the sample project?

The sample Godot project is located in the Sample folder

Clone/Download the repo.
Download the latest release from the Releases section and replace the existing /addons/epic-online-services-godot with the one from the Release (this includes the built shared libraries).
Copy your credentials (Product Id, Sandbox Id, Deployment Id, Client Id, Client Secret) of your Epic Games "Product" from the Epic Games Dev Portal and paste them in Main.gd script in the relevant sections. The encryption key is a random 64 character long string. These credentials need to be kept as private as possible. One way is to make sure to encrypt all scripts when exporting the final game. (See Compiling with script key encryption)
Configure your Product on the EOS Dev Portal with the following configuration:

In the Client Policies section in Product Settings, for the Client policy type choose Custom policy, enable the User is required and enable every features and action except Connect (Trusted Server Required). This will allow the sample to access the different services provided by Epic Online Services. In your actual game, the client policy is important and you should give minimal permissions to features.
In the Permissions section of Epic Account Services, enable all three: Basic Profile, Online Presence and Friends.
(Optional if you want some pre-made achievements) In the Achievements section in Game Services, use the Bulk Import option and import the HelloProduct.zip file located at res://HelloProduct.zip

Bootstrapping Godot executable with Epic Online Services

If you want to use the Account Portal login option in Epic Online Services, you need to bootstrap the Godot/Game executable as needed by EOS-SDK 1.15 and greater. See Redistributable Installer

A sample of the generated .ini file for the Godot Editor is shown below (during game development):

ApplicationPath=Godot_v4.3.0-stable_win64.exe
WorkingDirectory=
WaitForExit=0
NoOperation=0

Follow the instructions in Running the service for local development and:

During game development

Bootstrap the Godot Editor executable (eg. Godot_v4.3.0-stable_win64.exe) to test the Account Portal login
After exporting the game

Bootstrap the exported game executable (eg. My Amazing Game.exe)

Exporting for Android

Pre-requisites

Setup the Android Build Template in your Godot project by following the tutorial Gradle builds for Andriod. This will create an android project in res://android/build.
Now with reference to the tutorial Add the EOS SDK to Your Android Studio Project, perform the following steps.

In the res://android/build/build.gradle file, add the following lines after the implementations in the dependencies section.

Before

dependencies {
    implementation libraries.kotlinStdLib
    implementation libraries.androidxFragment
    ... other code

After

dependencies {
    implementation libraries.kotlinStdLib
    implementation libraries.androidxFragment
    
    // EOS SDK dependencies
    implementation 'androidx.appcompat:appcompat:1.5.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    implementation 'androidx.security:security-crypto:1.0.0'
    implementation 'androidx.browser:browser:1.4.0'
    // Update the path so that it points to eossdk-StaticSTDC-release.aar provided in addons/epic-online-services-godot/bin/android/
    implementation files('../../addons/epic-online-services-godot/bin/android/eossdk-StaticSTDC-release.aar')

    ...other code

In the res://android/build/build.gradle file, add the following lines after the defaultConfig in the android section.

Before

android {

    ... other code

    defaultConfig {
        ... other code
    
        // Feel free to modify the application id to your own.
        applicationId getExportPackageName()
        versionCode getExportVersionCode()
        versionName getExportVersionName()
        minSdkVersion getExportMinSdkVersion()
        targetSdkVersion getExportTargetSdkVersion()

        missingDimensionStrategy 'products', 'template'
    }

    ... other code

After

android {

    ... other code

    defaultConfig {
        ... other code
    
        // Feel free to modify the application id to your own.
        applicationId getExportPackageName()
        versionCode getExportVersionCode()
        versionName getExportVersionName()
        minSdkVersion getExportMinSdkVersion()
        targetSdkVersion getExportTargetSdkVersion()

        missingDimensionStrategy 'products', 'template'

        // This is needed by EOS Android SDK
        String ClientId = "PUT YOUR EOS CLIENT ID HERE"
        resValue("string", "eos_login_protocol_scheme", "eos." + ClientId.toLowerCase())
    }

    ... other code

In the res://android/build/config.gradle file, update the minSdk to 23 to match with the requirements of the EOS Android SDK.

Before
```
minSdk             : 21,
```
After
```
minSdk             : 23,
```

In the res://android/build/src/com/godot/game/GodotGame.java file, update it as follows.

package com.godot.game;

import com.epicgames.mobile.eossdk.EOSSDK;     // added
import org.godotengine.godot.GodotActivity;

import android.os.Bundle;

public class GodotApp extends GodotActivity {
    static {                                   // added
        System.loadLibrary("EOSSDK");          // added
    }                                          // added
    
    @Override
    public void onCreate(Bundle savedInstanceState) {
        EOSSDK.init(getActivity());  // added
        
        setTheme(R.style.GodotAppMainTheme);
        super.onCreate(savedInstanceState);

    }
}

Now open your project in the Godot Editor, and goto Project -> Export and create a new Android export profile.
In the Gradle Build section, enable Use Gradle Build. In the Architectures section enable arm64-v8a. In the Permissions section ensure that ACESSS_NETWORK_STATE, ACCESS_WIFI_STATE and INTERNET are enabled. These permissions are needed for the EOS SDK to work. Fill in the other details such as package name, etc as needed.
You can now export the Android APK by clicking the Export Project button.

Exporting for iOS

Export the project from Godot editor for iOS target. You might get a build error during this process, ignore it. Open the generated iOS project in XCode and build the project. The build should be successful. EOSG has support for iOS arm64 device and iOS arm64 simulator.

Current Project Status

Completed with sample
- Auth Interface
- Achievements Interface
- Connect Interface
- CustomInvites Interface
- Friends Interface
- Stats Interface
- UserInfo Interface
- Leaderboards Interface
- Metrics Interface
- Mods Interface
- Presence Interface
- ProgressionSnapshot Interface
- Reports Interface
- UI Interface
- Version Interface
Completed without sample
- KWS Interface
- Lobby Interface
- P2P Interface
- PlayerDataStorage Interface
- RTC Interface
- Sanctions Interface
- Sessions Interface
- TitleStorage Interface
- Ecom Interface
- AntiCheatServer Interface
- AntiCheatClient Interface
Not completed
- Integrated Platform Interface

Name		Name	Last commit message	Last commit date
Latest commit History 271 Commits
.github		.github
.vscode		.vscode
_media		_media
godot-cpp @ fbbf9ec		godot-cpp @ fbbf9ec
sample		sample
src		src
thirdparty		thirdparty
.clang-format		.clang-format
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE.md		LICENSE.md
README.md		README.md
SConstruct		SConstruct
build-ios.sh		build-ios.sh
debug-entitlements.plist		debug-entitlements.plist
debug.cmd		debug.cmd
debug.sh		debug.sh
function_analyzer.py		function_analyzer.py

License

3ddelano/epic-online-services-godot

Folders and files

Latest commit

History

Repository files navigation

Epic Online Services Godot (EOSG)

Easiest way to use Epic Online Services in Godot 4.3 (includes demo project)

This plugin has two main systems:

High Level EOS (Recommended)

GDExtension EOS

High Level Epic Online Services

HPlatform

HAuth

HAchievements

HFriends

HStats

HLeaderboards

HLobbies

HLog

GDextension Epic Online Services

Features

View Current Project Status

Simple P2P Example

Support Development

Making this project took a lot of time and effort, reading the Epic Online Services documentation countless times and testing each method in Godot. I would really appreciate if you could support the project in any way.

Want to support in other ways? Contact me on Discord: @3ddelano

Demo Video (Youtube)

Documentation (Coming Soon)

Screenshots

How does it work

Installation

Method 1: Install from Asset Library

Method 2: Install from GitHub

Development Setup

Pre-requisites

Debugging GDExtension on MacOS

How to run the sample project?

Bootstrapping Godot executable with Epic Online Services

Exporting for Android

Pre-requisites

Exporting for iOS

Current Project Status

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 9

Sponsor this project

Contributors 5

Languages

Want to support in other ways? Contact me on Discord: `@3ddelano`