This overview provides a tour of the Auth and Friends sample project, which uses the Epic Online Services (EOS) SDK.
The Auth and Friends sample uses Epic Account Services for user authentication. You will need to initialize the EOS SDK with Client Credentials that correspond to a valid Application. For information about setting up your Application, consult the Developer Portal documentation. The functionality that this sample demonstrates can be used with any of the supported identity providers.
Source Code and Project
You can find the Auth and Friends project inside the EOSSDK/Samples/AuthAndFriends/ directory, which has the following subdirectories:
| Subdirectory | Contents |
|---|---|
/Bin/ | The output location where you will find the game's executable. The exact subdirectory where the executable appears after building varies based on your configuration and platform. |
/cmake/ | Helper files for making builds with CMake on Mac and Linux. |
/Intermediate/ | Intermediate build files. |
/Source/ | Project source code. |
You can also find certain shared sample files inside the EOSSDK/Samples/Shared/ directory. They are broken up into subdirectories as follows:
| Subdirectory | Contents |
|---|---|
/Assets/ | Shared game runtime texture and font assets. |
/External/ | Shared libraries. |
/Source/ | All shared source code. |
The Shared/Source/Core/ directory contains sample code using the EOS SDK to log in, authenticate users, and query friends. The source directories also contain code to manage the game itself.
Building the Sample
Windows DirectX
To compile and build the Auth and Friends sample, open Samples.sln with Microsoft Visual Studio, and build the desired configuration (either Debug_DX or Release_DX) for the target platform (either Win32 or Win64).
Following a successful build, the /Bin/ directory will contain the executable (AuthAndFriends.exe) in a subdirectory based on your configuration and target platform. The subdirectory will also contain a copy of the data assets and SDK binaries.
Windows SDL
To compile and build the Auth and Friends sample, open the solution, Samples.sln with Microsoft Visual Studio 2017 and build the desired configuration (either Debug_SDL or Release_SDL) for the target platform (either Win32 or Win64).
Following a successful build, the /Bin/ directory will contain the executable, (AuthAndFriends.exe), in a subdirectory based on your configuration and target platform. The subdirectory will also contain a copy of the data assets and SDK binaries.
Mac OSX
To build on a Mac, you will need to install the following dependencies:
- SDL2
- SDL2_ttf
- GLEW
- cmake
- gcc (through Command Line Tools for Xcode)
To compile and build the Auth and Friends sample, you can use Build.sh or Install.sh:
-
For local use only: Using
Build.shorBuild.commandfrom the Terminal, builds the sample and only packages the minimum to run locally on the sample folder (/Build/AuthAndFriends.app). -
Using
Install.shorInstall.commandfrom the Terminal, packages dependencies (e.g. EOS SDK dynamic lib, SDL2 lib etc.) in with the sample application package (/Install/AuthAndFriends.app) so it can be moved elsewhere and still run.
To run the AuthAndFriends sample, execute Run.command or Run.sh from the Terminal.
Linux
To build on Linux, you will need to install the following dependencies:
- SDL2 (runtime + headers)
- SDL2_ttf (runtime + headers)
- GLEW (runtime + headers)
- cmake
- gcc/g++
To compile and build the Auth and Friends sample, execute Install.sh from the Terminal.
Following a successful build, the /Install/ directory will contain the executable (AuthAndFriends). The subdirectory will also contain a copy of the data assets and makefile build files.
To run the AuthAndFriends sample, execute Run.sh from the Terminal.
Authenticating with Steam APIs
To compile and build the Auth and Friends sample with Steam External Auth support, open Samples.sln with Microsoft Visual Studio, and build the desired configuration (either Debug_DX_Steam, Release_DX_Steam, Debug_SDL_Steam, Release_SDL_Steam) for the target platform (either Win32 or Win64).
The Sample references files from the Steam SDK which can be downloaded and extracted to the Sample shared folder (as shown below). The public folder contains the Steam include files and the redistributable_bin folder contains the Steam LIB and DLL files.
The Samples.props file contains a SteamSDK property with a default path for the Steam SDK files to be located at: ..\Shared\External\SteamSDK.
Change this path if you wish to reference the Steam SDK files from a different location.
For testing, create a steam_appid.txt in the AuthAndFriends project root folder (as shown below) and add your Steam App ID to this file. This file will be copied along with the required Steam DLL file pre-build.
Following a successful build, the /Bin/ directory will contain the executable (AuthAndFriends.exe) in a subdirectory based on your configuration and target platform. The subdirectory will also contain a copy of the data assets, SDK binaries, and the Steam DLL file.
To run the sample, you will need to have the Steam Client running.
The sample will attempt to log in with a Steam Session Ticket on startup. If your account is not already linked to Steam, you will be taken to the Account Portal to log in, the Authentication will continue, and you will be logged in.
Exploring the Sample
If you would like to explore the sample, keep reading to learn about the available command line parameters, console commands, and features.
Command Line Parameters
The Auth and Friends sample supports the following optional command line parameters:
| Command Line Parameter | Usage | Description |
|---|---|---|
| userid | -userid <string> | The user id box will be filled out with the <userid> text, and the user (specified by the id <string>) will be logged in when the "LOGIN" button is clicked (or via the autologin process). Additionally, <userid> can be an email, display name or Facebook ID. |
| password | -password <string> | The password box will be filled out with the <password> text and the user (with password <string>) will logged in when the "LOGIN" button is clicked or via the autologin process. |
| autologin | -autologin 1 | The user specified with "userid" and "password" will be logged in automatically when the game starts after the EOS SDK has been initialized. |
| productid | -productid <string> | Overrides the Product ID when creating the EOS SDK Platform Options. See SampleConstants.ProductId for the default value. |
| sandboxid | -sandboxId <string> | Overrides the Sandbox ID when creating the EOS SDK Platform Options. See SampleConstants.SandboxId for the default value. |
| deploymentId | -deploymentId <string> | This enables you to override the Deployment ID when creating the EOS SDK Platform Options. See SampleConstants.DeploymentId for the default value. |
| clientid | -clientid <string> | This allows you to override the Client Credentials Id when creating the EOS SDK Platform Options. Also, see SampleConstants.ClientCredentialsId for the default value. |
| clientsecret | clientsecret <string> | This enables you to override the Client Credentials Secret when creating the EOS SDK Platform Options. Also, see SampleConstants.ClientCredentialsSecret for the default value. |
| fullscreen | -fullscreen 1 | If this is added to the command line, the game will start up in full screen mode (window mode is the default). |
| logfile | -logfile <string> | The debug output log will be written out to the file name specified by <string>. Additionally, the default debug output log file is "DebugOuput.log", and it is saved in the same folder as the solution file. |
| devhost | -devhost <string> | The "Host" port box in the "Dev Auth" login options will contain the <string> parameter. |
| devcred | -devcred <string> | The "Credentials" box in the "Dev Auth" login options will contain the <string> parameter. |
Console Commands
The Auth and Friends sample supports the following console commands, which you can enter in-game:
| Console Command | Usage | Description |
|---|---|---|
| TEST | TEST | Prints out a test message to the console. |
| CLEAR | CLEAR | Clears all the text lines in the console output window. |
| EXIT | EXIT | Exits and closes down the game. |
| LOGIN | LOGIN <USER_ID> <PASSWORD> | Attempts to login the user with user ID <USER_ID> and password <PASSWORD>. |
| LOGOUT | LOGOUT <USER_NAME> | Attempts to logout the user named <USER_NAME>. |
| INVITE | INVITE <FRIEND_NAME> | Send a friend invite to the user with display name <FRIEND_NAME>. |
| PREV | PREV | Shows info for the previous logged in user (if more than one user is logged in). |
| NEXT | NEXT | Shows info for the next logged in user (if more than one user is logged in). |
| NEW | NEW | Shows login dialog to allow logging in as an additional user. |
| FRIENDS | FRIENDS | Opens the Friends overlay. |
| HELP | HELP | Prints info to the console output about all the above console commands. |
To add more console commands, see the Game::CreateConsoleCommands function in Game.cpp.
Features
The Simple Framework has a few features, including Login and Logout functionality, a Console Window, a Friends List, and Presence Information.
Login
The following image shows the FRIENDS section with several login methods. To log in, click on a method and enter the appropriate information. You can then click LOG IN to complete the process.
The login panel, showing the supported login methods.
- Device Code: Log in with a URL containing a code that Epic provides.
- Dev Auth: Log in with Developer Authentication Tool credentials.
- Account Portal: Log in by linking with your Epic Account.
The following image shows your user display name (in the top right) after you have successfully logged in:
EOS supports multiple, simultaneous logins from a single system. In this sample, you can click the NEW button to log in with a new account. If multiple accounts are logged in at the same time, the left and right arrows will cycle through them.
Device Code Method
The Device Code method sends a URL containing a login code to the sample. You can find the URL in the sample's console log. After copying it into the FRIENDS section, you will be logged in. To cancel this process, click Cancel in the pop-up window.
Dev Auth Method
To log in with the Dev Auth method, enter the host port where you are running the Developer Authentication Tool, and supply the credentials that the tool provides. Click LOG IN after entering this information.
Account Portal Method
With the Account Portal method, you will be taken to the Epic Account portal in your web browser, where you can log in to your application with an Epic Account. After completing the web flow, you will be returned to the sample.
Logging Out
To log out, click the LOG OUT button.
Console Window
The Console logs relevant debug output from various EOS SDK operations. Additionally, the Console displays debug output from the following:
| Function | Text Color |
|---|---|
FDebugLog::Log() | White |
FDebugLog::LogWarning() | Orange |
FDebugLog::LogError() | Red |
Note: Errors from EOS SDK operations display red text, and warnings display orange text.
Refer to the following image to learn more about the Console Window:
The console output (1) logs relevant debug information. Additionally, you can enter console commands (2) or clear all times from the console output (3). Finally, you can select and copy text highlighted in yellow from the console output by clicking, dragging, and then then using the Ctrl+C keyboard combination. If you want to select all text in the console ouput, use the Ctrl+A keyboard combination.
Note: Text is copied to the clipboard.
Friends List
Friends List is a separate part of a window that shows friends and their statuses, friend invitations, and enables interaction. You have to be logged in to be able to use Friends List (see below).
Friends List also contains a text field that serves two purposes. First, it can filter friends by their display name. And second, it is possible to search for new friends by typing in a user display name and pressing the Enter key. If there are no friends with the entered display name in your list, a search operation is executed, and the user will be shown in the list with an option to add them (see below):
Pressing the + button sends a friend invite to the user. Invited friends are shown in Friends List until the user accepts or rejects the invitation.
Incoming friend invitations display buttons to accept or reject the invitation.
Presence Information
After a user accepts an invitation, they become your Friend, enabling the display of additional information. For example, it is possible to see what a friend's status is (such as whether they are Online, Away or Offline). Additionally, presence information is available for friends who are currently playing a game, and a green label next to their name shows the application name and platform they are currently using (see image below).
