The UniRESTBinary class is a set of methods for working with binary data and performs various operations with bytes and Binary Strings. Basically, the main scopes of this class are:
- extracting bytes from different sources like files, Unity Resources files (Textures, Audio Clips, etc.) and data objects;
- converting a byte array into a simple Binary String (Base64 String) and vice-versa;
- easily save, load and delete local binary files.
Why bytes?
The bytes are the basic elements constituting any file. Figuratively, they are like atoms that are the basis of matter. From the bytes point of view, all files and objects are the same things: there’s no difference between an image and a 3d model, between a video and an array of strings. Just as bytes can be extracted from files and data, bytes can be reassembled into the original files and data. This means, for example, you can take the bytes from a video, a texture, a 3d model, and a data object, save all in one file and then read that file to get back the 4 original sources. It’s a very flexible format!
Binary Formatter and Odin Serializer
The UniRESTBinary class can use both the standard .NET binary formatter and the Sirenix Odin Serializer. Starting from the 3.0 version, the default serializer is the .NET binary formatter, while the Odin Serializer is still integrated into the UniREST Solution but disabled.
| PROS | CONS | |
| .NET binary formatter | It’s fast and lightweight. It’s supported by all the Unity platforms. | It’s very limited and can’t serialize too complex data. |
| Odin Serializer | It can serialize practically any kind of data. | It’s not light as .NET binary formatter. The WebGL platform requires the configuration of what Odin Serializer can serialize. |
Instantiate a UniRESTBinary object
The first thing to do for working with this class features is to declare an instance of the UniRESTBinary class. This will initialize the Binary engine.
| Parameter | Data-type | Description |
| serializerType | Enum (optional) | Default BinaryFormatter Set the serialization technology to use. OdinSerializer: the Sirenix Odin Serializer offers a sophisticated system ables of serializing practically any kind of data. It’s strictly recommended. BinaryFormatter: the standard .NET serialization technology. It’s very fast and efficient, but it lacks in the support of many data-type formats. |
| Returned value | Description |
| UniRESTBinary object | A UniRESTBinary instance object. |
Load binary data
Binary data can be extracted from different kinds of resources. The UniRESTBinary class has a set of Load* methods which get bytes from specific kind of resources. Once binary data is loaded, you can choose what to do with this data.
LoadFromFile()
The LoadFromFile() method reads bytes from a file. You can read:
- local files, providing the file name and selecting one of the available system folders;
- files from the Unity project Resources folders, providing the resource path and name, and selecting the kind of resource (TextAsset, Texture2D, Sprite, AudioClip).
| filePath | string | The file name or the name of a Resource. |
| sourcePosition | Enum (optional) | The local file position. PersistentDataPath by default. It can be: PersistentDataPath AssetsPath StreamingAssetsPath TemporaryCachePath UserDefined When selected, a full, complete filePath must be provided. Resources When selected, you can read files from the Resources folders. A resourceType parameter must be selected so as to use the right method of reading bytes. |
| resourceType | Enum (optional) | The type of resource. None by default. It can be: TextAsset Texture2D_JPG Texture2D_PNG Texture2D_EXR Texture2D_TGA Sprite_EXR* Sprite_JPG* Sprite_PNG* Sprite_TGA* AudioClip * Bytes are extracted from the Sprite’s Tetxure. |
| bool | This method just returns true or false. |
var myBinary = new UniRESTBinary();
// Read bytes from the "model.fbx" file, located in the PersistentDataPath Game's folder.
var result = myBinary.LoadFromFile("model.fbx");
// Read bytes from the "shoot" audio file, under the "myassets" subfolder,
// located in a Resources Unity Project's folder.
var result = myBinary.LoadFromFile(
"myassets/shoot",
UniRESTBinary.sourcePosition.Resources,
UniRESTBinary.resourceType.AudioClip
);
LoadFromData()
The LoadFromData() method reads bytes from a data object. The data can be anything that can be serialized.
| object | object | The data to read. |
| bool | This method just returns true or false. |
var myBinary = new UniRESTBinary();
var playerEquip = new List<Equipment>();
// Read bytes from "playerEquip" object.
var result = myBinary.LoadFromData(playerEquip);LoadFromBytes()
The LoadFromBytes() method loads bytes directly from a bytes array.
| bytes | bytes array | The bytes to load. |
var myBinary = new UniRESTBinary();
// Load bytes from "myFileContent" bytes array.
var result = myBinary.LoadFromBytes(myFileContent);LoadFromBinaryString()
The LoadFromBinaryString() method reads bytes from a binary string.
| binaryString | object | The binary string to read. |
| decompress | bool (optional) | Default false. If true, decompress bytes data. |
var myBinary = new UniRESTBinary();
// Read bytes from "playerEquip" object.
var result = myBinary.LoadFromBinaryString(myBinaryString);Convert and save binary data
Once binary data has been loaded, you can perform two kinds of operation:
- convert it, for example, in a binary string or back into the original data-type;
- save it in a local file.
ToString()
The ToString() method converts the loaded bytes into a binary string. The advantage is that the returned data is just a string, that is suitable to be saved as an ordinary string (for example, in a Database table).
| string | A Base64 string representation of the loaded bytes. |
ToObject()
The ToObject() method converts the loaded bytes or the given binary string back into the original object the bytes were taken from.
| TYPE | data-type | The data-type of the returned object. |
| binaryString | string (override) | The binary string to convert. |
| object | The object of the specified data-type. |
ToFile()
The ToFile() method saves the loaded bytes or the given binary string into a local file, in the device storage memory.
| filePath | string | The file name. |
| binaryString | string (override) | The binary string to convert. |
| localPosition | Enum (optional) | The local file position. PersistentDataPath by default. It can be: PersistentDataPath AssetsPath StreamingAssetsPath TemporaryCachePath UserDefined When selected, a full, complete filePath must be provided. Resources When selected, you can read files from the Resources folders. A resourceType parameter must be selected so as to use the right method of reading bytes. |
Compression
Once you have loaded bytes from a resource, you can compress this data in order to reduce its size or decompress this data if it was previously compressed.
var myBinary = new UniRESTBinary();
// Read bytes from the "model.fbx" file, located in the PersistentDataPath Game's folder.
var result = myBinary.LoadFromFile("model.fbx");
// If the bytes are correctly loaded from the .fbx file...
if (result)
{
// ...I compress the loaded bytes so as to reduce the memory size.
myBinary.CompressLoadedBytes();
. . .
}Password protection
Once you have loaded bytes from a resource, you can encrypt or decrypt that data with a password.
This methods return an encrypted or decrypted byte array.
Enabling the Odin Serializer
Starting from the 3.0 version, the Odin Serializer is integrated into the UniREST Solution as DLLs and disabled. If you want to use it, you have to enable it.
Go under the Core > OdinSerializer folder and edit the UniRESTOdinConfig.cs file. Here, you will find the UseOdinSerializer property set to false. Set it to true.
In the Types function below there are the definitions of some common data-types. These definitions are used by the AOT system when you are going to use the Odin Serializer with the WebGL platform. Feel free to add new types or comment on unwanted types.
Now, go under the Core folder and edit the UniRESTBinary.cs file. Here, you will find a commented define USE_ODIN_SERIALIZER line. Simply uncomment it.
Now, you can use Odin Serializer as serialization technique.