Byte Formatter

Installing

Using the native Unity Package Manager introduced in 2017.2, you can add this library as a package by modifying your manifest.json file found at /ProjectName/Packages/manifest.json to include it as a dependency. See the example below on how to reference it.

Install via OpenUPM

The package is available on the npmjs registry.

Add registry scope

{
  "dependencies": {
    ...
    "com.elestrago.unity.byte-formatter": "x.x.x",
    ...
  },
  "scopedRegistries": [
    {
      "name": "eLeSTRaGo",
      "url": "https://registry.npmjs.org",
      "scopes": [
        "com.elestrago.unity"
      ]
    }
  ]
}

Add package in PackageManager

Open Window -> Package Manager choose Packages: My Regestries and install package

Introduction

Byte formatter has different pices:

• ByteReader and ByteWriter
• State serialization
• Byte data validator
• State serialization principle

ByteReader and ByteWriter

Write data example:

public byte[] WriteBytesFromState(State state)
{
    var writer = new ByteWriter();
    writer.Write(state.Value1);
    writer.Write(state.Value2);
    return writer.ToArray();
}

The resulting array of bytes will contain data written in a strict sequence. Data reading should be carried out in the same sequence in which they were written.

Read data example:

public State WriteBytesFromState(byte[] bytes)
{
    var state = new State();
    var reader = new ByteReader(bytes);
    state.Value1 = reader.ReadInt32();
    state.Value2 = reader.ReadInt32();
    return state;
}

State serialization

Prepare classes for generation

Serialized class or struct must be public partial and has attribute [ByteSerializable]

Serializable data must have attribute [ByteField(ushort id)] where id >= 1

Serialized class example:

[ByteSerializable]
public partial class State
{
    [ByteField(1)] public int Value1 { get; set; }
    [ByteField(2)] public string Value2 { get; set; }
}

Warning!

If data added or removed or indexes number changed for serialization, you need to create migration

Add custom data writing and reading

Create static class and add specific attribute [ByteExtension] for custom extensions.

Example:

[ByteExtension]
public static class CustomByteFormatterExtensions{
    ...
}

Custom read or write extensions do not support generic types for generation.

Write extension

Method name must in start contains Write word and as argument you custom type.

Example:

public static void WriteMyCustomType(this ByteWriter writer, MyCustomType value)
{
    writer.Write((int) value);
}

Read extension

Method name must contains Read word and no any arguments.

Example:

public static MyCustomType ReadMyCustomType(this ByteReader reader)
{
    return (MyCustomType) reader.ReadInt32();
}

State serialization principle

Object mapping

Example state:

[ByteSerializable]
public partial class State
{
    [ByteField(1)] public int Value1 { get; set; }
    [ByteField(2)] public int Value2 { get; set; }
}

This is the object map of example state

| Name | Type | Size | Data | |------------------|--------|--------|--------| | Field Count | ushort | 2 byte | 2 | | Field Id 1 | ushort | 2 byte | 1 | | Field Data End 1 | int | 4 byte | 16 | | Field Id 2 | ushort | 2 byte | 2 | | Field Data End 2 | int | 4 byte | 18 | | Field Data 1 | int | 4 byte | Value1 | | Field Data 2 | int | 4 byte | Value2 |

Field Count - Total count of fields in object Field Id - Unique field id Field Data End - Last data byte beginning from fields map Field Data - Bytes stored in field