3.0 – TigerForge

Version 3.0

This version introduces an important feature: the Async class (inside the UniRESTClient class). Moreover, there are some little changes about the use of the Sirenix Odin Serializer and how the Tokens are managed now by the UniREST solution. For these reasons, you should read this page carefully before upgrading your existing project to UniREST 3.0.

About Odin Serializer and the UniRESTBinary class: https://tigerforge.altervista.org/docs/unirest-1-0/unirest-client/unirest-binary/
About the Tokens system: https://tigerforge.altervista.org/docs/unirest-1-0/getting-started/how-communication-works/

Known upgrading issues

Let’s start with some known issue when you upgrade your existing UniREST installation with the new 3.0 version.

Odin Serializer folder issue

The folder where the Odin Serializer folder is placed has changed! The old folder was TigerForge.OdinSerializer and now it’s simply OdinSerializer. When you upgrade to version 3.0, this is what may happen:

Practically, the old TigerForge.OdinSerializer folder (in this screenshot highlighted in yellow) is still there and raises the errors shown in the Unity Console.

Simply delete that folder. The new Odin Serializer is under the OdinSerializer folder!

UniRESTServer with more ZIP files

In a similar way, in the UniRESTServer folder you will find the new UniREST Server Application ZIP file with the old one:

Simply delete the old version and just keep the new, last version.

Remeber to install the new UniREST Server application in WordPress too!

UniRESTClientConfig.cs

When you import the new 3.0 asset, you should exclude the UniRESTClientConfig.cs file. This file is filled by your C# code from the UniREST Server application. If you import this file from the upgrade package, you get a “virgin” file you have to set again. This is not a serious issue, but just an annoying thing you can avoid.

Generic issues

These are some generic issues you can encounter using the Async methods.

User not still logged in

One of the problems of using Async methods is to have everything synchronized. This sounds like a non-sense, but, before using the methods for communicating with your Server, you must log in to the UniREST system. This means that you have to find a way to call your Server after you are completely sure to be entered the system. Indeed, if you’re not logged in, this is the kind of message you get in the Unity Console (if debugMode is activated):

The NO_AUTH response meaning is explaned here.

Supported Unity Versions

The new features require Unity 2019.4 and higher versions.

Async class

The UniRESTClient.Async class is the new entry of the 3.0 version. It exposes the various UniREST methods (like Read(), Write(), Update(), File class and so on) as asynchronous methods.

This is why you should seriously consider the use of this class:

