Skip to content

Commit

Permalink
docs: link readme to official docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@nattb8
nattb8 committed Nov 8, 2023
1 parent 434f5fc commit 8475a41
Show file tree
Hide file tree
Showing 6 changed files with 3 additions and 249 deletions.
Binary file removed ImxBatchNftTransfer.png
View file
Binary file not shown.
Binary file removed ImxTransferFlow.png
View file
Binary file not shown.
Binary file removed PassportLoginFlow.jpg
View file
Binary file not shown.
Binary file removed PassportLogoutFlow.jpg
View file
Binary file not shown.
Binary file removed PassportPKCELoginFlow.png
View file
Binary file not shown.
252 changes: 3 additions & 249 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,256 +10,10 @@

# Immutable SDK for Unreal Engine

## User Guide

### Supported Platforms

- Windows 10 (64-bit)
- macOS (minimum version 10.5)
- Android (minimum version 8.0)
- iOS (minimum version 13.0)

### Supported Unreal Engine Versions

- Unreal Engine 5.0 and above
- Unreal Engine 4.26 and above

## Registering your game

Before using Passport, you must register your application as an OAuth 2.0 **Native** client in the [Immutable Developer Hub](https://hub.immutable.com). First, you'll need to create a project and a testnet environment.
Then, you can navigate to the Passport config screen and create a passport client for your created environment.
When you're ready to launch your application on the mainnet, please ensure you configure a passport client under a mainnet environment. Here's how you can configure the fields while creating a client:

### Creating an OAuth2.0 Native client

#### Application Type
You must register your application as an OAuth 2.0 **Native** client.

#### Client name
The name you wish to use to identify your application.

#### Logout URLs
Native clients don't make use of Logout URLs, you might set your own site or https://localhost:3000 as this is a required field.

#### Callback URLs
On Android, iOS and macOS clients, you should set your application's deep link scheme (e.g. `mygame://callback`) if you wish to make use of [PKCE login](#android-and-ios-pkce-login-unreal-engine-50-only), otherwise set the same as [Logout URLs](#logout-urls).

[PKCE login](#android-and-ios-pkce-login-unreal-engine-50-only) is not supported on Windows clients. Hence, they do not use Callback URLs. You may set Callback URLs to be the same as [Logout URLs](#logout-urls), as it is a required field.

#### Web Origins URLs
Optional field. The URLs that are allowed to request authorisation. This field is available when you select the Native application type.

See [here](https://docs.immutable.com/docs/x/passport/register-application/) for more details.


### Installation

> :clipboard: Prerequisites
>
>[git-lfs](https://git-lfs.github.com/): since `.uasset` and `.umap` files are stored on Git Large File Storage, ensure you have [git-lfs]((https://git-lfs.github.com/)) installed.
1. Clone the [unreal-immutable-sdk](https://github.com/immutable/unreal-immutable-sdk) repository or download the zip/tarball from one of the versions [here](https://github.com/immutable/unreal-immutable-sdk/tags)
2. Copy the cloned repository into your project's `Plugins` folder, e.g.: `MyGame/Plugins/unreal-immutable-sdk`.
3. Restart your project (Unreal Editor & Rider), upon restart it should load the `unreal-sdk-plugin` and should be good to use.

> [!NOTE]
> For Unreal Engine 4.26 and above we use Blui as a browser instead of inbuilt browser. For Unreal Engine 5.0 and above we use inbuilt browser
> For UE4 only download the Blui Plugin from https://github.com/immutable/unreal-immutable-sdk/releases/download/0.1.1/BLUI.4.2.BluBrowserCEF.90.0.4430.212-Win64.zip into your project Plugins directory.
> Please update `immutable.uplugin->Plugins->WebBrowserWidget` to false and restart your UE4 editor.
### Setup

#### Blueprint

See the included sample widgets in `All`->`Plugins`->`Immutable Content` in the Unreal Editor content browser for examples of how to use the plugin in Blueprint. If you don't see a `Plugins` folder under `All` you may need to enable `Show Plugin Content` in the content browser's `Settings` menu.

#### C++

See `ImmutablePassport.h` for the C++ Passport API. Follow the same sequence of steps as the Blueprint widget example to initialise and connect Passport and retrieve account data.

### Quick Start

#### Passport Login Flow

See this Blueprint showing how to login to passport ![Passport Login Blueprint](PassportLoginFlow.jpg)

Here are the steps to login to passport:

1. `Initialise Passport` to initialise passport instance.
2. Check if there are stored credentials from previous login.
3. If stored credentials found, `ConnectSilent` uses the saved credentials to login to Passport.
4. When no stored credentials found or step 3 fails, attempt to make a new Connection to login to Passport using `Connect`. This will open the gamer's default browser and take them through the auth flow.

Once the gamer is connected to Passport, the SDK will store your credentials (access, ID, and refresh tokens).

> [!NOTE]
> We use the [Device Code Authorisation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow#:~:text=Your%20Auth0%20Authorization%20Server%20redirects,authorized%20to%20access%20the%20API.) flow to authenticate and authorise gamers.
#### Log out of Passport

See this Blueprint showing how to logout from passport ![Passport Logout Blueprint](PassportLogoutFlow.jpg)

#### Imx Transfer

> Note: The transfers feature require pre-approval from Immutable. Please [contact us](https://docs.immutable.com/docs/x/contact/) before making use of it.
To transfer tokens of type ETH, ERC20 or ERC721 use `UImmutablePassport::ImxTransfer` method. See this Blueprint example showing how to use Imx Transfer

![Imx Transfer](ImxTransferFlow.png)

To transfer multiple NFTs in a single transaction use `UImmutablePassport::ImxBatchNftTransfer` method. See this Blueprint example showing how to use Imx Batch Nft Transfer

![Imx Batch Nft Transfer](ImxBatchNftTransfer.png)

#### zkEVM Send Transaction

To send a transaction on zkEVM use `UImmutablePassport::ZkEvmSendTransaction` method. See this Blueprint example showing how to use Zk Evm Send Transaction

![Zk Evm Send Transaction](ZkEvmSendTransaction.png)

### Android, iOS and macOS PKCE login (Unreal Engine 5.0+ only)

For Android, iOS and macOS, you can use the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce) login flow instead of [Device Code Authorisation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow#:~:text=Your%20Auth0%20Authorization%20Server%20redirects,authorized%20to%20access%20the%20API.). This means the gamer has one less step to complete and will be redirected back to the game after successfully authenticating.

To use this flow you will need to:

1. Define a deep link scheme for your game (e.g. `mygame://callback`)
2. Login to the [Immutable Developer Hub](https://hub.immutable.com/) and add the deeplink to your clients **Callback URLs** and **Logout URLs**
3. Set this deep link as your redirect URI in `Initialize Passport`

![Passport PKCE Login Blueprint](PassportPKCELoginFlow.png)

#### Unreal Editor Android setup

1. In Unreal Editor go to **Project Settings** -> **Android** -> **Advanced APK Packaging**
2. Add the following code inside the **Extra Settings for \<activity> section (\n to separate lines)** field:

```XML
<intent-filter>\n<action android:name="android.intent.action.VIEW" />\n<category android:name="android.intent.category.DEFAULT" />\n<category android:name="android.intent.category.BROWSABLE" />\n<data android:host="callback" android:scheme="mygame" />\n</intent-filter>
```

The application will now open when the device processes any link that starts with `mygame://callback`.

#### Unreal Editor iOS setup

1. In Unreal Editor go to **Project Settings** -> **iOS** -> **Extra PList Data**
2. Add the following code inside the **Additional Plist Data** field:

```
<key>CFBundleURLTypes</key><array><dict><key>CFBundleURLSchemes</key><array><string>mygame</string></array></dict></array>
```

After this set-up and the redirect URI you set in `Initialize Passport`, your game can log in using `mygame://callback`.

#### Unreal Editor macOS setup

Since there is no way to add extra plist data like iOS from the Unreal Editor Project Settings, you must edit the Engine's default `Info.plist`.

1. In your preferred IDE, open the Engine's `Info.plist` file (e.g. `Engine/Source/Runtime/Launch/Resources/Mac/Info.plist`)
2. Add the following code inside the root `<dict>...</dict>`:

```
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>mygame</string>
</array>
</dict>
</array>
```

After setting up and specifying the redirect URI in `Initialize Passport`, the user will be automatically redirected back to the game through `mygame://callback` upon completing the login process.

See the [sample game](https://github.com/immutable/sample-unreal-game) for an example of how to set up PKCE for Android, iOS and macOS.

## Supported Functionality


| Method | Description |
|-----------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Connect | Log into Passport using [Device Code Authorisation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow#:~:text=Your%20Auth0%20Authorization%20Server%20redirects,authorized%20to%20access%20the%20API.) |
| ConnectSilent | Attempts to login using stored credentials |
| ConnectPKCE | (Android, iOS and macOS on Unreal Engine 5.0+ only) Log into Passport using [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce) |
| CheckStoredCredentials | Checks if there are stored credits from previous login |
| GetAddress | Gets Wallet Address |
| GetEmail | Get Email Address associated with the Wallet Address |
| ImxTransfer | ImxTransfer used to send tokens of type ETH, ERC20, ERC721 to reciever's address |
| ImxBatchNftTransfer | ImxBatchNftTransfer used to send multiple Nft tokens in a single transaction to reciever's address |
| GetEmail | Get Email Address associated with the Wallet Address |
| zkEVM request accounts | This method attempts to authenticate the user and initialises their Passport wallet before returning an array of wallet addresses |
| zkEVM get balance | Returns the balance of the account of given address in wei |
| zkEVM send transaction | Creates new message call transaction or a contract creation, if the data field contains code |


See the [ImmutablePassport.h](https://github.com/immutable/unreal-immutable-sdk/blob/dc39324db204f2ba30e9c9f0ca25c070987785cb/Source/Immutable/Public/Immutable/ImmutablePassport.h#L115C8-L115C8) header for the full API.

## Examples

- **Sample Blueprints** - see the [sample blueprints](https://github.com/immutable/unreal-immutable-sdk/tree/main/Content/BlueprintSampleContent) for examples of how to use the Immutable Unreal SDK.

- **Sample Game** - see the [sample game](https://github.com/immutable/sample-unreal-game) for example of how to use the Immutable Unreal SDK.

## Plugin Maintainers' Guide

### Prerequisites

- git
- Epic Games Launcher
- Unreal Engine installed from the Epic Games Launcher; you will need every version that the plugin supports (currently 4.27, 5.0, 5.1, 5.2)
- Visual Studio 2022 with C++ support
- JetBrains Rider IDE (recommended for working with Unreal Engine C++ code)

If not Rider, Visual Studio is fine and even better with the Resharper plugin.

### Getting Started

See [user guide](#user-guide) to install the plugin, with one caveat: If you want to open the project and plugin in an IDE you'll need to create your Unreal project as a C++ project. If you've already accidentally created your Unreal project as BluePrint-only you can convert it to a BluePrint-and-C++ project by adding any C++ class from the `Add New C++ Class` option in the Unreal Editor's `File` menu.

### Debugging the Embedded Browser

#### Embedded Browser Logs

See `Saved/Logs/cef3.log` in your Unreal project.

#### JS Console Output

In Unreal Engine 5.1+ the project is set up so that `console.log()` will pass all the way through to the Unreal console. This isn't available in UE5.0 and earlier but you can still use Chromium's remote debugging (see below).

#### Remote Debugging

To set up Chromium remote debugging, edit project build/launch configurations in your IDE to add the following program command-line argument to the appropriate configurations: `cefdebug=9222`

Next, launch the game and then open a separate Chrome/Chromium browser and navigate to `chrome://inspect` where your app should be listed, sometimes intermittently or after a delay, under the `Remote Target #localhost` section. Click `inspect` to launch the remote debugging session.

## Release Unreal Immutable SDK Plugin

1. Release the plugin using GitHub releases. See https://github.com/immutable/unreal-immutable-sdk/releases

## Release Blui Plugin for UE4

For UE4 we are using Blui as the in built browser does not work.

1. Download this release supporting UE 4.27 and 4.26 https://github.com/getnamo/BLUI-Unreal/releases/tag/4.2.0
2. Download the CEF 90 Browser from https://github.com/getnamo/BLUI-Unreal/releases/tag/v4.6.0 (`BluBrowserCEF....7z`)
3. Delete the Thirdparty/cef/Win folder from the BLUI plugin
4. Place the Win folder from the `BluBrowserCEF...7z` into Thirdparty/cef
5. Disable cefdebug settings in `Blu.cpp`, following line
```
// BluManager::Settings.remote_debugging_port = 7777;
```
6. Zip the Blui plugin folder and upload to the GitHub release.
## How to Add Game Bridge Asset to Packaged Resources
1. Open Unreal Editor in the lowest supported version i.e, 4.26 for this Plugin.
2. Open Content Drawer
3. Navigate to Plugins -> Immutable Content -> Packages Resources
4. Delete the existing imported asset if you wish to replace with new one
5. Right Click and Import the `index.js` file
![Import Asset](Docs/ImportAsset.png)
# Documentation

* [Immutable X](https://docs.immutable.com/docs/x/sdks/unreal)
* [Immutable zkEVM](https://docs.immutable.com/docs/zkEVM/sdks/unreal)

## Changelog Management

Expand Down

0 comments on commit 8475a41

Please sign in to comment.