hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-24 06:34:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update rules

Browse source
This commit is contained in:
Joe 2026-02-02 14:05:11 -06:00
parent 4c390fdd37
commit d5522b2fef
8549 changed files with 11783 additions and 1888 deletions
Download patch file Download diff file Expand all files Collapse all files

491
.cursor/rules/roblox/en-us/reference/engine/libraries/bit32.yaml Normal file
View file

@ -0,0 +1,491 @@
# 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: bit32
type: library
summary: |
A library of functions to perform bitwise operations.
description: |
This library provides functions to perform bitwise operations.
#### Number Limitations
This library treats numbers as unsigned 32-bit integers; numbers will be
converted to this before being used (see image below). Numbers with decimal
numbers are rounded to the nearest whole number.
<img src="../../../assets/engine-api/libraries/bit32/32-Bit-Restriction.png" width="500" alt="32-bit integer conversion (in hexadecimal)" />
tags: []
code_samples: []
properties: []
functions:
- name: bit32.arshift
summary: |
Returns a number after its bits have been arithmetically shifted to the
right by a given displacement.
description: |
Returns the number `x` shifted `disp` bits to the right. The number `disp`
may be any representable integer. Negative displacements shift to the
left.
This shift operation is what is called arithmetic shift. Vacant bits on
the left are filled with copies of the higher bit of `x`; vacant bits on
the right are filled with zeros. In particular, displacements with
absolute values higher than 31 result in zero or 0xFFFFFFFF (all original
bits are shifted out).
parameters:
- name: x
type: number
default:
summary: |
The number whose bits shall be shifted.
- name: disp
type: number
default:
summary: |
The integer number of bits to shift by.
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.band
summary: |
Returns the bitwise AND of all provided numbers.
description: |
Returns the bitwise AND of all provided numbers.
Each bit is tested against the following truth table:
<table>
<thead>
<tr>
<th>A</th>
<th>B</th>
<th>Output</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
<td>1</td>
</tr>
</tbody>
</table>
<img src="../../../assets/engine-api/libraries/bit32/AND.png" width="500" alt="Bitwise AND of 3 numbers" />
parameters:
- name: numbers
type: Tuple
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.bnot
summary: |
Returns the bitwise negation of a given number.
description: |
Returns the bitwise negation of `x`.
<img src="../../../assets/engine-api/libraries/bit32/NOT.png" width="500" alt="Negation of a provided number" />
For any integer `x`, the following identity holds:
```lua
assert(bit32.bnot(x) == (-1 - x) % 2^32)
```
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.bor
summary: |
Returns the bitwise OR of all provided numbers.
description: |
Returns the bitwise OR of all provided numbers.
Each bit is tested against the following truth table:
<table>
<thead>
<tr>
<th>A</th>
<th>B</th>
<th>Output</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>0</td>
<td>1</td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
<td>1</td>
</tr>
</tbody>
</table>
<img src="../../../assets/engine-api/libraries/bit32/OR.png" width="500" alt="Bitwise OR of 3 numbers" />
parameters:
- name: numbers
type: Tuple
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.btest
summary: |
Returns a boolean describing whether the bitwise and of its operands is
different from zero.
description: |
Returns a boolean signalling whether the bitwise _and_ of its operands is
different from zero.
parameters:
- name: numbers
type: Tuple
default:
summary: ''
returns:
- type: bool
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.bxor
summary: |
Returns the bitwise XOR of all provided numbers.
description: |
Returns the bitwise XOR of all provided numbers.
Each bit is tested against the following truth table:
<table>
<thead>
<tr>
<th>A</th>
<th>B</th>
<th>Output</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>0</td>
<td>1</td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
<td>0</td>
</tr>
</tbody>
</table>
<img src="../../../assets/engine-api/libraries/bit32/XOR.png" width="580" alt="Bitwise XOR of 3 numbers" />
parameters:
- name: numbers
type: Tuple
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.byteswap
summary: |
Returns the given number with the order of the bytes swapped.
description: |
Returns the given number with the order of the bytes swapped.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.countlz
summary: |
Returns the number of consecutive zero bits in the 32-bit representation
of the provided number starting from the left-most (most significant) bit.
description: |
Returns the number of consecutive zero bits in the 32-bit representation
of the provided number starting from the left-most (most significant) bit.
Returns 32 if the provided number is zero.
parameters:
- name: 'n'
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.countrz
summary: |
Returns the number of consecutive zero bits in the 32-bit representation
of the provided number starting from the right-most (least significant)
bit.
description: |
Returns the number of consecutive zero bits in the 32-bit representation
of the provided number starting from the right-most (least significant)
bit. Returns 32 if the provided number is zero.
parameters:
- name: 'n'
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.extract
summary: |
Extract a range of bits from a number and return them as an unsigned
number.
description: |
Returns the unsigned number formed by the bits `field` to
`field + width - 1` from `n`. Bits are numbered from 0 (least significant)
to 31 (most significant). All accessed bits must be in the range [0, 31].
The default for `width` is 1.
parameters:
- name: 'n'
type: number
default:
summary: ''
- name: field
type: number
default:
summary: ''
- name: width
type: number
default: 1
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.replace
summary: |
Return a copy of a number with a range of bits replaced by a given value.
description: |
Returns a copy of `n` with the bits `field` to `field + width - 1`
replaced by the value `v`. See `Library.bit32.extract()` for details about
`field` and `width`.
parameters:
- name: 'n'
type: number
default:
summary: ''
- name: v
type: number
default:
summary: ''
- name: field
type: number
default:
summary: ''
- name: width
type: number
default: 1
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.lrotate
summary: |
Returns a number after its bits have been rotated to the left by a given
number of times.
description: |
Returns the number `x` rotated `disp` bits to the left. The number `disp`
may be any representable integer. For any valid displacement, the
following identity holds:
```lua
assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))
```
In particular, negative displacements rotate to the right.
parameters:
- name: x
type: number
default:
summary: ''
- name: disp
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.lshift
summary: |
Returns a number whose bits have been logically shifted to the left by a
given displacement.
description: |
Returns the number `x` shifted `disp` bits to the left. The number `disp`
may be any representable integer. Negative displacements shift to the
right. In any direction, vacant bits are filled with zeros. In particular,
displacements with absolute values higher than 31 result in zero (all bits
are shifted out).
<img src="../../../assets/engine-api/libraries/bit32/LSHIFT.png" width="500" alt="Number shifted 3 to the left" />
For positive displacements, the following equality holds:
```lua
assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)
```
parameters:
- name: x
type: number
default:
summary: ''
- name: disp
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.rrotate
summary: |
Returns a number after its bits have been rotated to the right by a given
number of times.
description: |
Returns the number `x` rotated `disp` bits to the right. The number `disp`
may be any representable integer.
For any valid displacement, the following identity holds:
```lua
assert(bit32.rrotate(x, disp) == bit32.rrotate(x , disp % 32))
```
In particular, negative displacements rotate to the left.
parameters:
- name: x
type: number
default:
summary: ''
- name: disp
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: bit32.rshift
summary: |
Returns a number whose bits have been logically shifted to the right by a
given displacement.
description: |
Returns the number `x` shifted `disp` bits to the right. The number `disp`
may be any representable integer. Negative displacements shift to the
left. In any direction, vacant bits are filled with zeros. In particular,
displacements with absolute values higher than 31 result in zero (all bits
are shifted out).
<img src="../../../assets/engine-api/libraries/bit32/RSHIFT.png" width="500" alt="Number shifted 3 to the right" />
For positive displacements, the following equality holds:
```lua
assert(bit32.rshift(b, disp) == (b % 2^32 / 2^disp) // 1)
```
This shift operation is what is called logical shift.
parameters:
- name: x
type: number
default:
summary: ''
- name: disp
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''

727
.cursor/rules/roblox/en-us/reference/engine/libraries/buffer.yaml Normal file
View file

@ -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&nbsp;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&nbsp;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: ''

299
.cursor/rules/roblox/en-us/reference/engine/libraries/coroutine.yaml Normal file
View file

