serialize data into memory More...

Public Member Functions
MemBlock	getDataPtr ()
	get the serialized data More...

number	getDataSize ()
	get the size of the serialized data More...

	serialize_1 (int val)
	serialize 1 signed byte More...

	serialize_1u (uint val)
	serialize 1 unsigned byte More...

	serialize_2 (int val)
	serialize 2 signed bytes More...

	serialize_2u (uint val)
	serialize 2 unsigned bytes More...

	serialize_3u (uint val)
	serialize 3 unsigned bytes More...

	serialize_4 (int val)
	serialize 4 signed bytes More...

	serialize_4u (uint val)
	serialize 4 unsigned bytes More...

	serialize_8 (number val)
	serialize 8 signed bytes More...

	serialize_8u (number val)
	serialize 8 unsigned bytes More...

	serialize_bool (boolean val)
	serialize a 1 bit boolean value More...

	serialize_color (Color val)
	serialize a Color More...

	serialize_d (number val)
	serialize a double precision floating point number More...

	serialize_f (number val)
	serialize a single precision floating point number More...

	serialize_mem (BinaryString mem)
	serialize a binary string More...

	serialize_mem (MemBlock mem)
	serialize a block of memory More...

	serialize_obj (ISerializable obj)
	serialize a serializable object More...

	serialize_offset (Offset val)
	serialize an Offset's (x,y) values More...

	serialize_point (Point val)
	serialize a Point's (x,y) values More...

	serialize_quad (Quad val)
	serialize a Quad's (x,y) point values More...

	serialize_rect (Rect val)
	serialize a Rect's left, top, right, bottom values More...

	serialize_ref (object obj)

	serialize_rotr (RotatedRect val)
	serialize a RotatedRect's data values More...

	serialize_str (string str)
	serialize a JavaScript string More...

	serialize_uint (uint val)
	serialize up to 4 unsigned bytes More...

	serialize_vector (Vector val)
	serialize a Vector's (x,y) values More...

uint	sizeof_1 (int val)

uint	sizeof_1u (uint val)

uint	sizeof_2 (int val)

uint	sizeof_2u (uint val)

uint	sizeof_3u (uint val)

uint	sizeof_4 (int val)

uint	sizeof_4u (uint val)

uint	sizeof_8 (int val)

uint	sizeof_8u (uint val)

uint	sizeof_bool (boolean val)
	get the number of bytes used to serialize the given boolean More...

uint	sizeof_color (Color val)
	get the number of bytes used to serialize the given Color More...

uint	sizeof_d (number val)

uint	sizeof_f (number val)

uint	sizeof_mem (BinaryString mem)

uint	sizeof_mem (MemBlock mem)
	get the number of bytes used to serialize the given block of memory More...

uint	sizeof_obj (ISerializable val)
	get the number of bytes used to serialize the given object, including any objects that it serializes More...

uint	sizeof_offset (Offset val)
	get the number of bytes used to serialize the given Offset More...

uint	sizeof_point (Point val)
	get the number of bytes used to serialize the given Point More...

uint	sizeof_quad (Quad val)
	get the number of bytes used to serialize the given Quad More...

uint	sizeof_rect (Rect val)
	get the number of bytes used to serialize the given Rect More...

uint	sizeof_ref (object val)

uint	sizeof_rotr (RotatedRect val)
	get the number of bytes used to serialize the given RotatedRect More...

uint	sizeof_str (string val)
	get the number of bytes used to serialize the given string More...

uint	sizeof_uint (uint val)
	get the number of bytes used to serialize the given unsigned integer More...

uint	sizeof_vector (Vector val)
	get the number of bytes used to serialize the given Vector More...

Detailed Description

serialize data into memory

Precondition: API Stability: 3 - Stable. The API has proven satisfactory, but cleanup in the underlying code may cause minor changes. Backwards-compatibility is guaranteed.

Serializer stores complex data into memory in a way that it can be read back from a Deserializer. It can correctly store entire object hierarchies without duplication.

The data stream format is platform neutral, so it is suitable for saved game files and network messages between client and server, using NetConnection.send(ISerializable).

Serializer writes tags at key points that the deserialization process can use to be sure things haven't gotten out of sync. However, if you want your serialized data streams to be versioned, you will have to add that yourself; either on a per object/message basis or for an entire saved stream.

Method Groups