asynchronous programming is a modern and efficient way to develop projects;
asynchronous functions don’t stop the execution of your Unity game. They run in parallel, while your game is still in execution, improving the system memory and CPU usage, and making the whole Unity system more efficient and stable;
these methods are fully compatible with the WebGL platform. So, using these methods, you can make your Unity Game work on all the platforms.
these methods use UniTask, a new and more efficient tasks system (look at here for more info: https://github.com/Cysharp/UniTask).

	PROS	CONS
UniRESTClient.Method()	They are lightweight and very easy to use. They are ideal if you need to perform a few server calls with small amount of data.	They are sync functions, so the game flow stops until the method is executed. They are not ideal for a lot of calls and not compatible with the WebGL platform.
UniRESTClient.Async.Method()	They are efficient and don’t stop the game execution, improving the performance. They are compatible with the WebGL platform.	The project must be developed taking into consideration the asynchronous nature of these methods.

From the C# development point of view, the difference between a sync and an async method is minimal. In general, a sync method is someting like this way:

var result = UniRESTClient.ReadOne<DB.Players>(
     API.player_data, 
     new DB.Players { id = UniRESTClient.UserID }
);

// The script that will use the result goes here!

In the Async class, a method like this one is similar, except for the use of a callback function:

_ = UniRESTClient.Async.ReadOne(
     API.player_data, 
     new DB.Players { id = UniRESTClient.UserID },
     (DB.Players result) => {

         // The script that will use the result goes here!

     });

Basically, the difference between the two example scripts above is that the first code blocks the game execution and continues only once the result is given, instead, the second code is executed like an independent program while the game is still running. Once the async call is completed, the callback function is called and the inside script is executed.

Don't mix sync methods with async methods. Sync and async are not just methods, but a new logic and approach of programming. If you choose to develop in async mode, use async methods only!

Because these methods are new, they have been tested a lot but can raise some issues. The Async class should be considered as a beta version.

Sirenix Odin Serializer

The Sirenix Odin Serializer is a powerful serialization system used by the UniRESTBinary class. This means that this tool is not directly involved in the operation of the UniREST Solution, but it’s just a tool used by a utility class.

Before UniREST Solution 3.0, the Odin Serializer was included in the UniREST Solution as source code, which requested the use of the .NET 4.0. It was the default serialization system used by the UniRESTBinary class and was incompatible with the WebGL platform because it wasn’t AOT compliant.

Starting from UniREST Solution 3.0, the Odin Serializer is included as 3 compiled DLLs: one for the WebGL platform, one for use in the Unity Editor and one for the other platforms (as you can see in the image below).

Moreover, the DLLs just need the classic .NET 2.0 framework and it’s no more the default serialization system of the UniRESTBinary class. Now, it’s the standard .NET serialization system.

	Included in the UniREST Solution as:	Requested .NET setting for the Unity Project:	WebGL Support
Old Odin Serializer	source code	.NET 4.0	NO
New Odin Serializer	3 DLLs: one for the AOT systems, one for the Editor, one for the other platforms.	.NET 2.0	YES

However, if you want to come back to the use of Odin Serializer there are no problems. It’s still integrated into the UniREST Solution ecosystem and it requires just to be enabled (see the UniRESTBinary chapter for details).

Tokens system

Together with the encryption, the Tokens system is a component involved in communications security. Basically, a Token is a random string constantly provided by the Server. When the Client communicates with the Server, it sends the Token back and the Server expects the Token is correct.

This simple system offers two levels of security. The first one is that if the Client message doesn’t contain the Token or the Token is wrong, the Server refuses the message and the communication fails. The second level requires the Token to periodically change. This makes the reuse of a previous message invalid because it contains an old Token.

Before UniREST Solution 3.0, the Writing Token (the token that manages the writings on the Database) changed every time a writing call was performed. Instead, the Reading Token (the token that manages the readings on the Database) didn’t change, but the UniRESTClient class has a method (ReadTokenUpdate() method) to request the Server to change it.

Starting from UniREST Solution 3.0, also the Writing Token doesn’t change and the UniRESTClient class has a method (WriteTokenUpdate() method) to request the Server to change it. This new approach comes from the integration of the Async class.

As explained earlier, asynchronous methods are performed in parallel. If the Tokens change automatically, the execution of an asynchronous method could invalidate the execution of another method. For this reason, with the use of these methods, the automatic change of Tokens is not possible. You will have to change the Tokens at the appropriate times when you know that all the operations on the database are completed.

However, if you are still using the synchronous methods, you can continue to take advantage of the automatic Token change. In this case, you have to enable two new properties: UpdateReadToken and UpdateWriteToken. When set to true, the Server will change the Tokens for every operation on the database.

Many developers love the opportunity to allow their users to register an account in WordPress and then develop a Unity project where these users can log in using that account credentials. The UniRESTClient class has a specific login method to do this: WPLogin().

Like the Login() method, WPLogin() allows a user to login into the UniREST system using an account registered in WordPress. The account can be registered directly in WordPress or a Unity project using the WPRegister() method.

However, if a user registers an account with the WordPress registration form, he has to provide a username, password, and other information. In particular, the email address. For this reason, many developers asked to have the WPLogin() method capable to allow the login using the email instead of the username. This mainly because the email is simpler to remember.

Now, the WPLogin() accepts an email as username parameter. See the WPLogin / WPRegistration chapter for details

UniREST Solution 3.5