1. Ruslan Nazirov Avatar Ruslan Nazirov
  2. Untitled project
  3. Etherlinker for UE4

Wiki

Clone wiki

Etherlinker for UE4 / Frequently Asked Questions

View History

Frequently Asked Questions

How to use Etherlinker plugin in your own projects

  • Copy Etherlinker folder from Example Project/Plugins folder to your project Plugins folder.
  • Copy config files (DefaultInput.ini, DefaultEngine.ini) from EtherlinkerExampleProject/Config folder or merge them manually if you have your own configs. Make sure that you copied data from [/Script/Engine.RendererSettings] and [/Script/Engine.CollisionProfile] sections of DefaultEngine.ini. VR Widgets require custom collision preset and trace channel, so make sure that you copied those settings.
  • Migrate content from EtherlinkerExampleProject to your project.
    If you're new to UE4 and never do this, then those articles might be helpful: https://wiki.unrealengine.com/Migrate_content_between_projects https://docs.unrealengine.com/latest/INT/Engine/Content/Browser/UserGuide/Migrate/
  • Manually copy IntegrationServer folder from Content directory of Example Project to your project Content directory.
  • Create your own PlayerState blueprint(for experienced users) or use existing, provided with Example Project.
    If you created your own PlayerState blueprint, you need to add the same components (like Etherlinker) and variables in it, like in BP_PlayerState blueprint from Example Project. Also don't forget to implement BP_EtherManagerHolder interface.
  • Setup Etherlinker parameters using Getting Started guide.
  • If in Edit->Project Settings->Android SDK you configured Java Location (probably it equals to JDK 1.8), change its location to JDK 11 (read FAQ, Android Support section for more details).
  • Run Integration Server, use BP_Terminal_01 blueprint to interact with Ethereum blockchain or make your own blueprints/classes for that.
  • Use BP_WalletAuthenticator_UI and BP_WalletInitializationChecker_UI widgets for wallet authentication and customize them to fit your requirements.

How to start/stop/restart/check integration server from UE4 Editor

In the toolbar, find Etherlinker icon and in the menu select required action. Make sure that java.exe is available in your PATH variable(so you can call it from the console without specifying a full path to it, for example) in case if something not working.

How to compile contracts from UE4 Editor

Make sure that you set JAVA_HOME variable and EtherlinkerServer folder is in the same folder as your UE4 project. In the toolbar, find Etherlinker icon and in the menu select Compile Contracts. If it's your first run of this command, then Maven will download all required libraries first, which could take some time. After contract compilation, integration server also will be recompiled. Then the new .war file will be placed in the Content/IntegrationServer folder. If everything completed successfully, then the integration server will start automatically. After that, you can deploy your new contracts by using the DeployContract method of EtherManager.

How to run integration server manually

You can use start.bat script in Content/IntegrationServer or use terminal to run command: "java -Xms128m -Xmx512m -jar <PathToYourProject>\Content\IntegrationServer\stratum-1.0.war".
You can use javaw instead of java if you want to run server silently.

VR Controls (Tested with Oculus Rift):

  • Move up/down and hold thumbstick on motion controller to set teleport direction.
  • Release thumbstick to teleport to the selected location.
  • Move thumbstick left/right to rotate in place in certain direction.
  • Touch and hold terminal display to execute example code on it.
  • Press Facebutton1 on left motion controller to open VR Widget Selector
  • Press Special Button on left motion controller to open pause menu.

FPS Controls:

  • Use WASD buttons for movement
  • Press and hold Shift to run
  • Press E to execute code on terminal
  • Press Space to jump
  • Press "F" to open wallet authentication widget
  • Press "G" to open donations widget
  • Press "T" to open Ether transfer widget
  • Press "C" to open ERC20 Token User widget
  • Press "V" to open ERC20 Token Admin widget
  • Press "B" to open ERC721 Token User widget
  • Press "N" to open ERC721 Token Admin widget
  • Press "M" or "Esc" to open pause menu
  • Press "H" or open mobile widget selector

How to rebuild Etherlinker plugin