serialize_x(x): These methods write the given data of type x into the stream. When x is a number (ie: serialize_1 or serialize_2u) the number represents the number of bytes that will be used in the data stream. Others, such as uint, str, mem and obj are all variable sized based on the actual data passed in.
serialized_Size(x) - These methods get the number of bytes of data that would be written into the stream to serialize that particular bit of data. These are only used for the variable size data types.

See Also: Deserializer; ISerializable; NetConnection.send(ISerializable)

Member Function Documentation

getDataPtr ( )

get the serialized data

Returns: a MemBlock object with the serialized data.

Note: This is really only useful after one or more serialize_X methods have been called to actually write data into the memory block.

See Also: getDataSize; Deserializer.setDataPtr

getDataSize ( )

get the size of the serialized data

Returns: the number of bytes of data in the serialized data. This is the same value that would be returned by calling the getDataSize() method of the MemBlock returned by getDataPtr()

Note: This is really only useful after one or more serialize_X methods have been called to actually write data into the memory block.

See Also: getDataPtr

serialize_1 ( int val )

serialize 1 signed byte

Write a one byte value in the range of −127 to 127 into the data stream.

Warning: if the value is outside the range then only the info from the least significant byte will be written into the serialized data stream

Note: data size: 1 byte

See Also: Deserializer.deserialize_1

serialize_1u ( uint val )

serialize 1 unsigned byte

Write a one byte value in the range of 0 to 255 into the data stream.

Warning: if the value is outside the range then only the info from the least significant byte will be written into the serialized data stream

Note: data size: 1 byte

See Also: Deserializer.deserialize_1u

serialize_2 ( int val )

serialize 2 signed bytes

Write a two byte value in the range of −32,767 to 32,767 into the data stream.

Warning: if the value is outside the range then only the info from the least significant two bytes will be written into the serialized data stream

Note: data size: 2 bytes

See Also: Deserializer.deserialize_2

serialize_2u ( uint val )

serialize 2 unsigned bytes

Write a two byte value in the range of 0 to 65,535 into the data stream.

Warning: if the value is outside the range then only the info from the least significant two bytes will be written into the serialized data stream

Note: data size: 2 bytes

See Also: Deserializer.deserialize_2u

serialize_3u ( uint val )

serialize 3 unsigned bytes

Write a three byte value in the range of 0 to 16,777,216 into the data stream.

Warning: if the value is outside the range then only the info from the least significant three bytes will be written into the serialized data stream.

Note: data size: 3 bytes

Remarks: there is no serialize_3(signed int); use serialize_4 instead

See Also: Deserializer.deserialize_3u

serialize_4 ( int val )

serialize 4 signed bytes

Write a four byte value in the range of −2,147,483,647 to 2,147,483,647 into the data stream.

Warning: if the value is outside the range then only the info from the least significant four bytes will be written into the serialized data stream.

Note: data size: 4 bytes

See Also: Deserializer.deserialize_4

serialize_4u ( uint val )

serialize 4 unsigned bytes

Write a four byte value in the range of 0 to 4,294,967,295 into the data stream.

Warning: if the value is outside the range then only the info from the least significant four bytes will be written into the serialized data stream.

Note: data size: 4 bytes

See Also: Deserializer.deserialize_4u

serialize_8 ( number val )

serialize 8 signed bytes

Write an eight byte value in the range of −9,223,372,036,854,775,807 to 9,223,372,036,854,775,807 into the data stream.

Warning: JavaScript doesn't directly support 64-bit Integers, so for very large values expect some precision to be lost in the conversion between JavaScript's native double and 64-bit Integer. You might want to use serialize_d() instead.

Note: data size: 8 bytes

See Also: Deserializer.deserialize_8

serialize_8u ( number val )

serialize 8 unsigned bytes

Write an eight byte value in the range of 0 to 18,446,744,073,709,551,615 into the data stream.

Warning: JavaScript doesn't directly support 64-bit Integers, so for very large values expect some precision to be lost in the conversion between JavaScript's native double and 64-bit Integer. You might want to use serialize_d() instead.

Note: data size: 8 bytes

See Also: Deserializer.deserialize_8u

serialize_bool ( boolean val )

serialize a 1 bit boolean value

Write a one bit boolean value (true or false) into the data stream. This is optimized collect up to 8 bits in a single byte, so writing a number of boolean values is very space efficient.

Note: data size: varies, call serializedSize(bool) to determine

See Also: serializedSize(bool); Deserializer.deserialize_bool()

serialize_color ( Color val )

serialize a Color

Write a Color's RBGA values into the data stream.