@ -0,0 +1,299 @@
# 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: coroutine
type: library
summary: |
A function that executes alongside the main thread.
description: |
A **coroutine** is used to perform multiple tasks at the same time from within
the same script. Such tasks might include producing values from inputs or
performing work on a subroutine when solving a larger problem. A task doesn't
even need to have a defined ending point, but it does need to define
particular times at which it **yields** (pause) to let other things be worked
on.
## Using Coroutines
A new coroutine can be created by providing a function to
`Library.coroutine.create()`. Once created, a coroutine doesn't begin running
until the first call to `Library.coroutine.resume()` which passes the
arguments to the function. This call returns when the function either halts or
calls `Library.coroutine.yield()` and, when this happens,
`Library.coroutine.resume()` returns either the values returned by the
function, the values sent to `Library.coroutine.yield()`, or an error message.
If it does error, the second return value is the thrown error.
```lua
local function task(...)
-- This function might do some work for a bit then yield some value
coroutine.yield("first") -- To be returned by coroutine.resume()
-- The function continues once it is resumed again
return "second"
end
local taskCoro = coroutine.create(task)
-- Call resume for the first time, which runs the function from the beginning
local success, result = coroutine.resume(taskCoro, ...)
print(success, result) --> true, first (task called coroutine.yield())
-- Continue running the function until it yields or halts
success, result = coroutine.resume(taskCoro)
print(success, result) --> true, second (task halted because it returned "second")
```
During the lifetime of the coroutine, you can call
`Library.coroutine.status()` to inspect its status:
<table>
<thead>
<tr>
<th>Status</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>suspended</b></td> <td>The coroutine is waiting to be
resumed. Coroutines begin in this state and enter it when their
function calls <code>coroutine.yield()</code>.</td>
</tr>
<tr>
<td><b>running</b></td>
<td>The coroutine is running right now.</td>
</tr>
<tr>
<td><b>normal</b></td> <td>The coroutine is awaiting the yield of
another coroutine; in other words, it has resumed another
coroutine.</td>
</tr>
<tr>
<td><b>dead</b></td> <td>The function has halted (returned or
thrown an&nbsp;error). The coroutine cannot be used further.</td>
</tr>
</tbody>
</table>
### Wrapping Coroutines
When working with coroutines, you can also forgo the use of the coroutine
object and instead use a wrapper function. Such a wrapper function will resume
a particular coroutine when it is called and will return only the yielded
values. You can do this using `Library.coroutine.wrap()`:
```lua
-- Create coroutine and return a wrapper function that resumes it
local f = coroutine.wrap(task)
-- Resume the coroutine as if we called coroutine.resume()
local result = f()
-- If an error occurs it will be raised here!
-- This differs from coroutine.resume() which acts similar to pcall()
```
The first value returned from `Library.coroutine.resume()` describes whether a
coroutine ran without errors. However, functions returned by
`Library.coroutine.wrap()` will not do this: instead they directly return the
values returned or passed to `Library.coroutine.yield()`, if any. Should an
error have occurred while running the coroutine function, the error is raised
on the call of the returned function.
### Producer Pattern Example
Imagine a task that produces repetitions of a word: each time it produces a
repetition, the next one will produce one more. For example, providing `Hello`
will produce `Hello`, `HelloHello`, `HelloHelloHello`, etc. To do this, you
can define `repeatThis()`:
```lua
-- This function repeats a word every time its coroutine is resumed
local function repeatThis(word)
local repetition = ""
while true do
-- Do one repetition then yield the result
repetition = repetition .. word
coroutine.yield(repetition)
end
end
```
To run this function as a coroutine, you can use `Library.coroutine.create()`
followed by multiple calls to `Library.coroutine.resume()`:
```lua
local repetitionCoro = coroutine.create(repeatThis)
print(coroutine.resume(repetitionCoro, "Hello")) -- true, Hello
print(coroutine.resume(repetitionCoro)) -- true, HelloHello
print(coroutine.resume(repetitionCoro)) -- true, HelloHelloHello
```
For this producer function, you can also use `Library.coroutine.wrap()` to get
a function that produces values:
```lua
local f = coroutine.wrap(repeatThis)
print(f("Hello")) -- Hello
print(f()) -- HelloHello
print(f()) -- HelloHelloHello
```
tags: []
code_samples: []
properties: []
functions:
- name: coroutine.close
summary: |
Closes and puts the provided coroutine in a dead state.
description: |
Closes and puts the provided coroutine in a dead state. This function
returns `true` unless the coroutine is in an error state, in which case it
returns `false` and the error message. A coroutine that is currently
running cannot be closed. A coroutine cannot be resumed after it is
closed.
parameters:
- name: co
type: thread
default:
summary: ''
returns:
- type: bool
summary: |
`true` unless the coroutine being closed is in an error state.
- type: Variant<string, void>
summary: |
The error message, if any.
tags: []
code_samples: []
deprecation_message: ''
- name: coroutine.create
summary: |
Creates a new coroutine, with body f. f must be a Luau function.
description: |
Creates a new coroutine, with body f. f must be a Luau function.
parameters:
- name: f
type: function
default:
summary: ''
returns:
- type: thread
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: coroutine.isyieldable
summary: |
Returns `true` if the coroutine this function is called within can safely
yield.
description: |
Returns `true` if the coroutine this function is called within can safely
yield. Yielding a coroutine inside metamethods or C functions is
prohibited, with the exception of `pcall` and `xpcall`.
parameters: []
returns:
- type: bool
summary: |
Whether or not the coroutine can safely yield at this point.
tags: []
code_samples: []
deprecation_message: ''
- name: coroutine.resume
summary: |
Starts or continues the execution of coroutine `co`.
description: |
Starts or continues the execution of coroutine `co`. The first time you
resume a coroutine, it starts running its body. The values `...` are
passed as the arguments to the body function. If the coroutine has
yielded, resume restarts it; the values `...` are passed as the results
from the yield. If the coroutine runs without any errors, resume returns
true plus any values passed to yield (if the coroutine yields) or any
values returned by the body function (if the coroutine terminates). If
there is any error, resume returns false plus the error message.
parameters:
- name: co
type: thread
default:
summary: ''
- name: ...
type: Variant
default:
summary: ''
returns:
- type: bool
summary: ''
- type: Variant<Tuple, string>
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: coroutine.running
summary: |
Returns the running coroutine.
description: |
Returns the running coroutine.
parameters: []
returns:
- type: thread
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: coroutine.status
summary: |
Returns the status of coroutine co as a string.
description: |
Returns the status of coroutine co, as a string: 'running', if the
coroutine is running (that is, it called status); 'suspended', if the
coroutine is suspended in a call to yield, or if it has not started
running yet; 'normal' if the coroutine is active but not running (that is,
it has resumed another coroutine); and 'dead' if the coroutine has
finished its body function, or if it has stopped with an error.
parameters:
- name: co
type: thread
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: coroutine.wrap
summary: |
Creates a new coroutine and returns a function that, when called, resumes
the coroutine.
description: |
Creates a new coroutine, with body f. f must be a Luau function. Returns a
function that resumes the coroutine each time it is called. Any arguments
passed to the function behave as the extra arguments to resume. Returns
the same values returned by resume, except the first boolean. In case of
error, propagates the error.
parameters:
- name: f
type: function
default:
summary: ''
returns:
- type: function
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: coroutine.yield
summary: |
Suspends execution of the coroutine.
description: |
Suspends the execution of the calling coroutine. Any arguments to yield
are passed as extra results to resume. Yielding a coroutine inside
metamethods or C functions is prohibited, with the exception of `pcall`
and `xpcall`.
parameters:
- name: ...
type: Tuple
default:
summary: ''
returns:
- type: Tuple<Variant>
summary: ''
tags: []
code_samples: []
deprecation_message: ''

409
.cursor/rules/roblox/en-us/reference/engine/libraries/debug.yaml Normal file
View file

