BitStream

Scrap Mechanic uses a stream of bits to serialize and deserialize all network packets. Most packets only use whole bytes, but some packets use bits that are not aligned to byte boundaries. This page describes the BitStream format.

BitStream format

Internally, the BitStream contains a buffer of bytes and a bit index. The bit index is the number of bits that have been read from or written to the buffer.

The BitStream is read and written from left to right. The bit index is incremented after each read or write operation by the number of bits that were read or written.

Example 1

The following example shows a BitStream with a buffer of 3 bytes. The bit index starts at 0. The following operations are performed:

1. An unsigned 8-bit integer with the value 0x11 is written to the BitStream.
2. An unsigned 16-bit big-endian integer with the value 0x2233 is written to the BitStream.

The BitStream now contains the following data:

Byte Index	0								1								2
Bit Index	0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23
Bit Value	0	0	0	1	0	0	0	1	0	0	1	0	0	0	1	0	0	0	1	1	0	0	1	1
Byte Value	0x11								0x22								0x33
Field	8-bit integer								16-bit integer

Because only whole bytes were written, the individual bytes of the buffer reflect the bytes that were written. The bit index after the write operations is 24.

Example 2

The following example shows a BitStream with a buffer of 4 bytes. The bit index starts at 0. The following operations are performed:

1. A boolean flag bit with the value 1 is written to the BitStream.
2. An unsigned 8-bit integer with the value 0x11 is written to the BitStream.
3. An unsigned 16-bit big-endian integer with the value 0x2233 is written to the BitStream.

The BitStream now contains the following data:

Byte Index	0								1								2								3
Bit Index	0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23	24	25	26	27	28	29	30	31
Bit Value	1	0	0	0	1	0	0	0	1	0	0	1	0	0	0	1	0	0	0	1	1	0	0	1	1	0	0	0	0	0	0	0
Byte Value	0x88								0x91								0x19								0x80
Field	bool	8-bit integer								16-bit integer																Alignment padding

Notice how the boolean flag bit is stored in the first bit of the first byte, offsetting the other bits by 1. It is now very difficult to see where the individual bytes start and end. The bit index after the write operations is 25.