BufferLayout

This package offers a simple and efficient way to manage buffers. It can be used to create buffer representations of certain data structurs like Vector2s, Vector3s, and CFrames. It can also be used to create custom data structures.

Features

• Type Safety: Leveraging TypeScript for stronger typing, reducing runtime errors.
• Data Validation: Includes methods for validating buffer data integrity, which can be disabled for performance.
• Structured Buffers: A clean and readable way to manage buffers, ensuring efficient memory usage.

Installation

To install the package, use the following command:

npm install @rbxts/bufferlayout

Usage

Import the module and utilize the BufferLayout class to manage your data buffers.

import { BufferLayout, Primitives } from '@rbxts/bufferlayout';

// Step 1: Define your buffer layout
// For example, a layout with an Unsigned 8-bit integer and a 32-bit float
const myLayout = new BufferLayout(Primitives.U8, Primitives.F32);

// Step 2: Setting Configurations
// For example, enabling validation and setting a custom error handler
// You can also retrieve these configurations by calling `myLayout.getConfigs()`
myLayout.setConfigs({
  validation: {
    enabled: true,
    onError: (index, message) => warn(`Validation Error at index ${index}: ${message}`),
  },
});

// Step 3: Create a LayoutObject
// For example, initializing with values 255 (for U8) and 123.456 (for F32)
const myObject = myLayout.create(255, 123.456);

// Step 4: Perform read/write operations

// Write new values
myObject.write(100, 789.012);

// Read values
const [myU8Value, myF32Value] = myObject.read();

// Output the read values
print("U8 Value:", myU8Value); // Should output 100
print("F32 Value:", myF32Value); // Should output 789.012


// NOTES:

// 1. If validation is enabled, the following will throw a warning:
myObject.write(256, 789.012); // U8 value is out of range

// 2. You can access the buffer directly
const trueBuffer = myObject.buffer;

// 3. Release the buffer when done.
// This clears the buffer and returns it to the cache.
// Doing this saves performance because it does not need to be re-allocated.
myObject.release();

API Reference

BufferLayout

• setConfigs(configs: Partial<LayoutConfigs>): Set configuration for buffer validation.
• getConfigs(): Retrieve current configuration settings.
• create(values: BufferLayoutTuple<T>): Create a new LayoutObject with the specified layout.

LayoutObject

• write(values: BufferLayoutTuple<T>): Write data to the buffer.
• read(): Read data from the buffer.
• release(): Release the buffer, clearing and returning it to the cache.

LayoutConfigs

LayoutConfigs are configurations used in the BufferLayout class to manage buffer validation and other settings in the future.

type LayoutConfigs = {
  validation: {
	enabled: boolean;
	onError: (index: number, value: number) => void;
  };
};

• validation
  • enabled
    • Type: boolean
    • Default: true
    • Description: Determines if validation is enabled. When true, buffer data will be checked for integrity based on the defined primitives.
  • onError
    • Type: Function (index: number, value: number) => void
    • Default: error(`Invalid value ${value} for field ${index}`)
    • Description: Callback function that is called when a validation error occurs. The function takes a string message as an argument, which describes the error.

Primitives

Primitives represent basic data types that can be used in buffer layouts. Each primitive type corresponds to a specific data type and size. String has been omitted from this package as (a) it is not a primitive type and (b) it is not a fixed-size data type. This package is designed to work with fixed-size data types.

U8

• Description: Unsigned 8-bit integer
• Byte Size: 1 byte
• Value Range: [0, 255]

I8

• Description: Signed 8-bit integer
• Byte Size: 1 byte
• Value Range: [-128, 127]

U16

• Description: Unsigned 16-bit integer
• Byte Size: 2 bytes
• Value Range: [0, 65535]

I16

• Description: Signed 16-bit integer
• Byte Size: 2 bytes
• Value Range: [-32768, 32767]

U32

• Description: Unsigned 32-bit integer
• Byte Size: 4 bytes
• Value Range: [0, 4294967295]

I32

• Description: Signed 32-bit integer
• Byte Size: 4 bytes
• Value Range: [-2147483648, 2147483647]

F32

• Description: 32-bit float
• Byte Size: 4 bytes
• Value Range: Approximately [-3.4028235e38, 3.4028235e38]
• Precision: ~7 decimal digits

F64

• Description: 64-bit float
• Byte Size: 8 bytes
• Value Range: Approximately [-1.7976931348623157e308, 1.7976931348623157e308]
• Precision: ~15 decimal digits