BitStream

SL: NET BitStream

This page was automatically translated from Russian by Google Translator

How to correctly work with data and transfer them using SL: NET
There are many ways to transfer data over UDP, but one of the most compact and fast, but not the most convenient, is BitStream. In general, the essence of this method is to compress data by means of translating non-typed Lua variables into a typed format, thereby saving on the size of the sent and received packet. SL: NET BitStream has two main methods: BitStream: write and BitStream: read. As you might guess, these methods allow you to write and read data. Also one of the main methods is BitStream: new - it allows you to create a BitStream for further filling. Let's take an example of how to write data: let's imagine that we have player data that we need to pack.

Let's imagine that we have a PlayerID, the maximum value of which is 255 characters, three coordinates of the Float type, and a PlayerName in string format.

local bitStream = BitStream: new () - first create a new BitStream
bitStream: write (UINT8, PlayerID) - UINT8 has a range of values ​​from 0 to 255, which is what you need
bitStream: write (FLOAT, coordX): write (FLOAT, coordY): write (FLOAT, coordZ)
- it is not necessary to start with the variable that stores the BitStream every time, it is enough to continue filling the data with the `write` method
bitStream: write (UINT8, #PlayerName): write (STRING, PlayerName) - write down the size of the string so that you can read it later

Now let's imagine that we received such a package and now we need to parse it in order to use this data in the future.

local PlayerID = bitStream: read (UINT8) - yes, just like that, now the PlayerID is full
local coord = {0, 0, 0}
for i = 1, 3 do
  coord [i] = bitStream: read (FLOAT) - data following each other can be read in a loop
end
local PlayerName = bitStream: read (STRING, bitStream: read (UINT8)) - but this is how you can read a string

It should be said that BitStream SL: NET is protected from invalid values, so even if there are no values ​​that you are trying to retrieve, a value of the correct type will be returned to you, but it will most likely be zero, or the character 0x0 if the returned result is character.

Import and export bytes from BitStream
The bytes from the filled BitStreams can be exported, and the unfilled ones (it is possible to fill them, but I do not recommend) can be imported. This is very convenient if you need to transfer BitStream for further processing, and your system uses any service data in the package. For example, at the beginning. Let's imagine that in each packet a value of type BOOL is passed, which shows some parameters, and then you need to get rid of it.

local myBool = bitStream: read (BOOL) - read the value, saved it to a variable
local exportData = bitStream: export () - export bytes, now it is a string variable
bitStream = BitStream: new () - re-create BitStream to clear old data from it
bitStream: import (exportData: sub (2, #exportData)) - import corrected for one character, because BOOL is 1 CHAR
bitStream: setWritePointer (1): setReadPointer (1) - reset read and write positions to one (optional)

If you know that the first step is to import, then you can create a BitStream with an initial set of bytes (start import).

local myBool = bitStream: read (BOOL) - read the value, saved it to a variable
local exportData = bitStream: export () - export bytes, now it is a string variable
bitStream = BitStream: new (exportData: sub (2, #exportData)) - re-create BitStream and immediately import data
bitStream: setWritePointer (1): setReadPointer (1) - reset read and write positions to one (optional)

Data types, their size in characters and range of values​​

• UINT8 - 1 character, number from 0 to 255
• UINT16 - 2 characters, a number from 0 to 65.535
• UINT32 - 4 characters, a number from 0 to 4,294,967,295
• INT8 - 1 character, number from -128 to 127
• INT16 - 2 characters, number from -32,768 to 32,767
• INT32 - 4 characters, numbers from -2,147,483,648 to 2,147,483,647
• BOOL - 1 character, TRUE / FALSE
• FLOAT - 4 characters, from -3.4E + 38 to + 3.4E + 38
• STRING - the number of characters is equal to the number of characters in a line