@ -0,0 +1,409 @@
# 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: debug
type: library
summary: |
This library provides functions useful for debugging and profiling code.
description: |
Provides a few basic functions for debugging code in Roblox. Unlike the
`Library.debug` library found in Lua natively, this version has been heavily
sandboxed.
tags: []
code_samples: []
properties: []
functions:
- name: debug.traceback
summary: |
Returns a string of undefined format that describes the current function
call stack.
description: |
Returns a traceback of the current function call stack as a string; in
other words, a description of the functions that have been called up to
this point. During debugging, this behaves like an error stack trace but
does not stop execution of the script.
The `level` parameter specifies what level of the call stack to consider,
with `1` being the call of `Library.debug.traceback()` itself, `2` being
the call of the function calling `Library.debug.traceback()`, and so on.
See the code sample below for an example of sequential function calls.
Note that this function will often return inaccurate results (compared to
the original source code) and that the format of the returned traceback
may change at any time. You should **not** parse the return value for
specific information such as script names or line numbers.
The following example includes sequential function calls; `fnB()` is
called, and it calls `fnA()` which then calls `Library.debug.traceback()`.
```lua
local function fnA()
print(debug.traceback("Specific moment during fnA()"))
end
local function fnB()
fnA()
end
-- Call function fnB() to begin traceback
fnB()
```
parameters:
- name: message
type: string
default: ''
summary: |
The first line of the returned string.
- name: level
type: number
default: 1
summary: |
The number of calls "up" the call stack to return.
returns:
- type: string
summary: |
Traceback of the current function call stack.
tags: []
code_samples: []
deprecation_message: ''
- name: debug.traceback
summary: |
Returns a string of undefined format that describes the current function
call stack.
description: |
Returns a traceback of the current function call stack as a string; in
other words, a description of the functions that have been called up to
this point. During debugging, this behaves like an error stack trace but
does not stop execution of the script.
The `level` parameter specifies what level of the call stack to consider,
with `1` being the call of `Library.debug.traceback()` itself, `2` being
the call of the function calling `Library.debug.traceback()`, and so on.
See the code sample below for an example of sequential function calls.
Note that this function will often return inaccurate results (compared to
the original source code) and that the format of the returned traceback
may change at any time. You should **not** parse the return value for
specific information such as script names or line numbers.
The following example includes sequential function calls; `fnB()` is
called, and it calls `fnA()` which then calls `Library.debug.traceback()`.
```lua
local function fnA()
print(debug.traceback("Specific moment during fnA()"))
end
local function fnB()
fnA()
end
-- Call function fnB() to begin traceback
fnB()
```
parameters:
- name: thread
type: thread
default:
summary: |
A thread as returned by `Library.coroutine.create()`.
- name: message
type: string
default: ''
summary: |
The first line of the returned string.
- name: level
type: number
default: 1
summary: |
The number of calls "up" the call stack to return.
returns:
- type: string
summary: |
Traceback of the current function call stack.
tags: []
code_samples: []
deprecation_message: ''
- name: debug.info
summary: |
Traverses the entire stack of current thread and returns a string
containing the call stack of target level details.
description: |
Allows programmatic inspection of the call stack. This function differs
from `Library.debug.traceback()` in that it guarantees the format of the
data it returns. This is useful for general logging and filtering purposes
as well as for sending the data to systems expecting structured input,
such as crash aggregation.
```lua
local function fnA()
-- Output source identifier ("s") and line ("l") at levels 1 and 2
print(debug.info(1, "sl")) --> fnA() 3
print(debug.info(2, "sl")) --> fnA() 7
end
fnA()
```
Note that this function is similar to
[debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
the standard Lua library which serves a similar purpose.
parameters:
- name: level
type: number
default:
summary: |
Determines at what level of the call stack the information returned
should describe. A value of `1` represents the function which is
calling `Library.debug.info()`, a value of `2` represents the function
that called that function, and so on.
- name: options
type: string
default:
summary: |
A string that describes what the returned information should
represent. It must only contain 0 or 1 instances of the characters
`slnaf`, each representing a piece of information:
- `s` ([string](/luau/strings.md)) — The function source identifier,
equal to the full name of the script the function is defined in.
- `l` ([number](/luau/numbers.md)) — The line number of the function
call represented by `level`.
- `n` ([string](/luau/strings.md)) — The name of the function; may be
`nil` for anonymous functions and C functions without an assigned
debug name.
- `a` ([number](/luau/numbers.md), [boolean](/luau/booleans.md)) —
Arity of the function, which refers to the parameter count and
whether the function is variadic.
- `f` ([function](/luau/functions.md)) — The function which was
inspected.
returns:
- type: Tuple
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: debug.info
summary: |
Traverses the entire stack of current thread and returns a string
containing the call stack of target function details.
description: |
Allows programmatic inspection of the call stack. This function differs
from `Library.debug.traceback()` in that it guarantees the format of the
data it returns. This is useful for general logging and filtering purposes
as well as for sending the data to systems expecting structured input,
such as crash aggregation.
```lua
local function fnA()
end
local function fnB()
end
-- Output line ("l"), name ("n"), and identifier ("f") for both fnA() and fnB()
print(debug.info(fnA, "lnf")) --> 1 fnA function: 0x75e3d3c398a81252
print(debug.info(fnB, "lnf")) --> 5 fnB function: 0x6022a6dc5ccf4ab2
```
Note that this function is similar to
[debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
the standard Lua library which serves a similar purpose.
parameters:
- name: function
type: function
default:
summary: |
The function of the call stack which the information returned should
describe.
- name: options
type: string
default:
summary: |
A string that describes what the returned information should
represent. It must only contain 0 or 1 instances of the characters
`slnaf`, each representing a piece of information:
- `s` ([string](/luau/strings.md)) — The function source identifier,
equal to the full name of the script the function is defined in.
- `l` ([number](/luau/numbers.md)) — The line that `function` is
defined on.
- `n` ([string](/luau/strings.md)) — The name of the function; may be
`nil` for anonymous functions and C functions without an assigned
debug name.
- `a` ([number](/luau/numbers.md), [boolean](/luau/booleans.md)) —
Arity of the function, which refers to the parameter count and
whether the function is variadic.
- `f` ([function](/luau/functions.md)) — The function which was
inspected.
returns:
- type: Tuple
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: debug.info
summary: |
Traverses the entire stack of target thread and returns a string
containing the call stack of target level details.
description: |
Allows programmatic inspection of the call stack. This function differs
from `Library.debug.traceback()` in that it guarantees the format of the
data it returns. This is useful for general logging and filtering purposes
as well as for sending the data to systems expecting structured input,
such as crash aggregation.
```lua
local function fnA()
-- Output source identifier ("s") and line ("l") at levels 1 and 2
print(debug.info(1, "sl")) --> fnA() 3
print(debug.info(2, "sl")) --> fnA() 7
end
fnA()
```
Note that this function is similar to
[debug.getinfo](https://www.lua.org/pil/23.1.html), an unavailable part of
the standard Lua library which serves a similar purpose.
parameters:
- name: thread
type: thread
default:
summary: |
A thread as returned by `Library.coroutine.create()`.
- name: level
type: number
default:
summary: |
Determines at what level of the call stack the information returned
should describe. A value of `1` represents the function which is
calling `Library.debug.info()`, a value of `2` represents the function
that called that function, and so on.
- name: options
type: string
default:
summary: |
A string that describes what the returned information should
represent. It must only contain 0 or 1 instances of the characters
`slnaf`, each representing a piece of information:
- `s` ([string](/luau/strings.md)) — The function source identifier,
equal to the full name of the script the function is defined in.
- `l` ([number](/luau/numbers.md)) — The line number of the function
call represented by `level`.
- `n` ([string](/luau/strings.md)) — The name of the function; may be
`nil` for anonymous functions and C functions without an assigned
debug name.
- `a` ([number](/luau/numbers.md), [boolean](/luau/booleans.md)) —
Arity of the function, which refers to the parameter count and
whether the function is variadic.
- `f` ([function](/luau/functions.md)) — The function which was
inspected.
returns:
- type: Tuple
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: debug.profilebegin
summary: |
Starts profiling for a label.
description: |
Starts profiling for a
[MicroProfiler](../../../studio/microprofiler/index.md) label.
parameters:
- name: label
type: string
default:
summary: |
The text that this
[MicroProfiler](../../../studio/microprofiler/index.md) label
displays.
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: debug.profileend
summary: |
Stops profiling for the most recent label that
`Library.debug.profilebegin()` opened.
description: |
Stops profiling for the most recent
[MicroProfiler](../../../studio/microprofiler/index.md) label that
`Library.debug.profilebegin()` opened.
parameters: []
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: debug.getmemorycategory
summary: |
Returns the name of the current thread's active memory category.
description: |
Returns the name of the current thread's active memory category.
parameters: []
returns:
- type: string
summary: |
The current thread's active memory category.
tags: []
code_samples: []
deprecation_message: ''
- name: debug.setmemorycategory
summary: |
Assigns a custom tag to the current thread's memory category.
description: |
Assigns a custom tag name to the current thread's memory category in the
[Developer Console](../../../studio/developer-console.md). Useful for
analyzing memory usage of multiple threads in the same script which would
otherwise be grouped together under the same tag/name. Returns the name of
the current thread's previous memory category.
parameters:
- name: tag
type: string
default:
summary: ''
returns:
- type: string
summary: |
The current thread's previous memory category.
tags: []
code_samples: []
deprecation_message: ''
- name: debug.resetmemorycategory
summary: |
Resets the tag assigned by `Library.debug.setmemorycategory()` to the
automatically assigned value (typically, the script name).
description: |
Resets the tag assigned by `Library.debug.setmemorycategory()` to the
automatically assigned value (typically, the script name).
parameters: []
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: debug.dumpcodesize
summary: |
Displays a table of native code size of individual functions and scripts.
description: |
Displays a table of native code size of individual functions and scripts.
This function is only available in the Command Bar in Studio. More details
can be found on the
[Native Code Generation](../../../luau/native-code-gen.md) page.
parameters: []
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''

726
.cursor/rules/roblox/en-us/reference/engine/libraries/math.yaml Normal file
View file

@ -0,0 +1,726 @@
# 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: math
type: library
summary: |
A library of math functions.
description: |
This library is an interface to the standard C math library, providing all of
its functions inside the `Library.math` table.
tags: []
code_samples: []
properties:
- name: math.huge
type: number
summary: |
Returns a value larger than or equal to any other numerical value (about
2<sup>1024</sup>).
description: |
Returns a value larger than or equal to any other numerical value (about
2<sup>1024</sup>). Dividing a positive number by zero yields this same
value.
tags: []
code_samples: []
deprecation_message: ''
- name: math.pi
type: number
summary: |
The value of pi.
description: |
The value of pi.
tags: []
code_samples: []
deprecation_message: ''
functions:
- name: math.abs
summary: |
Returns the absolute value of `x`.
description: |
Returns the absolute value of `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.acos
summary: |
Returns the arc cosine of `x`.
description: |
Returns the arc cosine of `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.asin
summary: |
Returns the arc sine of `x`.
description: |
Returns the arc sine of `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.atan
summary: |
Returns the arc tangent of `x` in radians.
description: |
Returns the arc tangent of `x` in radians.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.atan2
summary: |
Returns the arc tangent of `y`/`x` (in radians) while using the signs of
both parameters to find the quadrant of the result.
description: |
Returns the arc tangent of `y`/`x` (in radians) while using the signs of
both parameters to find the quadrant of the result. It also handles
correctly the case of `x` being zero.
parameters:
- name: 'y'
type: number
default:
summary: ''
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.ceil
summary: |
Returns the smallest integer larger than or equal to `x`.
description: |
Returns the smallest integer larger than or equal to `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.clamp
summary: |
Returns a number between `min` and `max`, inclusive.
description: |
Returns a number between `min` and `max`, inclusive.
parameters:
- name: x
type: number
default:
summary: ''
- name: min
type: number
default:
summary: ''
- name: max
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.cos
summary: |
Returns the cosine of `x`, assumed to be in radians.
description: |
Returns the cosine of `x`, assumed to be in radians.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.cosh
summary: |
Returns the hyperbolic cosine of `x`.
description: |
Returns the hyperbolic cosine of `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.deg
summary: |
Returns the angle `x` (given in radians) in degrees.
description: |
Returns the angle `x` (given in radians) in degrees.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.exp
summary: |
Returns the value `e`^`x`.
description: |
Returns the value `e`^`x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.floor
summary: |
Returns the largest integer smaller than or equal to `x`.
description: |
Returns the largest integer smaller than or equal to `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.fmod
summary: |
Returns the remainder of the division of `x` by `y` that rounds the
quotient towards zero.
description: |
Returns the remainder of the division of `x` by `y` that rounds the
quotient towards zero.
parameters:
- name: x
type: number
default:
summary: ''
- name: 'y'
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.frexp
summary: |
Returns `m` and `e` such that `x` = `m`\*`2`^`e`.
description: |
Returns `m` and `e` such that `x` = `m`\*`2`^`e`. `e` is an integer and
the absolute value of `m` is in the range of `0.5` to `1` (inclusive of
`0.5` but exclusive of `1`), or zero when `x` is zero.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.ldexp
summary: |
Returns `x`\*`2`^`e` (`e` should be an integer).
description: |
Returns `x`\*`2`^`e` (`e` should be an integer).
parameters:
- name: x
type: number
default:
summary: ''
- name: e
type: int
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.lerp
summary: |
Returns the linear interpolation between `a` and `b`.
description: |
Returns the linear interpolation between `a` and `b` based on the factor
`t`.
This function uses the formula `a`+`(b-a)`\*`t`. `t` is typically between
`0` and `1` but values outside this range are acceptable.
parameters:
- name: a
type: number
default:
summary: |
The starting value.
- name: b
type: number
default:
summary: |
The ending value.
- name: t
type: number
default:
summary: |
The interpolation factor, typically between `0` and `1`.
returns:
- type: number
summary: |
The interpolated value between `a` and `b`.
tags: []
code_samples: []
deprecation_message: ''
- name: math.log
summary: |
Returns the logarithm of `x` using the given base.
description: |
Returns the logarithm of `x` using the given base, or the mathematical
constant `e` if no base is provided (natural logarithm).
parameters:
- name: x
type: number
default:
summary: ''
- name: base
type: number
default: 2.7182818
summary: |
The base of the logarithm, the constant `e` by default.
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.log10
summary: |
Returns the base-10 logarithm of `x`.
description: |
Returns the base-10 logarithm of `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.map
summary: |
Returns the value of `x` mapped from one range to another.
description: |
Returns a value that represents `x` mapped linearly from the input range
(`inmin` to `inmax`) to the output range (`outmin` to `outmax`). This is
achieved by determining the relative position of `x` within the input
range and applying that ratio to the output range.
parameters:
- name: x
type: number
default:
summary: |
The number to be mapped.
- name: inmin
type: number
default:
summary: |
The lower bound of the input range.
- name: inmax
type: number
default:
summary: |
The upper bound of the input range.
- name: outmin
type: number
default:
summary: |
The lower bound of the output range.
- name: outmax
type: number
default:
summary: |
The upper bound of the output range.
returns:
- type: number
summary: |
The value of `x` mapped to the output range.
tags: []
code_samples: []
deprecation_message: ''
- name: math.max
summary: |
Returns the maximum value among the numbers passed to the function.
description: |
Returns the maximum value among the numbers passed to the function.
parameters:
- name: x
type: number
default:
summary: ''
- name: ...
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.min
summary: |
Returns the minimum value among the numbers passed to the function.
description: |
Returns the minimum value among the numbers passed to the function.
parameters:
- name: x
type: number
default:
summary: ''
- name: ...
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.modf
summary: |
Returns two numbers: the integral part of `x` and the fractional part of
`x`.
description: |
Returns two numbers: the integral part of `x` and the fractional part of
`x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.noise
summary: |
Returns a Perlin noise value.
description: |
Returns a Perlin noise value. The returned value is most often between the
range of `-1` to `1` (inclusive) but sometimes may be outside that range;
if the interval is critical to you, use `Library.math.clamp(noise, -1, 1)`
on the output.
If you leave arguments out, they will be interpreted as zero, so
`Library.math.noise(1.158)` is equivalent to
`Library.math.noise(1.158, 0, 0)` and `Library.math.noise(1.158, 5.723)`
is equivalent to `Library.math.noise(1.158, 5.723, 0)`.
Note that this function uses a Perlin noise algorithm to assign fixed
values to coordinates. For example, `Library.math.noise(1.158, 5.723)`
will always return `0.48397532105446` and `Library.math.noise(1.158, 6)`
will always return `0.15315161645412`.
If `x`, `y`, and `z` are all integers, the return value will be `0`. For
fractional values of `x`, `y`, and `z`, the return value will gradually
fluctuate between `-0.5` and `0.5`. For coordinates that are close to each
other, the return values will also be close to each other.
parameters:
- name: x
type: number
default:
summary: ''
- name: 'y'
type: number
default: 0
summary: ''
- name: z
type: number
default: 0
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.pow
summary: |
Returns `x`^`y`.
description: |
Returns `x`^`y` (you can also use the expression `x`^`y` to compute this
value).
parameters:
- name: x
type: number
default:
summary: ''
- name: 'y'
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.rad
summary: |
Returns the angle `x` (given in degrees) in radians.
description: |
Returns the angle `x` (given in degrees) in radians.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.random
summary: |
Returns a random number within the range provided.
description: |
When called without arguments, returns a uniform pseudo-random real number
in the range of `0` to `1` (inclusive of `0` but exclusive of `1`).
When called with an integer number `m`, returns a uniform pseudo-random
integer in the range of `1` to `m`, inclusive.
When called with two integer numbers `m` and `n`, returns a uniform
pseudo-random integer in the range of `m` to `n`, inclusive.
Internally, this uses a 32-bit PCG (Permuted Congruential Generator) which
achieves excellent statistical performance and makes its output hard to
predict.
parameters:
- name: m
type: number
default: 0
summary: ''
- name: 'n'
type: number
default: 1
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.randomseed
summary: |
Sets `x` as the seed for the pseudo-random generator.
description: |
Sets `x` as the seed for the pseudo-random generator: equal seeds produce
equal sequences of numbers.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.round
summary: |
Returns the integer with the smallest difference between it and the given
number.
description: |
Returns the integer with the smallest difference between it and the given
number. For example, the value `5.8` returns `6`.
For values like `0.5` that are equidistant to two integers, the value with
the greater difference between it and zero is chosen. In other words, the
function "rounds away from zero" such that `0.5` rounds to `1` and `-0.5`
rounds to `-1`.
parameters:
- name: x
type: number
default:
summary: |
The value to be rounded.
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.sign
summary: |
Returns `-1` if `x` is less than `0`, `0` if `x` equals `0`, or `1` if `x`
is greater than `0`.
description: |
Returns `-1` if `x` is less than `0`, `0` if `x` equals `0`, or `1` if `x`
is greater than `0`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.sin
summary: |
Returns the sine of `x`, assumed to be in radians.
description: |
Returns the sine of `x`, assumed to be in radians.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.sinh
summary: |
Returns the hyperbolic sine of `x`.
description: |
Returns the hyperbolic sine of `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.sqrt
summary: |
Returns the square root of `x`.
description: |
Returns the square root of `x`. You can also use the expression `x`^`0.5`
to compute this value.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.tan
summary: |
Returns the tangent of `x`, assumed to be in radians.
description: |
Returns the tangent of `x`, assumed to be in radians.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: math.tanh
summary: |
Returns the hyperbolic tangent of `x`.
description: |
Returns the hyperbolic tangent of `x`.
parameters:
- name: x
type: number
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''

334
.cursor/rules/roblox/en-us/reference/engine/libraries/os.yaml Normal file
View file

@ -0,0 +1,334 @@
# 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: os
type: library
summary: |
This library provides functions related to time and date.
description: |
This library currently serves the purpose of providing information about the
system time under the UTC format. It has been heavily sandboxed from the
standard Lua `Library.os` library and does not allow you to perform any
system-altering operations.
tags: []
code_samples: []
properties: []
functions:
- name: os.clock
summary: |
Returns elapsed time in seconds since an arbitrary baseline with
sub-microsecond precision.
description: |
Returns elapsed time in seconds since an arbitrary baseline with
sub-microsecond precision. This function is useful for comparing durations
between two events that occur on the same computer, and is the best option
for benchmarking.
Unlike with functions such as `Library.os.time()` or
`Datatype.DateTime.now()`, adjustments to the system clock (such as by the
user or [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)) do not
cause time to jump forwards or backwards.
```lua
-- Record the initial time:
local startTime = os.clock()
-- Do something you want to measure the performance of:
local a, b = 0, 1
for _ = 1, 5000000 do
a, b = b, a
end
-- Measure amount of time this took:
local deltaTime = os.clock() - startTime
print("Elapsed time: " .. deltaTime)
--> Elapsed time: 0.044425600033719 (actual number may vary)
```
parameters: []
returns:
- type: double
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: os.date
summary: |
Formats the given string with date/time information based on the given
time.
description: |
Formats the given `formatString` with date/time information based on the
given time, or if not provided, the value returned by `Library.os.time()`.
This function should be avoided in new work. Instead, use the
`Datatype.DateTime` API, which supports localized formatting.
The following specifiers (based on the C function strftime) are supported:
<table>
<thead>
<tr>
<th>Specifier</th>
<th>Meaning</th>
<th>Example<sup>&dagger;</sup></th>
</tr>
</thead>
<tbody>
<tr>
<td><code>%a</code></td>
<td>Abbreviated weekday name *</td>
<td>Mon</td>
</tr>
<tr>
<td><code>%A</code></td>
<td>Full weekday name *</td>
<td>Monday</td>
</tr>
<tr>
<td><code>%b</code></td>
<td>Abbreviated month name *</td>
<td>Feb</td>
</tr>
<tr>
<td><code>%B</code></td>
<td>Full month name *</td>
<td>February</td>
</tr>
<tr>
<td><code>%c</code></td>
<td>Date and time *</td>
<td>Mon Feb 12 14:14:35 2024</td>
</tr>
<tr>
<td><code>%d</code></td>
<td>Day of the month</td>
<td>12</td>
</tr>
<tr>
<td><code>%H</code></td>
<td>Hour, using 24-hour clock</td>
<td>14</td>
</tr>
<tr>
<td><code>%I</code></td>
<td>Hour, using 12-hour clock</td>
<td>02</td>
</tr>
<tr>
<td><code>%j</code></td>
<td>Day of year</td>
<td>043</td>
</tr>
<tr>
<td><code>%m</code></td>
<td>Month</td>
<td>02</td>
</tr>
<tr>
<td><code>%M</code></td>
<td>Minute</td>
<td>14</td>
</tr>
<tr>
<td><code>%p</code></td>
<td>Either "AM" or "PM"</td>
<td>PM</td>
</tr>
<tr>
<td><code>%S</code></td>
<td>Second</td>
<td>35</td>
</tr>
<tr>
<td><code>%U</code></td>
<td>Week number (first Sunday as the first day of week one)</td>
<td>06</td>
</tr>
<tr>
<td><code>%w</code></td>
<td>Weekday</td>
<td>1</td>
</tr>
<tr>
<td><code>%W</code></td>
<td>Week number (first Monday as the first day of week one)</td>
<td>07</td>
</tr>
<tr>
<td><code>%x</code></td>
<td>Date *</td>
<td>02/12/24</td>
</tr>
<tr>
<td><code>%X</code></td>
<td>Time *</td>
<td>14:14:35</td>
</tr>
<tr>
<td><code>%y</code></td>
<td>Two-digit year</td>
<td>24</td>
</tr>
<tr>
<td><code>%Y</code></td>
<td>Full year</td>
<td>2024</td>
</tr>
<tr>
<td><code>%z</code></td>
<td>ISO 8601 offset from UTC in timezone (1 minute = 1, 1 hour = 100)</td>
<td>-0800</td>
</tr>
<tr>
<td><code>%Z</code></td>
<td>Timezone name or abbreviation *</td>
<td>PST</td>
</tr>
<tr>
<td><code>%%</code></td>
<td>The % character</td>
<td>%</td>
</tr>
</tbody>
</table>
\* This value can vary depending on the current locale.
&dagger; The example provided is for February 12th, 2024 (Monday) at
2:14:35 PM (14:14:35), run using locale "en-us" in Pacific Standard Time
(PST).
If the provided `formatString` is exactly `"*t"` (local time) or `"!*t"`
(UTC time), this function instead returns a dictionary containing the
following components, which are normally available in the specifiers
above.
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>year</td>
<td>int</td>
<td>An integer that describes the current year of the Current Era (ex. 2017)</td>
</tr>
<tr>
<td>month</td>
<td>int</td>
<td>An integer between 1 and 12 (starting from January) that describes the current month.</td>
</tr>
<tr>
<td>wday</td>
<td>int</td>
<td>An integer between 1 and 7 (starting from Sunday) that describes the current week day.</td>
</tr>
<tr>
<td>yday</td>
<td>int</td>
<td>An integer between 1 and 366 describing how many days we are into the year.<br />There can be 366 days if it is a leap year.</td>
</tr>
<tr>
<td>day</td>
<td>int</td>
<td>An integer between 1 and 31 describing the current day of the month.</td>
</tr>
<tr>
<td>hour</td>
<td>int</td>
<td>An integer between 1 and 24 describing the current hour of the day.</td>
</tr>
<tr>
<td>min</td>
<td>int</td>
<td>An integer between 0 and 59 describing the current minute of the hour.</td>
</tr>
<tr>
<td>sec</td>
<td>int</td>
<td>An integer between 0 and 60 describing the current second of the hour.<br />(60 because the function is described to indicate leap seconds, but in practice it probably doesn't).</td>
</tr>
<tr>
<td>isdst</td>
<td>bool</td>
<td>A boolean describing if daylight savings time is currently active.</td>
</tr>
</tbody>
</table>
parameters:
- name: formatString
type: string
default:
summary: |
Must be either `"*t"` or `"!*t"`.
- name: time
type: int
default:
summary: |
The time value to format.
returns:
- type: Dictionary
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: os.difftime
summary: |
Returns the number of seconds from one time to another.
description: |
Returns the number of seconds from `t1` to `t2`. The difference is
computed assuming that `t1` and `t2` are correctly casted to the
[time_t](http://en.cppreference.com/w/cpp/chrono/c/time_t) format.
parameters:
- name: t2
type: int
default:
summary: ''
- name: t1
type: int
default:
summary: ''
returns:
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: os.time
summary: |
Returns how many seconds have passed since the Unix epoch (1 January 1970,
00:00:00) under current UTC time.
description: |
Returns how many seconds have passed since the Unix epoch (1 January 1970,
00:00:00), under current UTC time. If provided a table formatted similarly
to that returned by `Library.os.date()`, it returns the number of seconds
from the Unix epoch to that time instead.
Note that the returned time uses the device's local clock. Most operating
systems automatically sync their local time against online time servers,
so this should be within a few hundred milliseconds. However, users can
easily disable sync behavior and set the system time to anything they
want; for synchronized time between client and server, use
`Class.Workspace:GetServerTimeNow()` instead.
This function should be avoided in new work. Instead, use the
`Datatype.DateTime` API, which supports localized formatting.
When you need to precisely measure the time elapsed between two points in
time, like when testing performance, use `Library.os.clock()` instead.
parameters:
- name: time
type: table
default: UTC time
summary: |
A dictionary table describing a specific time, similar to that
returned by `Library.os.date()`. If not provided, uses the current UTC
time.
returns:
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''

773
.cursor/rules/roblox/en-us/reference/engine/libraries/string.yaml Normal file
View file

@ -0,0 +1,773 @@
# 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: string
type: library
summary: |
Provides generic functions to manipulate strings.
description: |
The string library provides generic functions to manipulate strings, such as
to extract substrings or match patterns. You can access the string library by
the global `Library.string` library.
See
[String pattern reference](../../../luau/strings.md#string-pattern-reference)
for details on using `Library.string.match()`, `Library.string.gmatch()`, and
`Library.string.gsub()` to find (and replace) substrings.
tags: []
code_samples: []
properties: []
functions:
- name: string.byte
summary: |
Returns the internal numerical codes of the characters
`s[i], s[i+1], ..., s[j]`. The default value for `i` is 1; the default
value for `j` is `i`. These indices are corrected following the same rules
of function string.sub.
description: |
Returns the internal numerical codes of the characters
`s[i], s[i+1], ..., s[j]`. The default value for `i` is 1; the default
value for `j` is `i`. These indices are corrected following the same rules
of function `Library.string.sub()`.
parameters:
- name: s
type: string
default:
summary: ''
- name: i
type: number
default: 1
summary: ''
- name: j
type: number
default: i
summary: ''
returns:
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.char
summary: |
Receives zero or more integers and returns a string with length equal to
the number of arguments, in which each character has the internal
numerical code equal to its corresponding argument.
description: |
Receives zero or more integers and returns a string with length equal to
the number of arguments, in which each character has the internal
numerical code equal to its corresponding argument.
parameters:
- name: ...
type: int
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.find
summary: |
Looks for the first match of pattern in the string `s` and returns the
indices of `s` where the occurrence starts and ends.
description: |
Searches for the first occurrence of a pattern in a string and returns the
start and end indices of the match. If no match is found, it returns
`nil.` You can specify where to start the search using the optional `init`
parameter which defaults to 1 and can be negative. An optional `plain`
parameter turns off pattern matching, so the function performs a plain
substring search; note that if you use `plain`, you must also provide
`init.`
```lua
-- Example 1: Basic usage
local s = "Hello, world!"
local pattern = "world"
local start_index, end_index = string.find(s, pattern)
print(start_index, end_index) -- Output: 8 12
```
```lua
-- Example 2: Using init parameter
local s = "Hello, world! Hello, Roblox!"
local pattern = "Hello"
local start_index, end_index = string.find(s, pattern, 10)
print(start_index, end_index) -- Output: 15 19
```
```lua
-- Example 3: Using plain parameter
local s = "Hello, world! (Hello)"
local pattern = "(Hello)"
local start_index, end_index = string.find(s, pattern, 1, true)
print(start_index, end_index) -- Output: 14 20
```
```lua
-- Example 4: No Pattern found
local s = "Hello, world!"
local pattern = "Roblox"
local start_index, end_index = string.find(s, pattern)
print(start_index, end_index) -- Output: nil
```
parameters:
- name: s
type: string
default:
summary: |
The string to search within.
- name: pattern
type: string
default:
summary: |
The pattern to search for in given string.
- name: init
type: number
default: 1
summary: |
The starting index for the search.
- name: plain
type: bool
default: false
summary: ''
returns:
- type: number
summary: |
The starting index of the match.
- type: number
summary: |
The ending index of the match.
tags: []
code_samples: []
deprecation_message: ''
- name: string.format
summary: |
Returns a formatted version of its variable number of arguments following
the description given in its first argument, which must be a string.
description: |
Returns a formatted version of its variable number of arguments following
the description given in its first argument, which must be a string.
You can convert variables into user-friendly strings of text using the
`Library.string.format()` function. The function requires the following
format:
`%[flags][width].[precision][specifier]`.
#### Specifiers
The most important part of string formatting is the **specifiers**.
<table>
<thead>
<tr>
<th>Specifier</th>
<th>Accepts</th>
<th>Outputs</th>
<th>Example Output</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>c</code></td>
<td>integer</td>
<td></td>
<td>3</td>
</tr>
<tr>
<td><code>d</code> or <code>i</code></td>
<td>integer</td>
<td>Decimal representation.</td>
<td> 321 </td>
</tr>
<tr>
<td><code>e</code> or <code>E</code></td>
<td>float</td>
<td>Scientific notation using <code>e</code> or <code>E</code>.</td>
<td>3.296e2<br>3.296E2</td>
</tr>
<tr>
<td><code>f</code></td>
<td>float</td>
<td></td>
<td>3231.1231</td>
</tr>
<tr>
<td><code>g</code> or <code>G</code></td>
<td>float</td>
<td>The shorter of <code>e</code>/<code>E</code> and <code>f</code>.</td>
<td>3E14<br>3e14</td>
</tr>
<tr>
<td><code>o</code></td>
<td>integer</td>
<td>Octal representation.</td>
<td>610</td>
</tr>
<tr>
<td><code>q</code></td>
<td>string</td>
<td>String in a form suitable to be safely read back by the Luau interpreter. The string is written between double quotes and all double quotes, new lines, embedded zeros, and backslashes are correctly escaped.</td>
<td>"print(\"Hi\")"</td>
</tr>
<tr>
<td><code>s</code></td>
<td>string</td>
<td></td>
<td>Hello world!</td>
</tr>
<tr>
<td><code>u</code></td>
<td>integer</td>
<td>Decimal representation.</td>
<td>3131</td>
</tr>
<tr>
<td><code>x</code> or <code>X</code></td>
<td>integer</td>
<td>Hexadecimal representation.</td>
<td>7fa<br>7FA</td>
</tr>
<tr>
<td><code>*</code></td>
<td>any</td>
<td>Equivalent to <code>s</code> but accepts any variable by converting it to a string using <code>Global.LuaGlobals.tostring()</code>.</td>
<td>table: 0x0123456789abcdef</td>
</tr>
<tr>
<td><code>%</code></td>
<td></td>
<td><code>%</code> followed by another <code>%</code> will return the <code>%</code> sign itself.</td>
<td>%</td>
</tr>
</tbody>
</table>
```
local str = "The magic word is %s"
print(string.format(str, "Roblox"))
-- The magic word is Roblox
local str = "The magic word is %q"
print(string.format(str, "Roblox"))
-- The magic word is "Roblox"
local str = "Skip to \na new line and \nanother new line!"
print(string.format(str, "%q"))
--[[ Output:
Skip to
a new line and
another new line!
]]
```
#### Flags
<table>
<thead>
<tr>
<th>Flag</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>-</code></td>
<td>Left-justify the given field width (see <code>Width</code> below). Right justification is the default.</td>
</tr>
<tr>
<td><code>+</code></td>
<td>Forces a "+" sign to precede a number. Has no effect on negative numbers.</td>
</tr>
<tr>
<td>(space)</td>
<td>One blank space is inserted before a positive number, while negative numbers are unaffected. This is useful for making positive and negative numbers vertically align in a visual stacked list.</td>
</tr>
<tr>
<td><code>#</code></td>
<td>When used with <code>o</code> and <code>x</code>/<code>X</code>, writes a 0 (octal) or 0x/0X (hex) before values other than zero.<br>When used with <code>e</code>/<code>E</code> and <code>f</code>, forces the output to contain a decimal point, even if no digits would follow (by default, no decimal point is written if no digits follow).<br>When used with <code>g</code> or <code>G</code>, the result is the same as with <code>e</code> or <code>E</code> but trailing zeros are not removed.</td>
</tr>
<tr>
<td><code>0</code></td>
<td>Left-pads the number with zeros instead of empty spaces (see <code>Width</code> below).</td>
</tr>
</tbody>
</table>
```lua
local str = "%-10d"
print(string.format(str, 300) .. "]")
-- 300 ]
-- There are 7 spaces between '300' and ']'
local str = "%+i versus %+i"
print(string.format(str, 300, -300)) -- +300 versus -300
local str = "There is a% i%% chance of rain in Seattle today."
print(string.format(str, 100))
-- There is a 100% chance of rain in Seattle today.
```
#### Width
<table>
<thead>
<tr>
<th>Width</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>(number)</td>
<td>Minimum number of characters to return. If the number of characters to be formatted is less than this number, the result is padded with blank spaces.</td>
</tr>
</tbody>
</table>
```lua
local str = "%012i"
print("Score: " .. string.format(str, 15000))
-- Output: Score: 000000015000
-- The output has 12 digits total, left-padded with zeros
```
#### Precision
The default precision is 1. If you give a period without a value, the
default is 0.
<table>
<thead>
<tr>
<th>Precision</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>.</code>(number)</td>
<td>For integer specifiers (<code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>/<code>X</code>), precision specifies the minimum number of digits to be returned. If the value to be formatted is shorter than this number, the result is padded with leading zeros. A precision of 0 means that no character is written for the value 0.<br>For <code>e</code>/<code>E</code> and <code>f</code> specifiers, this is the number of digits to be printed after the decimal point.<br>For <code>g</code>/<code>G</code> specifiers, this is the maximum number of digits (before the <code>e</code>/<code>E</code>, if present).<br>For <code>s</code>, this is the maximum number of characters to be returned.<br>For <code>c</code> and <code>q</code>, this has no effect.</td>
</tr>
</tbody>
</table>
```lua
-- Add decimal with precision of 2 for a currency output
local str = "$%.2f"
print(string.format(str, 300)) -- Output: $300.00
-- Return first 6 letters of a string
local str = "%.6s"
print(string.format(str, "Robloxian")) -- Output: Roblox
local str = "Once upon a time, there was a dragon named %s and it had %.8f horns."
print(string.format(str, "Pi", math.pi))
-- Output: Once upon a time, there was a dragon named Pi and it had 3.14159265 horns.
```
parameters:
- name: formatstring
type: string
default:
summary: ''
- name: ...
type: string
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.gmatch
summary: |
Returns an iterator function that returns the next captures from pattern
over the string `s` each time it's called.
description: |
Returns an iterator function that returns the next captures from pattern
over the string `s` each time it's called.
parameters:
- name: s
type: string
default:
summary: ''
- name: pattern
type: string
default:
summary: ''
returns:
- type: function
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.gsub
summary: |
Returns a copy of `s` in which all or the first `n` occurrences of the
pattern are replaced with the given replacement. The second value returned
is the total number of substitutions made.
description: |
Short for global substitution. Returns a copy of `s` in which all (or the
first n, if given) occurrences of the pattern are substituted (replaced)
with the given `replacement`. The second value returned is the total
number of substitutions made.
The `replacement` can be one of several types, each used differently to
determine the actual string:
- string: The pattern is replaced with the string directly
- table: The string that matched the pattern is looked up in the table as
a key, and the value (string) is what replaces it, if it exists.
- function: Called with the string that matched the pattern, should return
the string to replace the matched pattern.
An optional final argument can be provided which specifies the maximum
number of substitutions to make (for example, stop after 2 replacements)
#### Various Examples
```lua
-- Basic replacement
string.gsub("I love tacos!", "tacos", "Roblox") --> I love Roblox! 1
-- Replacement with a pattern
string.gsub("I like red!", "%w+", "word") --> word word word! 3
-- Replacement table
string.gsub("I play Roblox.", "%w+", {I="Je", play="joue à"}) --> Je joue à Roblox. 3
-- Replacement function
string.gsub("I have 2 cats.", "%d+", function(n) return tonumber(n) * 12 end) --> I have 24 cats. 1
-- Replace only twice
string.gsub("aaa", "a", "b", 2) --> bba 2
-- Replacement with capture groups (maximum of nine)
string.gsub("love2play Roblox", "(%w+)(%d+)(%w+)%s+(%w+)", "I %1 %2 %3 %4!") --> I love 2 play Roblox! 1
```
parameters:
- name: s
type: string
default:
summary: |
The string whose occurrences of the given pattern shall be replaced.
- name: pattern
type: string
default:
summary: |
The pattern to be matched and replaced.
- name: replacement
type: Variant
default:
summary: |
Determines what should replace the occurrence(s) of the given pattern.
- name: replacements
type: number
default:
summary: |
The maximum number of substitutions to make.
returns:
- type: string
summary: ''
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.len
summary: |
Returns the length of a string.
description: |
Returns the length of a string.
parameters:
- name: s
type: string
default:
summary: ''
returns:
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.lower
summary: |
Returns a copy of a string with all uppercase letters changed to
lowercase.
description: |
Returns a copy of a string with all uppercase letters changed to
lowercase.
parameters:
- name: s
type: string
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.match
summary: |
Looks for the first match of pattern in the string `s`. If a match is
found, it is returned; otherwise, it returns `nil`. A third, optional
numerical argument, init, specifies where to start the search.
description: |
Looks for the first match of pattern in the string `s`. If a match is
found, it is returned; otherwise, it returns `nil`. A third, optional
numerical argument, init, specifies where to start the search; its default
value is 1 and can be negative.
parameters:
- name: s
type: string
default:
summary: ''
- name: pattern
type: string
default:
summary: ''
- name: init
type: number
default: 1
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.pack
summary: |
Returns a binary string containing the provided arguments.
description: |
Returns a binary string containing the provided arguments. The first
argument, `format`, determines the way the remaining arguments are packed;
see [here](https://www.lua.org/manual/5.3/manual.html#6.4.2) for options.
parameters:
- name: format
type: string
default:
summary: ''
- name: ...
type: Variant
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.packsize
summary: |
Returns the size in bytes of any string packed with a given description.
description: |
Returns the size in bytes of any string packed with a given description.
The sole argument, `format`, determines the way the remaining arguments
are packed, but you cannot use `s` and `z` because they have variable
lengths. See [here](https://www.lua.org/manual/5.3/manual.html#6.4.2) for
options.
parameters:
- name: format
type: string
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.rep
summary: |
Returns a string that is the concatenation of `n` copies of the string
`s`.
description: |
Returns a string that is the concatenation of `n` copies of the string
`s`.
parameters:
- name: s
type: string
default:
summary: ''
- name: 'n'
type: int
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.reverse
summary: |
Returns a string that is the string `s` reversed.
description: |
Returns a string that is the string `s` reversed.
parameters:
- name: s
type: string
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.split
summary: |
Splits a string into parts based on the defined separator character(s),
returning a table of ordered results.
description: |
Splits a string into parts based on the defined separator character(s),
returning a table of ordered results.
If an empty "slice" is located, that part will be returned as an empty
string. For instance `string.split("abc||def", "|")` will return a table
with three strings: `"abc"`, `""`, and `"def"`.
```lua
local values = input:split(",")
print(values[1], values[2], values[3])
```
Also note that whitespace from the original string will be preserved, for
example `string.split("abc _ def", "_")` will honor the whitespace on both
sides of the `_` separator. By default, the separator character is `,` but
you can specify an alternative character or series of characters.
**Corner Cases**
#### Empty String
```lua
"" --> ""
```
#### Empty Slices
```lua
"foo,,bar" --> "foo", "", "bar"
",foo" --> "", "foo"
"foo," --> "foo", ""
"," --> "", ""
",," --> "", "", ""
```
#### Whitespace Preserved
```lua
" whitespace " --> " whitespace "
"foo , bar" --> "foo ", " bar"
```
#### Invalid UTF-8
```lua
"\xFF" --> "\xFF"
"\xFD,\xFE" --> "\xFD", "\xFE"
```
#### Unicode
```lua
"，" --> U+FF0C FULLWIDTH COMMA
"我很高兴，你呢？" --> "我很高兴", "你呢？"
"•" --> U+2022 BULLET
"hello•world" --> "hello", "world"
```
parameters:
- name: s
type: string
default:
summary: |
The string to split.
- name: separator
type: string
default: ','
summary: |
The separator character(s) to be used for splitting the string.
returns:
- type: table
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.sub
summary: |
Returns the substring of `s` that starts at `i` and continues until and
including `j`. `i` and `j` can be negative. `i` defaults to 1 and `j`
defaults to `-1`.
description: |
Returns the substring of `s` that starts at `i` and continues until and
including `j`. `i` and `j` can be negative. `i` defaults to 1 and `j`
defaults to `-1`.
parameters:
- name: s
type: string
default:
summary: ''
- name: i
type: int
default: 1
summary: ''
- name: j
type: int
default: -1
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: string.unpack
summary: |
Extracts the values packed in the provided binary string.
description: |
Extracts the values packed in the provided binary string based on the
first argument, `format`, which should match the one originally used to
`Library.string.pack|pack()` the string; see
[here](https://www.lua.org/manual/5.3/manual.html#6.4.2) for options. The
optional third parameter determines the byte at which the reading starts.
parameters:
- name: format
type: string
default:
summary: ''
- name: data
type: string
default:
summary: ''
- name: readStart
type: string
default: 1
summary: ''
returns:
- type: Tuple
summary: |
The values packed into the provided binary string, plus the index of
the first unread byte.
tags: []
code_samples: []
deprecation_message: ''
- name: string.upper
summary: |
Returns a copy of a string with all lowercase letters changed to
uppercase.
description: |
Returns a copy of a string with all lowercase letters changed to
uppercase.
parameters:
- name: s
type: string
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''

530
.cursor/rules/roblox/en-us/reference/engine/libraries/table.yaml Normal file
View file

@ -0,0 +1,530 @@
# 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: table
type: library
summary: |
A library of table functions.
description: |
This library provides generic functions for table/array manipulation,
providing all its functions inside the global `Library.table` variable. Most
functions in the `Library.table` library assume that the table represents an
array or a list. For these functions, the "length" of a table means the result
of the length operator.
tags: []
code_samples: []
properties: []
functions:
- name: table.clear
summary: |
Sets all keys in the given table to `nil`.
description: |
Sets the value for all keys within the given table to `nil`. This causes
the `#` operator to return `0` for the given table. The allocated capacity
of the table's array portion is maintained, which allows for efficient
re-use of the space.
```lua
local grades = {95, 82, 71, 92, 100, 60}
print(grades[4], #grades) --> 92, 6
table.clear(grades)
print(grades[4], #grades) --> nil, 0
-- If grades is filled again with the same number of entries,
-- no potentially expensive array resizing will occur
-- because the capacity was maintained by table.clear.
```
This function does not delete/destroy the table provided to it. This
function is meant to be used specifically for tables that are to be
re-used.
parameters:
- name: table
type: table
default:
summary: |
The table whose keys will be cleared.
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.clone
summary: |
Returns a shallow copy of the provided table.
description: |
Returns an unfrozen shallow copy of the provided table.
```lua
local original = {
key = "value",
engine = "Roblox",
playerID = 505306092
}
local clone = table.clone(original)
```
parameters:
- name: t
type: table
default:
summary: |
The table to be cloned.
returns:
- type: table
summary: |
The clone of the provided table.
tags: []
code_samples: []
deprecation_message: ''
- name: table.concat
summary: |
Returns the given range of table elements as a string where each element
is separated by the given separator.
description: |
Given an array where all elements are strings or numbers, returns the
string `t[i] ... sep ... t[i+1] ... sep ... t[j]`. The default value for
sep is an empty string, the default for `i` is 1, and the default for `j`
is #t. If i is greater than `j`, returns the empty string.
parameters:
- name: t
type: Array
default:
summary: |
The table that will be converted into a string.
- name: sep
type: string
default: ''
summary: |
The string that will be concatenated between each entry in the table.
- name: i
type: int
default: 1
summary: |
The starting index of the table concatenation.
- name: j
type: int
default:
summary: |
The ending index of the table concatenation.
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.create
summary: |
Returns a new table populated with many instances of the specified value.
description: |
Creates a table with the array portion allocated to the given `number` of
elements, optionally filled with the given `value`.
```lua
local t = table.create(3, "Roblox")
print(table.concat(t)) --> RobloxRobloxRoblox
```
If you are inserting into large array-like tables and are certain of a
reasonable upper limit to the number of elements, it's recommended to use
this function to initialize the table. This ensures the table's array
portion of its memory is sufficiently sized, as resizing it can be
expensive. For small quantities this is typically not noticeable.
parameters:
- name: count
type: number
default:
summary: ''
- name: value
type: Variant
default:
summary: ''
returns:
- type: table
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.find
summary: |
Returns the index of the first occurrence of `needle` within `haystack`
starting from `init`.
description: |
Within the given array-like table `haystack`, find the first occurrence of
value `needle`, starting from index `init` or the beginning if not
provided. If the value is not found, `nil` is returned.
A [linear search](https://en.wikipedia.org/wiki/Linear_search) algorithm
is performed.
```lua
local t = {"a", "b", "c", "d", "e"}
print(table.find(t, "d")) --> 4
print(table.find(t, "z")) --> nil, because z is not in the table
print(table.find(t, "b", 3)) --> nil, because b appears before index 3
```
parameters:
- name: haystack
type: table
default:
summary: ''
- name: needle
type: Variant
default:
summary: ''
- name: init
type: number
default:
summary: ''
returns:
- type: Variant
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.foreach
summary: |
Iterates over the provided table, passing the key and value of each
iteration over to the provided function.
description: |
Iterates over the provided table, passing the key and value of each
iteration over to the provided function. This function has been deprecated
and is not recommended for use in new code; use a `for` loop instead.
parameters:
- name: t
type: table
default:
summary: |
The table to be iterated over.
- name: f
type: function
default:
summary: |
The function that will be used for the iteration. This function will
receive 2 arguments for each iteration, where the 1st argument is the
key, and the 2nd argument is the value.
returns:
- type: ()
summary: ''
tags:
- Deprecated
code_samples: []
deprecation_message: ''
- name: table.foreachi
summary: |
Similar to `Library.table.foreach()` except index-value pairs are passed
instead of key-value pairs.
description: |
This is similar to `Library.table.foreach()` except that index-value pairs
are passed, not key-value pairs. This function has been deprecated and is
not recommended for use in new code; use a `for` loop instead.
parameters:
- name: t
type: Array
default:
summary: |
The table to be iterated over.
- name: f
type: function
default:
summary: |
The function that will be used for the iteration. This function will
receive 2 arguments for each iteration, where the 1st argument is the
index, and the 2nd argument is the value.
returns:
- type: ()
summary: ''
tags:
- Deprecated
code_samples: []
deprecation_message: ''
- name: table.freeze
summary: |
Makes the given table read-only.
description: |
This function makes the given table read-only, effectively "freezing" it
in its current state. Attempting to modify a frozen table throws an error.
This freezing effect is shallow, which means that you can write to a table
within a frozen table. To deep freeze a table, call this function
recursively on all of the descending tables.
parameters:
- name: t
type: table
default:
summary: |
The table to be frozen.
returns:
- type: table
summary: |
The frozen table.
tags: []
code_samples: []
deprecation_message: ''
- name: table.getn
summary: |
Returns the number of elements in the table passed.
description: |
Returns the number of elements in the table passed. This function has been
deprecated and is not recommended for use in new code; use `#t` instead.
parameters:
- name: t
type: Array
default:
summary: |
The table whose size is being measured.
returns:
- type: number
summary: ''
tags:
- Deprecated
code_samples: []
deprecation_message: ''
- name: table.insert
summary: |
Inserts the provided value to the target position of the array.
description: |
Inserts the provided value to the target position of the array.
parameters:
- name: t
type: Array
default:
summary: |
The table that is being appended to.
- name: pos
type: number
default:
summary: |
The position at which the value will be inserted.
- name: value
type: Variant
default:
summary: |
The value that will be appended to the table.
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.insert
summary: |
Appends the provided value to the end of the array.
description: |
Appends the provided value to the end of the array.
parameters:
- name: t
type: Array
default:
summary: |
The table that is being appended to.
- name: value
type: Variant
default:
summary: |
The value that will be appended to the table.
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.isfrozen
summary: |
Returns `true` if the given table is frozen and `false` if it isn't
frozen.
description: |
This function returns `true` if the given table is frozen and `false` if
it isn't frozen. You can freeze tables using `Library.table.freeze()`.
parameters:
- name: t
type: table
default:
summary: |
The table to check.
returns:
- type: bool
summary: |
Whether the table is frozen from `Library.table.freeze()`.
tags: []
code_samples: []
deprecation_message: ''
- name: table.maxn
summary: |
Returns the maximum numeric key of the provided table, or zero if the
table has no numeric keys.
description: |
Returns the maximum numeric key of the provided table, or zero if the
table has no numeric keys. Gaps in the table are ignored.
parameters:
- name: t
type: table
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.move
summary: |
Copies the specified range of elements from one table to another.
description: |
Copies elements in table `src` from `src[a]` up to `src[b]` into table
`dst` starting at index `t`. Equivalent to the assignment statement
`dst[t], ..., dst[t + (b - a)] = src[a], ..., src[b]`.
The default for `dst` is `src`. The destination range may overlap with the
source range.
Returns `dst` for convenience.
parameters:
- name: src
type: table
default:
summary: |
Source table.
- name: a
type: number
default:
summary: |
Start copying at `src[a]`.
- name: b
type: number
default:
summary: |
Copy up to and including `src[b]`.
- name: t
type: number
default:
summary: |
Copy into `dst[t], ...`.
- name: dst
type: table
default: src
summary: |
Destination table.
returns:
- type: table
summary: |
`dst`, for convenience.
tags: []
code_samples: []
deprecation_message: ''
- name: table.pack
summary: |
Returns a new table containing the provided values.
description: |
Returns a new table with all arguments stored into keys 1, 2, etc. and
with a field "n" with the total number of arguments. Note that the
resulting table may not be a sequence.
```lua
local t = table.pack(1, 2, 3)
print(table.concat(t, ", ")) --> 1, 2, 3
```
parameters:
- name: values...
type: Variant
default:
summary: ''
returns:
- type: Variant
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.remove
summary: |
Removes the specified element from the array, shifting later elements down
to fill in the empty space if possible.
description: |
Removes from array t the element at position pos, returning the value of
the removed element. When pos is an integer between `1` and `#t`, it
shifts down the elements `t[pos+1], t[pos+2], ..., t[#t]` and erases
element `t[#t]`. If the pos parameter is not provided, pos defaults to the
length of the table removing the last element.
parameters:
- name: t
type: Array
default:
summary: |
The table that is having an element removed.
- name: pos
type: number
default:
summary: |
The index of the element being removed.
returns:
- type: Variant
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.sort
summary: |
Sorts table elements using the provided comparison function or the `<`
operator.
description: |
Sorts elements of array t in a given order, from `t[1]` to `t[#t]`. If
`comp` is given, then it must be a function that receives two elements and
returns true when the first element must come before the second in the
final order.
The error `invalid order function for sorting` is thrown if both
`comp(a, b)` and `comp(b, a)` return `true`.
If `comp` is not given, then the standard Luau operator `<` is used
instead.
parameters:
- name: t
type: Array
default:
summary: ''
- name: comp
type: function
default: nil
summary: |
An optional comparison function to be used when comparing elements in
the table. This function receives two elements, and should return true
if the first element should be sorted before the second in the final
order.
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: table.unpack
summary: |
Returns all elements from the given list as a tuple.
description: |
Returns the elements from the given list. By default, `i` is 1 and `j` is
the length of `list`.
Note that this same functionality is also provided by the global
`Global.LuaGlobals.unpack()` function.
parameters:
- name: list
type: table
default:
summary: |
The list of elements to be unpacked.
- name: i
type: number
default: 1
summary: |
The index of the first element to unpack.
- name: j
type: number
default: '#list'
summary: |
The index of the last element to unpack.
returns:
- type: Tuple
summary: ''
tags: []
code_samples: []
deprecation_message: ''

266
.cursor/rules/roblox/en-us/reference/engine/libraries/task.yaml Normal file
View file

@ -0,0 +1,266 @@
# 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: task
type: library
summary: |
Allows for functions and threads to be coordinated with the engine's
scheduler.
description: |
The **task** library allows for functions and threads to be scheduled with the
engine's scheduler.
The functions available in this library generally support functions and
threads. In most cases using a function is sufficient, but for more advanced
cases it's recommended you familiarize yourself with the `Library.coroutine`
library.
tags: []
code_samples: []
properties: []
functions:
- name: task.spawn
summary: |
Calls/resumes a function/coroutine immediately through the engine's
scheduler.
description: |
Accepts a function or a thread (as returned by
`Library.coroutine.create()`) and calls/resumes it immediately through the
engine's scheduler. Arguments after the first are sent to the
function/thread.
If the calling script is currently running in a serial execution phase,
then the spawned function or thread is resumed in the current serial
execution phase. If the calling script is currently running in a parallel
execution phase, then the spawned function or thread is resumed in the
current parallel execution phase. For more information, see
[Parallel Luau](../../../scripting/multithreading.md).
parameters:
- name: functionOrThread
type: function | thread
default:
summary: |
A function or a thread returned by `Library.coroutine.create()`.
- name: ...
type: Variant
default:
summary: |
Arguments to send to the function or thread.
returns:
- type: thread
summary: |
The scheduled thread.
tags: []
code_samples: []
deprecation_message: ''
- name: task.defer
summary: |
Calls/resumes a function/coroutine at the end of the current resumption
cycle.
description: |
Accepts a function or a thread (as returned by
`Library.coroutine.create()`) and defers it until the end of the current
resume point within the current frame.
This function should be used when a similar behavior to
`Library.task.spawn()` is desirable, but the thread does not need to run
immediately.
If the calling script is currently running in a serial execution phase,
then the deferred function or thread is resumed in a serial execution
phase. If the calling script is currently running in a parallel execution
phase, then the deferred function or thread is resumed in a parallel
execution phase. For more information, see
[Parallel Luau](../../../scripting/multithreading.md).
parameters:
- name: functionOrThread
type: function | thread
default:
summary: |
A function or a thread returned by coroutine.create.
- name: ...
type: Variant
default:
summary: |
Arguments to send to the function or thread.
returns:
- type: thread
summary: |
The scheduled thread.
tags: []
code_samples: []
deprecation_message: ''
- name: task.delay
summary: |
Schedules a function/coroutine to be called/resumed on the next Heartbeat
after the given duration (in seconds) has passed, without throttling.
description: |
Accepts a function or a thread (as returned by
`Library.coroutine.create()`) and schedules it to be called/resumed on the
next `Class.RunService.Heartbeat|Heartbeat` after the given amount of time
in seconds has elapsed. Arguments after the second are sent to the
function/thread.
This function differs from the deprecated global `delay()` function in
that **no throttling occurs**: on the very same
`Class.RunService.Heartbeat|Heartbeat` step in which enough time has
passed, the function is guaranteed to be called/resumed. Providing a
duration of zero (`0`) will guarantee that the function is called on the
very next `Class.RunService.Heartbeat|Heartbeat`.
You can calculate the actual time passed by calling `Library.os.clock()`
upon scheduling and in the scheduled function.
If the calling script is currently running in a serial execution phase,
then the delayed function or thread is resumed in a serial execution
phase. If the calling script is currently running in a parallel execution
phase, then the delayed function or thread is resumed in a parallel
execution phase. For more information, see
[Parallel Luau](../../../scripting/multithreading.md).
parameters:
- name: duration
type: number
default:
summary: |
The minimum number of seconds that must pass before the
function/thread is called/resumed.
- name: functionOrThread
type: function | thread
default:
summary: ''
- name: ...
type: Variant
default:
summary: |
Arguments to be passed to the function/thread when it is due to be
called/resumed.
returns:
- type: thread
summary: |
The scheduled thread.
tags: []
code_samples: []
deprecation_message: ''
- name: task.desynchronize
summary: |
Causes the following code to be run in parallel.
description: |
If the calling script is currently running in a serial execution phase,
`desynchronize()` suspends the script and the script will be resumed in
the next parallel execution phase. If the calling script is currently
running in a parallel execution phase, `desynchronize()` returns
immediately and has no effect.
Only scripts which are descendants of an `Class.Actor` may call this
method. If a script outside of an `Class.Actor` calls this method, an
error will be raised. `Class.ModuleScript|ModuleScripts` may also call
`desynchronize()` as long as the instantiation of the module calling it
was required by a script that is a descendant of an `Class.Actor`.
For more information, see
[Parallel Luau](../../../scripting/multithreading.md).
parameters: []
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: task.synchronize
summary: |
Causes the following code to be run in serial.
description: |
If the calling script is currently running in a parallel execution phase,
`synchronize()` suspends the script and the script will be resumed in the
next serial execution phase. If the calling script is currently running in
a serial execution phase, `synchronize()` returns immediately and has no
effect.
Only scripts which are descendants of an `Class.Actor` may call this
method. If a script outside of an `Class.Actor` calls this method, an
error will be raised. `Class.ModuleScript|ModuleScripts` may also call
`synchronize()` as long as the instantiation of the module calling it was
required by a script that is a descendant of an `Class.Actor`.
For more information, see
[Parallel Luau](../../../scripting/multithreading.md).
parameters: []
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: task.wait
summary: |
Yields the current thread without throttling.
description: |
Yields the current thread until the given duration (in seconds) has
elapsed, then resumes the thread on the next
`Class.RunService.Heartbeat|Heartbeat` step. The actual amount of time
elapsed is returned.
If no duration is given, it will default to zero (`0`). This means the
thread resumes on the very next step, which is equivalent in behavior to
`Class.RunService.Heartbeat:Wait()`
Unlike the deprecated global `wait()`, this function **does not throttle**
and guarantees the resumption of the thread on the first Heartbeat that
occurs when it is due. This function also only returns the elapsed time
and nothing else.
If the calling script is currently running in a serial execution phase,
then the script is resumed in a serial execution phase. If the calling
script is currently running in a parallel execution phase, then the script
is resumed in a parallel execution phase. For more information, see
[Parallel Luau](../../../scripting/multithreading.md).
parameters:
- name: duration
type: number
default: 0
summary: |
The amount of time in seconds that should elapse before the current
thread is resumed.
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: task.cancel
summary: |
Cancels a thread, preventing it from being resumed.
description: |
Cancels a thread and closes it, preventing it from being resumed manually
or by the engine's scheduler.
This function can be used with other members of the **task** library that
return a thread to cancel them before they are resumed. For example:
```lua
local thread = task.delay(5, function()
print("Hello world!")
end)
task.cancel(thread)
```
Note that threads may be in a state where it is impossible to cancel them.
For example, the currently executing thread and threads that have resumed
another coroutine may not be cancelled. If this is the case, an error will
be generated. However, code should not rely on specific thread states or
conditions causing `Library.task.cancel()` to fail. It is possible that
future updates will eliminate these constraints and allow threads in these
states to be successfully cancelled.
parameters:
- name: thread
type: thread
default:
summary: |
The thread that will be cancelled.
returns:
- type: ()
summary: ''
tags: []
code_samples: []
deprecation_message: ''

247
.cursor/rules/roblox/en-us/reference/engine/libraries/utf8.yaml Normal file
View file

@ -0,0 +1,247 @@
# 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: utf8
type: library
summary: |
This library provides basic support for `UTF-8` encoding.
description: |
This library provides basic support for `UTF-8` encoding. This library does
not provide any support for Unicode other than the handling of the encoding.
Any operation that needs the meaning of a character, such as character
classification, is outside its scope.
Unless stated otherwise, all functions that expect a byte position as a
parameter assume that the given position is either the start of a byte
sequence or one plus the length of the subject string. As in the string
library, negative indices count from the end of the string.
You can find a large catalog of usable `UTF-8` characters
[here](https://www.w3schools.com/charsets/ref_html_utf8.asp).
tags: []
code_samples: []
properties:
- name: utf8.charpattern
type: string
summary: |
The pattern `"[%z\x01-\x7F\xC2-\xF4][\x80-\xBF]*"`, which matches exactly
zero or more UTF-8 byte sequences, assuming that the subject is a valid
UTF-8 string.
description: |
The pattern `"[%z\x01-\x7F\xC2-\xF4][\x80-\xBF]*"`, which matches exactly
zero or more UTF-8 byte sequence, assuming that the subject is a valid
UTF-8 string.
tags: []
code_samples: []
deprecation_message: ''
functions:
- name: utf8.char
summary: |
Converts zero or more codepoints to UTF-8 byte sequences.
description: |
Receives zero or more codepoints as integers, converts each one to its
corresponding UTF-8 byte sequence and returns a string with the
concatenation of all these sequences.
parameters:
- name: codepoints
type: Tuple<int>
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: utf8.codes
summary: |
Returns an iterator function that iterates over all codepoints in a given
string.
description: |
Returns an iterator function so that the construction:
```lua
for position, codepoint in utf8.codes(str) do
-- body
end
```
will iterate over all codepoints in string `str`. It raises an error if it
meets any invalid byte sequence.
parameters:
- name: str
type: string
default:
summary: |
The string to iterate over.
returns:
- type: function
summary: ''
- type: string
summary: ''
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: utf8.codepoint
summary: |
Returns the codepoints (as integers) from all codepoints in a given
string.
description: |
Returns the codepoints (as integers) from all codepoints in the provided
string (str) that start between byte positions `i` and `j` (both
included). The default for `i` is `1` and for `j` is `i`. It raises an
error if it meets any invalid byte sequence.
parameters:
- name: str
type: string
default:
summary: ''
- name: i
type: int
default: 1
summary: |
The index of the codepoint that should be fetched from this string.
- name: j
type: int
default: i
summary: |
The index of the last codepoint between `i` and `j` that will be
returned. If excluded, this will default to the value of `i`.
returns:
- type: Tuple<int>
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: utf8.len
summary: |
Returns the number of UTF-8 codepoints in a given string.
description: |
Returns the number of UTF-8 codepoints in the string _str_ that start
between positions `i` and `j` (both inclusive). The default for `i` is `1`
and for `j` is `-1`. If it finds any invalid byte sequence, returns a nil
value plus the position of the first invalid byte.
parameters:
- name: s
type: string
default:
summary: ''
- name: i
type: int
default: 1
summary: |
The starting position.
- name: j
type: int
default: -1
summary: |
The ending position.
returns:
- type: int
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: utf8.offset
summary: |
Returns the position (in bytes) where the encoding of the `n`‑th codepoint
of `s` (counting from byte position `i`) starts.
description: |
Returns the position (in bytes) where the encoding of the `n`‑th codepoint
of `s` (counting from byte position `i`) starts. A negative `n` gets
characters before position `i`. The default for `i` is `1` when `n` is
non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the
offset of the `n`‑th character from the end of the string. If the
specified character is neither in the subject nor right after its end, the
function returns `nil`.
parameters:
- name: s
type: string
default:
summary: ''
- name: 'n'
type: int
default:
summary: ''
- name: i
type: int
default: 1
summary: ''
returns:
- type: int?
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: utf8.graphemes
summary: |
Returns an iterator function that iterates over the grapheme clusters of a
given string.
description: |
Returns an iterator function so that
```lua
for first, last in utf8.graphemes(str) do
local grapheme = s:sub(first, last)
-- body
end
```
will iterate the grapheme clusters of the string.
parameters:
- name: str
type: string
default:
summary: ''
- name: i
type: number
default:
summary: ''
- name: j
type: number
default:
summary: ''
returns:
- type: function
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: utf8.nfcnormalize
summary: |
Converts the input string to Normal Form C.
description: |
Converts the input string to Normal Form C, which tries to convert
decomposed characters into composed characters.
parameters:
- name: str
type: string
default:
summary: ''
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: utf8.nfdnormalize
summary: |
Converts the input string to Normal Form D.
description: |
Converts the input string to Normal Form D, which tries to break up
composed characters into decomposed characters.
parameters:
- name: str
type: string
default:
summary: |
The string to convert.
returns:
- type: string
summary: ''
tags: []
code_samples: []
deprecation_message: ''

310
.cursor/rules/roblox/en-us/reference/engine/libraries/vector.yaml Normal file
View file

@ -0,0 +1,310 @@
# 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: vector
type: library
summary: |
A library of vector functions.
description: |
This library implements functionality for the vector type in addition to the
built-in primitive operator support. It uses vectors with three components
(`x`, `y`, and `z`).
Individual vector components can be accessed using the fields `x` or `X`, `y`
or `Y`, `z` or `Z`. Since vector values are immutable, writing to individual
components is not supported.
tags: []
code_samples: []
properties:
- name: vector.zero
type: vector
summary: |
Constant vector with all components set to `0`.
description: |
Constant vector with all components set to `0`.
tags: []
code_samples: []
deprecation_message: ''
- name: vector.one
type: vector
summary: |
Constant vector with all components set to `1`.
description: |
Constant vector with all components set to `1`.
tags: []
code_samples: []
deprecation_message: ''
functions:
- name: vector.create
summary: |
Creates a new vector with the given component values.
description: |
Creates a new vector with the given component values.
parameters:
- name: x
type: number
default:
summary: ''
- name: 'y'
type: number
default:
summary: ''
- name: z
type: number
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.magnitude
summary: |
Calculates the magnitude of a given vector.
description: |
Calculates the magnitude of a given vector.
parameters:
- name: vec
type: vector
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.normalize
summary: |
Computes the normalized version (unit vector) of a given vector.
description: |
Computes the normalized version (unit vector) of a given vector.
parameters:
- name: vec
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.cross
summary: |
Computes the cross product of two vectors.
description: |
Computes the cross product of two vectors.
parameters:
- name: vec1
type: vector
default:
summary: ''
- name: vec2
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.dot
summary: |
Computes the dot product of two vectors.
description: |
Computes the dot product of two vectors.
parameters:
- name: vec1
type: vector
default:
summary: ''
- name: vec2
type: vector
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.angle
summary: |
Computes the angle between two vectors in radians.
description: |
Computes the angle between two vectors in radians. The axis, if specified,
is used to determine the sign of the angle.
parameters:
- name: vec1
type: vector
default:
summary: ''
- name: vec2
type: vector
default:
summary: ''
- name: axis
type: vector?
default:
summary: ''
returns:
- type: number
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.floor
summary: |
Applies `Library.math.floor()` to every component of the input vector.
description: |
Applies `Library.math.floor()` to every component of the input vector.
parameters:
- name: vec
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.ceil
summary: |
Applies `Library.math.ceil()` to every component of the input vector.
description: |
Applies `Library.math.ceil()` to every component of the input vector.
parameters:
- name: vec
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.abs
summary: |
Applies `Library.math.abs()` to every component of the input vector.
description: |
Applies `Library.math.abs()` to every component of the input vector.
parameters:
- name: vec
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.sign
summary: |
Applies `Library.math.sign()` to every component of the input vector.
description: |
Applies `Library.math.sign()` to every component of the input vector.
parameters:
- name: vec
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.clamp
summary: |
Applies `Library.math.clamp()` to every component of the input vector.
description: |
Applies `Library.math.clamp()` to every component of the input vector.
parameters:
- name: vec
type: vector
default:
summary: ''
- name: min
type: vector
default:
summary: ''
- name: max
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.lerp
summary: |
Returns a vector linearly interpolated between two vectors by a fractional
alpha.
description: |
Returns a vector linearly interpolated between two vectors (`vec1`,
`vec2`) by the fraction `alpha`. Note that `alpha` is **not** limited to
the range `[0, 1]`.
parameters:
- name: vec1
type: vector
default:
summary: ''
- name: vec2
type: vector
default:
summary: ''
- name: alpha
type: number
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.max
summary: |
Applies `Library.math.max()` to the corresponding components of the input
vectors.
description: |
Applies `Library.math.max()` to the corresponding components of the input
vectors.
parameters:
- name: ...
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''
- name: vector.min
summary: |
Applies `Library.math.min()` to the corresponding components of the input
vectors.
description: |
Applies `Library.math.min()` to the corresponding components of the input
vectors.
parameters:
- name: ...
type: vector
default:
summary: ''
returns:
- type: vector
summary: ''
tags: []
code_samples: []
deprecation_message: ''