Follow these steps to build Etherlinker plugin:

  • Open from top menu Edit -> Plugins tab.
  • Find Etherlinker plugin.
  • Click Package. Select directory, where plugin should be placed after compilation (it should be separate directory, not your project Plugins folder).
  • If compilation completed successfully, delete old Etherlinker plugin and put compiled plugin inside your Plugins directory.

This way of plugin compilation will allow you to build your project safely.
But during plugin development, you can also use Visual Studio to compile plugin (don't forget to close UE4 Editor before that) and test changes. Keep in mind that this way of plugin compilation won't work with packaged builds and you still need to follow steps above to compile plugin, if you want to package your game/project.

How to add new features to Integration Server

  • Import EtherlinkerServer into your preferred IDE (like IntelliJ Idea)
  • Make the required changes
  • From UE4 Editor run "Compile Integration Server" command.

How to enable Java Melody integration server monitoring

In application.properties (can be found inside EtherlinkerServer folder) set javamelody.enabled=true and change login/password in javamelody.init-parameters.authorized-users parameter. Then rebuild the integration server from UE4 Editor. Now you can use URL, like https://localhost:8451/monitoring to open integration server console monitoring.

How to generate self-signed SSL certificates

Open console, move to the desired folder to store certificate with "cd" command and enter the following command (where PATH_TO_JDK is something like "C:/Program Files/Java/jdk-11.0.1" on Windows):
"<PATH_TO_JDK>/bin/keytool" -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore keystore.p12 -validity 3650
Enter the password and other requested data (IMPORTANT: set first and last name equal to localhost).
Copy generated keystore.p12 file into EtherlinkerServer\Stratum\src\main\resources folder.
Change "server.ssl.key-store-password" and "server.ssl.keyAlias" parameters in EtherlinkerServer\Stratum\src\main\resources\application.properties
Re-compile integration server from UE4 Editor

How to use an existing SSL certificate

If you already have an SSL certificate and want to use it in Integration server, you can use the following command to create a new keystore, which contains your certificate: "<PATH_TO_JDK>/bin/keytool" -import -alias tomcat -file myCertificate.crt -keystore keystore.p12 -storepass password

If you have a PEM certificate, you can use the following command to create a new keystore, which contains your certificate: openssl pkcs12 -export -inkey <PRIVATE KEY PEM> -in <CERTIFICATE PEM> -out keystore.p12

If you're using Windows, you can download OpenSSL here (first link is fine): https://wiki.openssl.org/index.php/Binaries
If you got PEM keys from LetsEncrypt, then the command will be like that: "C:\Program Files\OpenSSL-Win64\bin\openssl" pkcs12 -export -inkey privkey1.pem -in fullchain1.pem -out keystore.p12
Set a proper export password to use it later.
Copy generated keystore.p12 file into EtherlinkerServer\Stratum\src\main\resources folder.
Change "server.ssl.key-store-password" and "server.ssl.keyAlias" parameters in EtherlinkerServer\Stratum\src\main\resources\application.properties
Re-compile integration server from UE4 Editor

If you want to know alias (to set server.ssl.keyAlias property), you can use the following command:
"<PATH_TO_JDK>/bin/keytool" -v -list -keystore keystore.p12

Keep in mind, that if you have Integration Server URL = https://localhost:8451 and in your certificate, you have Owner CN != localhost (it could be something like yourwebsite.com), then you will get an error when you will try to call any methods from UE4. The solution is to use a proper Integration Server URL (like https://yourwebsite.com:8451) and to host integration server on a server, which uses that domain name.

Mac OS Support

If you're running Etherlinker on Mac OS and want to use pre-built debug certificate, you should add a keystore.p12 certificate from EtherlinkerServer folder to the Keychain Access app and in certificate properties set everything to always allow.
You need to change Compile Contracts Script to compileContracts.sh and Compile Integration Server Script to compileIntegrationServer.sh in Plugin's settings.
On Mac OS during contracts or integration server compilation UE4 Editor window can be freezed (unlike Windows), so be patient and wait until dialog with operation result pops up.
In case of any issues, try to check that script files or mvnw file has LF line terminator instead of CRLF.
Also on Mac OS java always running in silent mode, which means that you won't see a separate window with java process like in Windows if you turned off silent mode.
Don't forget to build a plugin if you want to package your project. You can do this from Edit->Plugins->Etherlinker->Package.

Android Support

To run Etherlinker Example Project Demo Level on Android Device and get visual experience, similar to desktop, you need a high-end phone, which supports Open GL 3.1. However, Etherlinker plugin itself can work on low-end phones in any kind of games.

You also need to deploy Integration Server on a dedicated server (Linux/Ubuntu recommended) in production. For debugging purposes, you can use your local machine (read docs below on how to do this).

Don't forget to read official UE4 docs on how to configure Android SDK.

Add "Android" platform to Etherlinker.uplugin WhitelistPlatforms list.

Currently, there is a bug with Gradle in UE4, which prevents from compiling .apk for android or package an Etherlinker plugin with Android support if you're using OpenJDK 11. The solution is to temporarily change "Location of Java" in Edit->Project Settings->Android SDK to Java 1.8 and compile .apk or package a plugin, then change it back to OpenJDK 11 to be able to make operations with Integration Server from UE4 Editor. Make sure that if you installed JDK 8 after OpenJDK 11, to change PATH variable in a way, that only "C:\Program Files\Java\jdk-11.0.1\bin" will exist and remove other Java-related paths from PATH variable. Then test that you're using OpenJDK 11 by entering java -version in the console.

To interact with terminals, just tap on them, when they are in focus (yellow outline around them visible).

Use Mobile Widget Selector to open various Etherlinker template widgets.

To make it possible to connect to Integration Server, hosted on your local machine (https://localhost:8451 by default), from Android device, you need to do following:

  • Connect your Android phone to your local machine via USB cable
  • Make sure that you're enabled developer options on Android phone and allowed USB debugging
  • Open chrome://inspect/#devices in your Chrome browser
  • Set Discover USB devices and Discover network targets to true
  • Open Port Forwarding menu
  • Set "Port" field to 8451 and "IP address and port" field to your actual local machine IP address (192.168.1.2:8451 for example)
  • Enable port forwarding
  • Do not close the DevTools tab until you working with your Android phone
  • Now you can connect to Integration Server, which is running on your local machine from your Android Phone, which exists in the same network.

iOS Support

To run Etherlinker Example Project Demo Level on iOS device, you need to register in Apple Developer Program, get a machine with Mac OS installed and read UE4 docs on how to run your project on iOS.

Add "IOS" platform to Etherlinker.uplugin WhitelistPlatforms list.

You also need to deploy Integration Server on a dedicated server (Linux/Ubuntu recommended) in order to interact with Ethereum blockchain from iOS.

Deploying integration server on Linux(Ubuntu) dedicated server

  • Add correct SSL keystore file (Read FAQ on how to generate it) to integration server sources folder and compile integration server.
  • Deploy stratum-1.0.war file to your Linux server.
  • Make sure that you opened port 8451 (or any other, which you selected to work with integration server).
    You can do this with command: sudo ufw allow 8451/tcp
  • Install Java 8 package
  • Install Haveged package (sudo apt-get install haveged) and run it (sudo service haveged start) in order to make encryption library work.
  • Run Integration Server with command: java -Xms128m -Xmx1024m -jar stratum-1.0.war
  • Update Etherlinker plugin settings in UE4 Editor to connect to your Linux server. Also, don't forget to change Default Wallet Path to something like /home/username/EtherlinkerKeys/ ("/" symbol at the end is important).
  • You can also run Integration Server in debug mode with command: java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=5005,suspend=y -Xms128m -Xmx1024m -jar stratum-1.0.war (make sure that you opened port 5005). Then create Remote Configuration in IntelliJ Idea and connect to Integration Server.

Integration server parameters

You can customize some integration server-specific parameters in the application.properties file in EtherlinkerServer\Stratum\src\main\resources directory.

  • etherlinker.is.local.server - it set to true, we won't make any additional HTTP request checks if it's a local server on end-user PC.

  • etherlinker.antispam.filter.active - if set to true, then anti-spam service will process each operation request and can block the user if he makes too many requests. Can be used against DDOS attacks. If user blocked third times per day, then he will be blocked until next day since his first operation call.

  • etherlinker.antispam.filter.unblock.interval - how much time (value = 1000 means 1 second) should pass to unblock user so he can call operations on integration server.

  • etherlinker.antispam.filter.block.interval - how much time (value = 1000 means 1 second) should pass between operation calls to process operation request as normal, otherwise activate anti-spam protection.

  • etherlinker.check.ue4.agent - If a User-Agent value from HTTP request is not equal to "X-UnrealEngine-Agent" then this request will be blocked if this setting equals to true. It can be used to prevent any activity from non-UE4 applications, but it won't help if the user fakes his User-Agent in the HTTP request.

Geth/Parity support

If you don't want to use Infura Network, it's possible to use local geth/parity nodes to interact with Ethereum blockchain.

  • You can run geth with command: geth --rpcapi personal,db,eth,net,web3 --rpc --rinkeby
  • You can run parity with command: parity --chain testnet

Make sure to do compelete sync with network
Then you need to configure application.properties file in Integration Server source folder:

  • etherlinker.use.geth.or.parity = true (or false, if you want to use Infura Network)
  • etherlinker.geth.or.parity.url = http://127.0.0.1:8545 (or any other URL to connect to your local instance of geth/parity)

Then recompile and run integration server and try to check wallet balance to see if things working or not.

How to install OpenJDK 11 on Windows

  • Download OpenJDK 11 (https://jdk.java.net/11/)
  • Extract the zip file and copy jdk-11.0.1 folder into "C:\Program Files\Java\"
  • Select Control Panel and then System.
  • Click Advanced and then Environment Variables.
  • Add the location of the bin folder of the JDK installation to the PATH variable in System Variables ("C:\Program Files\Java\jdk-11.0.1\bin").
  • Under System Variables, click New.
  • Enter the variable name as JAVA_HOME.
  • Enter the variable value as the installation path of the JDK ("C:\Program Files\Java\jdk-11.0.1").
  • Click OK.
  • Click Apply Changes.
  • Configure the JDK in your IDE.
  • To see if it worked, open up the Command Prompt and type java -version and see if it prints your newly installed JDK.

How to install OpenJDK 11 on Mac

  • Download OpenJDK 11 (https://jdk.java.net/11/)
  • Open terminal
  • cd ~/Downloads
  • tar xf openjdk-11.0.1_osx-x64_bin.tar
  • sudo mv jdk-11.0.1.jdk /Library/Java/JavaVirtualMachines/
  • java -version to check if it installed correctly

Useful tips

If you need to package a project, make sure that you packaged plugin firstly (Plugins -> Select Etherlinker plugin -> Package).

Due to the complexity of movement replication, VR Character, included in the project, is not multiplayer-ready (but VR widgets should work fine in multiplayer). Use third-party open source projects, like VRExpansionPlugin, to get multiplayer-ready VR character, which can be used with Etherlinker.

If you can't click on VR Widgets with Widget Interaction component in multiplayer, then open Editor Settings -> Multiplayer Options and uncheck "Use Single Process", then set Editor Multiplayer Mode to "Play as Client".

You can convert number parameter from Ether to Wei by adding "EtherToWei" modifier to input string. For example, 0.002 EtherToWei will be converted to 2000000000000000 value.

You can make hands in VR collideable with the environment and enable ragdoll for fingers. To do this, you need to enable IsLeftHandCollisionActive or IsRightHandCollisionActive properties in BP_Player_VR blueprint. Keep in mind that by default we have only right hand mesh and Physics Assets can't be mirrored correctly, so in order to make left hand work properly you should make a separate mesh for left hand, separate physics asset, animation blueprint, animations and initialize this hand in left motion controller blueprint. By default hands collision are disabled.

It's possible to execute operations on Integration Server in batch. See ERC721 Entity Summon Terminal blueprint for example.

If in your custom contracts you're using solidity version higher than in demo contracts, then you need to update version of web3j libraries (web3j-maven-plugin and org.web3j.core) and version number in "EtherlinkerExampleProject\Content\IntegrationServer\compileContracts.bat/sh"

If in your custom contracts you're using open zeppelin contracts, make sure that they aren't duplicate existing demo contracts inside "EtherlinkerServer\Stratum\src\main\resources\solidity" (otherwise it's better to update them).

If you copied Infura URL from their website, make sure that you add "https://" prefix into it (so it will look like this: "https://rinkeby.infura.io/v3/XXX")

Updated