Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/deniszykov/msgpack-unity3d

MessagePack and JSON serializer for Unity3D
https://github.com/deniszykov/msgpack-unity3d

json json-serialization messagepack messagepack-serializer unity-asset unity-plugin unity3d

Last synced: about 1 month ago
JSON representation

MessagePack and JSON serializer for Unity3D

Awesome Lists containing this project

README 

        
[![Build Status](https://travis-ci.org/deniszykov/msgpack-unity3d.svg?branch=master)](https://travis-ci.org/deniszykov/msgpack-unity3d)



# Introduction



This [package](https://assetstore.unity.com/packages/tools/network/json-messagepack-serialization-59918) provides an API for data serialization/deserialization into [MessagePack](https://en.wikipedia.org/wiki/MessagePack) and [JSON](https://en.wikipedia.org/wiki/JSON) formats.



Supported Platforms:



* PC/Mac

* iOS

* Android

* WebGL



**API**



* JSON

  * Serialize

  * SerializeToString

  * Deserialize

* MsgPack

  * Serialize

  * Deserialize



## Installation



### NuGet



```bash

PM> Install-Package GameDevWare.Serialization

```



### Unity3D



[Json + MessagePack Serializer](https://assetstore.unity.com/packages/tools/network/json-messagepack-serialization-59918)



## Example



Serialize an object into a [Stream](https://msdn.microsoft.com/en-us/library/system.io.stream%28v=vs.90%29.aspx) using a MessagePack serializer:



```csharp

var outputStream = new MemoryStream();

MsgPack.Serialize(new { field1 = 1, field2 = 2 }, outputStream);

outputStream.Position = 0; // rewind stream before copying/reading

```



Deserialize an object from a [Stream](https://msdn.microsoft.com/en-us/library/system.io.stream%28v=vs.90%29.aspx) using a MessagePack serializer:



```csharp

Stream inputStream;

MsgPack.Deserialize(typeof(MyObject), inputStream); // -> instance of MyObject

// or

MsgPack.Deserialize(inputStream); // -> instance of MyObject

```



## Breaking Change in v2.0



### Message Pack Endianness



Message Pack serialization prior to v2.0 used a [little-endian](https://en.wikipedia.org/wiki/Endianness) byte order for multi-byte integers. That doesn't correspond to the [specification](https://github.com/msgpack/msgpack/blob/master/spec.md). Data saved with **little-endian** formatting could be re-written to **big-endian** with the following code:



```csharp

var context = new SerializationContext { Options = SerializationOptions.SuppressTypeInformation };

using (var fileStream = File.Open("", FileMode.Open, FileAccess.ReadWrite))

{

    var reader = new MsgPackReader(fileStream, context, Endianness.LittleEndian);

    var value = reader.ReadValue(typeof(object));

    fileStream.Position = 0;

    var writer = new MsgPackWriter(fileStream, context);

    writer.WriteValue(value, typeof(object));

    fileStream.SetLength(fileStream.Position);

}

```



### Data Contract Attributes



* The [IgnoreDataMember](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.ignoredatamemberattribute%28v=vs.110%29.aspx) attribute is only honored when used with unmarked types. This includes types that are not marked with the [DataContract](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute%28v=vs.110%29.aspx) attribute.

* You can apply the [DataMember](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.datamemberattribute%28v=vs.110%29.aspx) attribute to **PUBLIC** fields and properties.

* The [DataMember](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.datamemberattribute%28v=vs.110%29.aspx) and [IgnoreDataMember](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.ignoredatamemberattribute%28v=vs.110%29.aspx) attributes are ignored if they are applied to static members.

* The [DataMember](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.datamemberattribute%28v=vs.110%29.aspx) attribute is ignored if the [DataContract](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute%28v=vs.110%29.aspx) attribute is not applied.

* During serialization, property-get code is called for property data members to get the value of the properties to be serialized.

* During deserialization, a new object is first created by calling an empty constructor on the type. Then all data members are deserialized.

* During deserialization, property-set code is called for property data members to set the properties to the value being deserialized.



## Mapping Types



The MessagePack/Json serializer is guided by [Data Contract](https://msdn.microsoft.com/en-us/library/ms733127%28v=vs.110%29.aspx) rules. Its behavior can be changed with [DataContract](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractattribute%28v=vs.110%29.aspx), [DataMember](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.datamemberattribute%28v=vs.110%29.aspx), and [IgnoreDataMember](https://msdn.microsoft.com/en-us/library/system.runtime.serialization.ignoredatamemberattribute%28v=vs.110%29.aspx) attributes. Attributes can be from *System.Runtime.Serialization.dll* or your attributes with the same names.



## Supported Types



* Primitives: Boolean, Byte, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64, String

* Standard Types: Decimal, DateTimeOffset, DateTime, TimeSpan, Guid, Uri, Version, DictionaryEntry

* Unity3D Types: Bounds, Vector, Matrix4x4, Quaternion, Rect, Color

* Binary: Stream, byte[]

* Lists: Array, ArrayList, List, HashSet and any other [IEnumerable](https://msdn.microsoft.com/en-us/library/system.collections.ienumerable%28v=vs.110%29.aspx) types with an **Add** method.

* Maps: Hashtable, Dictionary, and other [IDictionary](https://msdn.microsoft.com/en-us/library/system.collections.idictionary%28v=vs.110%29.aspx) types

* [Nullable](https://msdn.microsoft.com/en-us/library/b3h38hb0%28v=vs.110%29.aspx) types

* Enums

* Custom classes



## Custom Type Serializers



To implement a custom [TypeSerializer](https://github.com/deniszykov/msgpack-unity3d/blob/master/Assets/Plugins/GameDevWare.Serialization/TypeSerializer.cs) you need to inherit from *TypeSerializer* and override the Deserialize and Serialize methods.



```csharp

public sealed class GuidSerializer : TypeSerializer

{

    public override Type SerializedType { get { return typeof(Guid); } }

    

    public override object Deserialize(IJsonReader reader)

    { 

        // General rule of 'Deserialize' is to leave reader on

        // last token of deserialized value. It is EndOfObject or EndOfArray, or Value.

        // 'nextToken: true' will call 'reader.NextToken()' AFTER 'ReadString()'.

        // Since it is last token on de-serialized value we set 'nextToken: false'.

        var guidStr = reader.ReadString(nextToken: false);

        var value = new Guid(guidStr);

        return value;

    }



    public override void Serialize(IJsonWriter writer, object valueObj)

    {

        var value = (Guid)valueObj; // valueObj is not null

        var guidStr = value.ToString();

        writer.Write(guidStr);

    }

}

```



Then you need to register your class in the *Json.DefaultSerializers* collection or mark it with the [TypeSerializerAttribute](https://github.com/deniszykov/msgpack-unity3d/blob/master/Assets/Plugins/GameDevWare.Serialization/TypeSerializerAttribute.cs).



## Extra Type Information



There is additional type information with each serialized object. It increases the size of the serialized data. If you do not want to store object's type information, specify *SuppressTypeInformation* when calling the **Serialize** method.



```csharp

MsgPack.Serialize(value, stream, SerializationOptions.SuppressTypeInformation);

```



If you want to ignore type information when deserializing an object, specify *SuppressTypeInformation* when calling the **Deserialize** method.



```csharp

MsgPack.Deserialize(typeof(MyObject), stream, SerializationOptions.SuppressTypeInformation);

```



## IL2CPP - AOT :grey_exclamation:



Additional preparation should be made for AOT execution platforms. A `link.xml` file should be added to the project's root folder. This file should exclude the _System.Runtime.Serialization.dll_ assembly from IL stripping. Read more about [IL code stripping](https://docs.unity3d.com/Manual/IL2CPP-BytecodeStripping.html) in the official documentation.



## Contacts

Please send any questions at [email protected]



## License

[MIT](License.md)