> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rollingquest.kramgames.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LuaArray — Native Array Type Reference

> API reference for the LuaArray type in RollingQuest Lua scripting. A fixed-length, optionally read-only array with 1-based indexing and iterator support.

The `LuaArray` type is a fixed-length array provided by the RollingQuest engine as an alternative to standard Lua tables. It supports 1-based indexing, optional read-only mode, and an iterator interface. Use `LuaArray` when you need a collection with a known length that can be made immutable.

<Note>
  Standard Lua tables (`{}`) work fine for most cases. Use `LuaArray` when you specifically need read-only protection or when an API returns a `LuaArray`.
</Note>

## Constructors

```lua theme={null}
-- Empty array of a given length
local arr = Array.new(10)

-- Empty read-only array
local arr = Array.new(5, true)

-- From varargs
local arr = Array.new(1, 2, 3, 4, 5)

-- From a Lua table
local arr = Array.new({10, 20, 30})

-- Read-only from varargs
local arr = Array.newReadonly(1, 2, 3)

-- Copy an existing array or table
local arr = Array.copyOf(someTable)

-- Copy as read-only
local arr = Array.copyOf(someTable, true)
```

## Properties

| Property   | Type      | Read-only | Description                       |
| ---------- | --------- | --------- | --------------------------------- |
| `length`   | `integer` | ✅         | Number of elements in the array.  |
| `readonly` | `boolean` | ✅         | `true` if the array is read-only. |

## Element Access

Arrays use 1-based indexing (like standard Lua):

```lua theme={null}
local value = arr[1]     -- first element
arr[1] = "new value"     -- set first element (fails if readonly)
```

## Methods

### toReadonly

Returns a read-only version of the array.

```lua theme={null}
--- @return LuaArray
function LuaArray:toReadonly()
```

### iterator

Returns an iterator for use with `for..in` loops.

```lua theme={null}
--- @return function
function LuaArray:iterator()
```

## Usage Example

```lua theme={null}
-- Create an array from a table
local scores = Array.new({100, 200, 300, 400, 500})

-- Read values
Logger.info("First score: " .. scores[1])
Logger.info("Total scores: " .. scores.length)

-- Make it read-only
local frozen = scores:toReadonly()

-- Iterate
for i, score in scores:iterator() do
    Logger.info("Score " .. i .. ": " .. score)
end
```