Warning: the Color is written as a 24 (no alpha channel) or 32 bit color (with alpha channel). If you need to preserve greater color precision than this, you will need to serialize the components yourself.

Note: data size: varies, call serializedSize(Color) to determine

See Also: serializedSize(Color); Deserializer.deserialize_color()

serialize_d ( number val )

serialize a double precision floating point number

Write a double precision floating point value in the range of 10⁻³⁰⁸ to 10³⁰⁸ with 17 significant digits into the data stream.

Warning: if the value is outside the range then the results are unknown.

Note: data size: 8 bytes (IEEE 754-2008 binary64 format)

See Also: Deserializer.deserialize_d

serialize_f ( number val )

serialize a single precision floating point number

Write a single precision floating point value in the range of 10⁻³⁸ to 10³⁸ with 9 significant digits into the data stream.

Warning: if the value is outside the range then the results are unknown.

Note: data size: 4 bytes (IEEE 754-2008 binary32 format)

See Also: Deserializer.deserialize_f

serialize_mem ( BinaryString mem )

serialize a binary string

Binary strings are a Node.js way of handling blocks of arbitrary binary data. This serializes that data into the stream.

Deprecated:: Node.js maintainers have deprecated BinaryString, so it may not be around in future versions

Note: data size: varies, call serializedSize(MemBlock) to determine. Because binary strings used 2 bytes for each actual byte stored, the serialized data takes less memory than the original string.

See Also: serialize_mem(MemBlock); serializedSize(MemBlock); Deserializer.deserialize_mem

serialize_mem ( MemBlock mem )

serialize a block of memory

MemBlocks are the game engine's way of handling blocks of arbitrary binary data in JavaScript. This serializes that data into the stream.

Note: data size: varies, call serializedSize(MemBlock) to determine.

See Also: serializedSize(MemBlock); Deserializer.deserialize_mem

serialize_obj ( ISerializable obj )

serialize a serializable object

This serializes the object and all its data into the stream. It does this by calling the ISerializable object's serialize method, which would then in turn call serializer methods for each of the object's data members. If the given object's data members include other serializable objects, then serialize_obj() is called recursively to serialize those objects.

The Serializer keeps track of what objects have already been added to the stream, and simply serializes a reference to any object that has already been serialized if serialize_obj is called for it again.

Note: data size: varies, call serializedSize() to determine.

See Also: serializedSize(ISerializable); Deserializer.deserialize_obj; ISerializable

serialize_offset ( Offset val )

serialize an Offset's (x,y) values

Write an Offset's x and y values into the data stream. This is optimized for certain common cases, such as a (0,0) offset and small positive numbers.

Warning: because JavaScript handles floating-point numbers as doubles internally but an Offset is streamed using floats, some precision is lost. If you need that precision you should serialize the Offset's x and y values yourself using serialize_d()

Note: data size: varies, call serializedSize(Offset) to determine

See Also: serializedSize(Offset); Deserializer.deserialize_offset()

serialize_point ( Point val )

serialize a Point's (x,y) values

Write a Point's x and y values into the data stream. This is optimized for certain common cases, such as Point(0,0) and small positive numbers.

Warning: because JavaScript handles floating-point numbers as doubles internally but a Point is streamed using floats, some precision is lost. If you need that precision you should serialize the Point's x and y values yourself using serialize_d()

Note: data size: varies, call serializedSize(Point) to determine

See Also: serializedSize(Point); Deserializer.deserialize_point()

serialize_quad ( Quad val )

serialize a Quad's (x,y) point values

Write a Quad's four sets of x and y values into the data stream.

Warning: because JavaScript handles floating-point numbers as doubles internally but a Quad is streamed using floats, some precision is lost. If you need that precision you should serialize the Quad's array of x and y values yourself using serialize_d()

Note: data size: varies, call serializedSize(Quad) to determine

See Also: serializedSize(Quad); Deserializer.deserialize_quad()

serialize_rect ( Rect val )

serialize a Rect's left, top, right, bottom values

Write a Rect's left, top, right, and bottom values into the data stream. This is optimized for certain common cases, such as empty rectangles and small positive numbers.

Warning: because JavaScript handles floating-point numbers as doubles internally but a Rect is streamed using floats, some precision is lost. If you need that precision you should serialize the Rect's left, top, right, and bottom values yourself using serialize_d()

Note: data size: varies, call serializedSize(Rect) to determine

See Also: serializedSize(Rect); Deserializer.deserialize_rect()

