rules

.cursor/rules/roblox/reference/engine/libraries/buffer.yaml

@@ -0,0 +1,727 @@
+# This file is automatically generated. Please don't edit it manually.
+# To submit a bug report on the content, see
+# https://devforum.roblox.com/c/bug-reports/documentation-issues/72
+
+name: buffer
+type: library
+summary: |
+  A library of buffer functions.
+description: |
+  A buffer is an object that represents a fixed-size mutable block of memory.
+  The buffer library provides functions for creation and manipulation of buffer
+  objects, providing all its functions inside the global `Library.buffer`
+  variable.
+
+  Buffer is intended to be used a low-level binary data storage structure,
+  replacing the uses of `Library.string.pack()` and `Library.string.unpack()`.
+  Use cases include reading and writing existing binary formats, working with
+  data in a more compact form, serialization to custom binary formats, and
+  general work with native memory types like fixed-length integers and floats.
+
+  When passed through Roblox APIs, including sending a buffer through custom
+  events, the identity of the buffer object is not preserved and the target will
+  receive a copy. Similar to other limitations, the same buffer object cannot be
+  used from multiple `Class.Actor` scripts (Parallel Luau).
+
+  Many of the functions accept an offset in bytes from the start of the buffer.
+  Offset of `0` from the start of the buffer memory block accesses the first
+  byte. All offsets, counts and sizes should be non-negative integer numbers. If
+  the bytes that are accessed by any read or write operation are outside the
+  buffer memory, an error is thrown.
+
+  The `read` and `write` methods that work with integers and floats use
+  [little-endian](https://en.wikipedia.org/wiki/Endianness) encoding.
+tags: []
+code_samples: []
+properties: []
+functions:
+  - name: buffer.create
+    summary: |
+      Creates a buffer.
+    description: |
+      Creates a buffer of the requested size with all bytes initialized to `0`.
+      Size limit is 1 GiB, or 1,073,741,824 bytes. Keep in mind that larger
+      buffers might fail to allocate if device is running low on memory.
+    parameters:
+      - name: size
+        type: number
+        default:
+        summary: |
+          Size of the buffer in bytes. Must be a positive integer.
+    returns:
+      - type: buffer
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.fromstring
+    summary: |
+      Creates a buffer from a string.
+    description: |
+      Creates a buffer initialized to the contents of the string. The size of
+      the buffer equals the length of the string.
+    parameters:
+      - name: str
+        type: string
+        default:
+        summary: ''
+    returns:
+      - type: buffer
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.tostring
+    summary: |
+      Converts a buffer to a string.
+    description: |
+      Returns the buffer data as a string.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+    returns:
+      - type: string
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.len
+    summary: |
+      Returns the size of the buffer in bytes.
+    description: |
+      Returns the size of the buffer in bytes.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readbits
+    summary: |
+      Reads a range of bits into an unsigned integer from the buffer based on a
+      specific `bitCount` integer from `0` to `32`, inclusive.
+    description: |
+      Reads a range of bits into an unsigned integer from the buffer based on a
+      specific `bitCount` integer from `0` to `32`, inclusive. For example:
+
+      - `buffer.readbits(b, 0, 8)` is equivalent to
+        `Library.buffer.readu8(b, 0)`.
+      - `buffer.readbits(b, 0, 16)` is equivalent to
+        `Library.buffer.readu16(b, 0)`.
+      - `buffer.readbits(b, 0, 32)` is equivalent to
+        `Library.buffer.readu32(b, 0)`.
+      - `buffer.readbits(b, 0, 24)` reads 24 bits from the buffer.
+
+      Note that `0` bit width is supported only to not error in generalized
+      cases where bit count is dynamic, and reading 0 bits returns `0`. Also
+      note that, since the max size of the buffer is 1 GB, `bitOffset`
+      cannot be handled as a 32‑bit integer number like byte offset in other
+      buffer functions.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: bitOffset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: bitCount
+        type: number
+        default:
+        summary: |
+          Integer bit count to read. Error is thrown if this value is not in
+          range of `0` to `32`, inclusive.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readi8
+    summary: |
+      Reads an 8-bit signed integer from the buffer.
+    description: |
+      Reads the data from the buffer by reinterpreting bytes at the offset as an
+      8-bit signed integer and converting it into a number.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readu8
+    summary: |
+      Reads an 8-bit unsigned integer from the buffer.
+    description: |
+      Reads the data from the buffer by reinterpreting bytes at the offset as an
+      8-bit unsigned integer and converting it into a number.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readi16
+    summary: |
+      Reads a 16-bit signed integer from the buffer.
+    description: |
+      Reads the data from the buffer by reinterpreting bytes at the offset as a
+      16-bit signed integer and converting it into a number.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readu16
+    summary: |
+      Reads a 16-bit unsigned integer from the buffer.
+    description: |
+      Reads the data from the buffer by reinterpreting bytes at the offset as a
+      16-bit unsigned integer and converting it into a number.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readi32
+    summary: |
+      Reads a 32-bit signed integer from the buffer.
+    description: |
+      Reads the data from the buffer by reinterpreting bytes at the offset as a
+      32-bit signed integer and converting it into a number.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readu32
+    summary: |
+      Reads a 32-bit unsigned integer from the buffer.
+    description: |
+      Reads the data from the buffer by reinterpreting bytes at the offset as a
+      32-bit unsigned integer and converting it into a number.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readf32
+    summary: |
+      Reads a 32-bit floating-point value from the buffer.
+    description: |
+      Reads the data from the buffer by reinterpreting bytes at the offset as a
+      32-bit floating-point value and converting it into a number. If the
+      floating-point value matches any bit patterns that represent `NaN` (not a
+      number), the returned value may be converted to a different quiet `NaN`
+      representation.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readf64
+    summary: |
+      Reads a 64-bit floating-point value from the buffer.
+    description: |
+      Reads the data from the buffer by reinterpreting bytes at the offset as a
+      64-bit floating-point value and converting it into a number. If the
+      floating-point value matches any bit patterns that represent `NaN` (not a
+      number), the returned value may be converted to a different quiet `NaN`
+      representation.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+    returns:
+      - type: number
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writebits
+    summary: |
+      Writes data to the buffer based on a specific `bitCount` integer from `0`
+      to `32`, inclusive.
+    description: |
+      Writes data to the buffer based on a specific `bitCount` integer from `0`
+      to `32`, inclusive. `value` is treated as an unsigned 32‑bit number and
+      only `bitCount` least significant bits are written.
+
+      Note that `0` bit width is supported only to not error in generalized
+      cases where bit count is dynamic, and writing 0 bits has no effect. Also
+      note that, since the max size of the buffer is 1 GB, `bitOffset`
+      cannot be handled as a 32‑bit integer number like byte offset in other
+      buffer functions.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: bitOffset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: bitCount
+        type: number
+        default:
+        summary: |
+          Integer bit count to write. Error is thrown if this value is not in
+          range of `0` to `32`, inclusive.
+      - name: value
+        type: number
+        default:
+        summary: |
+          Unsigned 32‑bit number. Only `bitCount` least significant bits are
+          written.
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writei8
+    summary: |
+      Writes an 8-bit signed integer to the buffer.
+    description: |
+      Writes data to the buffer by converting the number into an 8-bit signed
+      integer and writing a single byte.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          An integer number in range [-128, 127].
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writeu8
+    summary: |
+      Writes an 8-bit unsigned integer to the buffer.
+    description: |
+      Writes data to the buffer by converting the number into an 8-bit unsigned
+      integer and writing a single byte.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          An integer number in range [0, 255].
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writei16
+    summary: |
+      Writes a 16-bit signed integer to the buffer.
+    description: |
+      Writes data to the buffer by converting the number into a 16-bit signed
+      integer and reinterpreting it as individual bytes.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          An integer number in range [-32,768, 32,767].
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writeu16
+    summary: |
+      Writes a 16-bit unsigned integer to the buffer.
+    description: |
+      Writes data to the buffer by converting the number into a 16-bit unsigned
+      integer and reinterpreting it as individual bytes.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          An integer number in range [0, 65,535].
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writei32
+    summary: |
+      Writes a 32-bit signed integer to the buffer.
+    description: |
+      Writes data to the buffer by converting the number into a 32-bit signed
+      integer and reinterpreting it as individual bytes.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          An integer number in range [-2,147,483,648, 2,147,483,647].
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writeu32
+    summary: |
+      Writes a 32-bit unsigned integer to the buffer.
+    description: |
+      Writes data to the buffer by converting the number into a 32-bit unsigned
+      integer and reinterpreting it as individual bytes.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          An integer number in range [0, 4,294,967,295].
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writef32
+    summary: |
+      Writes a 32-bit floating-point value to the buffer.
+    description: |
+      Writes data to the buffer by converting the number into a 32-bit
+      floating-point value and reinterpreting it as individual bytes.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          A single-precision floating-point number.
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writef64
+    summary: |
+      Writes a 64-bit floating-point value to the buffer.
+    description: |
+      Writes data to the buffer by converting the number into a 64-bit
+      floating-point value and reinterpreting it as individual bytes.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          A double-precision floating-point number.
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.readstring
+    summary: |
+      Reads a string from the buffer.
+    description: |
+      Reads a string of length `count` from the buffer at the specified
+      `offset`.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: count
+        type: number
+        default:
+        summary: |
+          Length to read.
+    returns:
+      - type: string
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.writestring
+    summary: |
+      Writes a string to the buffer.
+    description: |
+      Writes data from a string into the buffer at the specified `offset`. If an
+      optional `count` is specified, only `count` bytes are taken from the
+      string.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: ''
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: string
+        default:
+        summary: |
+          Data to write.
+      - name: count
+        type: number?
+        default:
+        summary: |
+          Number of bytes to take from the string. This value cannot be larger
+          than the string length.
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.copy
+    summary: |
+      Copies bytes between buffers.
+    description: |
+      Copies `count` bytes from `source` starting at offset `sourceOffset` into
+      the `target` at `targetOffset`.
+
+      It's possible for `source` and `target` to be the same. Copying an
+      overlapping region inside the same buffer acts as if the source region is
+      copied into a temporary buffer and then that buffer is copied over to the
+      target.
+    parameters:
+      - name: target
+        type: buffer
+        default:
+        summary: |
+          Buffer to copy data into.
+      - name: targetOffset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: source
+        type: buffer
+        default:
+        summary: |
+          Buffer to take the data from.
+      - name: sourceOffset
+        type: number?
+        default: 0
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: count
+        type: number?
+        default:
+        summary: |
+          Number of bytes to copy. If omitted, the whole `source` data starting
+          from `sourceOffset` is taken.
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''
+  - name: buffer.fill
+    summary: |
+      Sets a region of the buffer memory to some 8-bit unsigned integer value.
+    description: |
+      Sets `count` bytes in the buffer starting at the specified `offset` to
+      `value`.
+    parameters:
+      - name: b
+        type: buffer
+        default:
+        summary: |
+          Buffer to write the data into.
+      - name: offset
+        type: number
+        default:
+        summary: |
+          Offset from the beginning of the buffer memory, starting from `0`.
+      - name: value
+        type: number
+        default:
+        summary: |
+          An integer number in range [0, 255].
+      - name: count
+        type: number?
+        default:
+        summary: |
+          Number of bytes to write. If omitted, all bytes after the specified
+          offset are set.
+    returns:
+      - type: ()
+        summary: ''
+    tags: []
+    code_samples: []
+    deprecation_message: ''