serialize_ref ( object obj )

serialize_rotr ( RotatedRect val )

serialize a RotatedRect's data values

Write a RotatedRect's left, top, right, bottom, radians and centerOffset values into the data stream. This is optimized for certain common cases, such as empty rectangles, small positive numbers, and no center offset.

Warning: because JavaScript handles floating-point numbers as doubles internally but a RotatedRect is streamed using floats, some precision is lost. If you need that precision you should serialize the RotatedRect's left, top, right, bottom, radians, centerOffset.x and centerOffset.y values yourself using serialize_d()

Note: data size: varies, call serializedSize(RotatedRect) to determine

See Also: serializedSize(RotatedRect); Deserializer.deserialize_rotr()

serialize_str ( string str )

serialize a JavaScript string

Writes the string into the data stream.

Note: data size: varies, call serializedSize() to determine. Format is Unicode UTF-8.

See Also: serializedSize(string); Deserializer.deserialize_str

serialize_uint ( uint val )

serialize up to 4 unsigned bytes

Write a value in the range of 0 to 4,294,967,295 into the data stream. This is optimized for cases where the number is usually small, but can sometimes be quite large. If the number is usually large, you are better off just using serialize_4u.

Note: data size: varies, 1 to 5 bytes, call serializedSize() to determine.

See Also: serializedSize(uint); serialize_4u; Deserializer.deserialize_uint

serialize_vector ( Vector val )

serialize a Vector's (x,y) values

Write a Vector's x and y values into the data stream. This is optimized for certain common cases, such as a (0,0) offset and small positive numbers.

Warning: because JavaScript handles floating-point numbers as doubles internally but a Vector is streamed using floats, some precision is lost. If you need that precision you should serialize the Vector's x and y values yourself using serialize_d()

Note: data size: varies, call serializedSize(Vector) to determine

See Also: serializedSize(Vector); Deserializer.deserialize_vector()

uint sizeof_1 ( int val )

uint sizeof_1u ( uint val )

uint sizeof_2 ( int val )

uint sizeof_2u ( uint val )

uint sizeof_3u ( uint val )

uint sizeof_4 ( int val )

uint sizeof_4u ( uint val )

uint sizeof_8 ( int val )

uint sizeof_8u ( uint val )

sizeof_bool ( boolean val )

get the number of bytes used to serialize the given boolean

Does not actually write any data to stream

Returns: the number of bytes needed (0 or 1)

Note: this will often return 0, which simply means that the particular boolean bit is being stored along with other boolean bits in a previously reserved space in the stream, so no additional bytes were needed

See Also: serialize_bool

sizeof_color ( Color val )

get the number of bytes used to serialize the given Color

Does not actually write any data to stream

Returns: the number of bytes needed (3-5)

See Also: serialize_color

uint sizeof_d ( number val )

uint sizeof_f ( number val )

uint sizeof_mem ( BinaryString mem )

sizeof_mem ( MemBlock mem )

get the number of bytes used to serialize the given block of memory

Does not actually write any data to stream

Returns: the number of bytes needed

See Also: serialize_mem

sizeof_obj ( ISerializable obj )

get the number of bytes used to serialize the given object, including any objects that it serializes

Does not actually write any data to stream

Returns: the number of bytes needed

See Also: serialize_obj

sizeof_offset ( Offset val )

get the number of bytes used to serialize the given Offset

Does not actually write any data to stream

Returns: the number of bytes needed (0-9)

Note: this can return 0 for an offset whose value is (0,0), since a zero offset is optimized to be stored as a single bit.

See Also: serialize_offset

sizeof_point ( Point val )

get the number of bytes used to serialize the given Point

Does not actually write any data to stream

Returns: the number of bytes needed (0-9)

Note: this can return 0 for a Point whose value is (0,0), since a point at origin is optimized to be stored as a single bit.

See Also: serialize_point

sizeof_quad ( Quad val )

get the number of bytes used to serialize the given Quad

Does not actually write any data to stream

Returns: the number of bytes needed (0-34)

Note: this can return 0 under some conditions, such as a Quad made up of 4 points at the origin, which is optimized to be stored in 4 bits.

See Also: serialize_quad

sizeof_rect ( Rect val )

get the number of bytes used to serialize the given Rect

Does not actually write any data to stream

Returns: the number of bytes needed (0-17)

Note: this can return 0 under some conditions, such as an Rect located at (0,0) with zero width or height, which is optimized to be stored in 2 bits.