Arrays

This page explains arrays in a beginner-friendly way. An array lets you keep many values under one variable name and pick which value you want by using an index.

Back to Language Reference

What an Array Is

If one variable stores one value, an array stores many values of the same general kind.

Think of an array like a row of boxes. The variable name tells you which group of boxes you are using, and the index tells you which box inside that group you want.

Dim scores(10) As Integer

In this example, scores is the array variable. Later, you use an index such as scores[0] or scores[i] to work with one element inside that array.

Declaring an Array with Dim

Arrays are declared with Dim. The dimension part goes in parentheses after the variable name.

Dim <name>(<dimensionExpr>[, <dimensionExpr>...]) [As <typeName>]

• Dim scores(10) As Integer
• Dim names(3) As String
• Dim board(8, 8) As Integer

The expressions inside () describe the dimensions of the array. One expression gives you one dimension. Two expressions give you two dimensions, and so on.

Use As when you want to state the element type clearly, such as Integer, String, or a user-defined type name.

Reading and Writing Elements

After the array is declared, use square brackets to access an element.

Dim scores(10) As Integer
Dim currentScore As Integer

scores[0] = 100
scores[1] = 250
currentScore = scores[1]

This is an important pattern to remember:

• Use () in the Dim declaration.
• Use [] when reading or writing an element.

One-Dimensional Arrays

A one-dimensional array is the simplest kind. It is useful for lists.

Dim playerNames(3) As String
Dim firstName As String

playerNames[0] = "Luna"
playerNames[1] = "Nova"
playerNames[2] = "Sol"

firstName = playerNames[0]

You can also use expressions as indexes.

Dim index As Integer
Dim selectedName As String

index = 1
selectedName = playerNames[index]

Multi-Dimensional Arrays

An array can have more than one dimension. This is useful for grids, maps, image-like data, and board-style layouts.

Dim board(8, 8) As Integer
Dim x As Integer
Dim y As Integer
Dim cellValue As Integer

x = 2
y = 5
board[x, y] = 1
cellValue = board[x, y]

Each index matches one dimension. Separate multiple indexes with commas.

Indexes Can Be Expressions

You are not limited to plain numbers. Any valid expression can be used where an index is expected.

Dim values(10) As Integer
Dim i As Integer
Dim nextValue As Integer

i = 2
values[i] = 40
nextValue = values[i + 1]

This makes it easy to use loop counters, calculations, and other variables when working with arrays.

Getting Array Lengths

Use ArrayLen when you need to know how large an array is.

Dim values(3, 4) As Integer
Dim total As Integer
Dim columns As Integer

total = ArrayLen(values)
columns = ArrayLen(values, 1)

ArrayLen(values) returns the total number of elements in the array. ArrayLen(values, 1) returns the length of the second dimension, because dimensions are zero-based.

Resizing a One-Dimensional Array

Use Resize when you want to change the length of a one-dimensional array after it has already been declared.

Dim values(3) As Integer

Resize(values, 10)

After this call, values has room for 10 elements, so the valid indexes are 0 through 9.

Resize also works for one-dimensional array fields in custom types, including nested access chains such as Resize(player.Inventory.Slots, 10).

Resize keeps the old values that still fit in the new length. If the new length is larger, the new slots start empty.

If the array stores custom types, shrinking the array can lose object references that were only stored in the removed slots. Read the Resize page for a beginner-friendly explanation of that memory-leak risk.

Arrays in Larger Expressions

Array access is an expression, so it can appear anywhere an expression is allowed.

• total = scores[0] + scores[1]
• If board[x, y] = 0 Then
• DoSomething(values[i])

Index access can also be part of a longer chain, because LunarBasic supports postfix operations such as member access and indexing together.

• foo.bar[1]
• foo.bar[1].baz

Custom type fields can also be arrays, so foo.bar may itself be an array reference.

• player.InventorySlots[0] = 10
• count = ArrayLen(player.InventorySlots)
• Resize(player.InventorySlots, 16)
• count = ArrayLen(world.CurrentPlayer.InventorySlots)

Passing Arrays to Functions and Subs

You can pass an array directly to a function or sub that declares an array reference parameter. Inside the routine, you can use ArrayLen and index access on the parameter just like a regular array.

An array reference parameter uses empty parentheses () for a one-dimensional array or one comma per extra dimension for higher ranks, such as (,) for two dimensions.

Function SumAll(values() As Integer) As Integer
    Dim total As Integer
    Dim i As Integer

    total = 0
    For i = 0 To ArrayLen(values) - 1
        total = total + values[i]
    Next i
    Return total
End Function

Dim scores(5) As Integer
Dim result As Integer

scores[0] = 10
scores[1] = 20
scores[2] = 30
result = SumAll(scores)

Multi-dimensional arrays are passed the same way:

Function CountCells(grid(,) As Integer) As Integer
    Return ArrayLen(grid)
End Function

Dim board(8, 8) As Integer
Dim total As Integer

total = CountCells(board)

The rank in the parameter declaration must match the rank of the array you pass. Passing a two-dimensional array to a parameter declared as () is a compiler error, and passing a scalar variable to any array parameter is also a compiler error.

Passing a Row of a Multi-Dimensional Array

When a function expects a one-dimensional array, you can pass a single row of a two-dimensional array by indexing its first dimension.

Function SumRow(values() As Integer) As Integer
    Dim total As Integer
    Dim i As Integer

    total = 0
    For i = 0 To ArrayLen(values) - 1
        total = total + values[i]
    Next i
    Return total
End Function

Dim grid(4, 8) As Integer
Dim rowIndex As Integer
Dim rowTotal As Integer

rowIndex = 2
rowTotal = SumRow(grid[rowIndex])

grid[rowIndex] refers to the entire row at rowIndex, which is itself a one-dimensional array of length 8. The called function receives that row and can use ArrayLen and indexing on it normally.

Common Beginner Mistakes

• Declaring with [] instead of (). Write Dim scores(10), not Dim scores[10].
• Accessing with () instead of []. Write scores[0], not scores(0), when you use the array after declaration.
• Forgetting commas in multi-dimensional access. Write board[x, y].
• Using non-literal or non-positive dimensions for array fields in a Type block. Use positive integer literals such as Field Tiles(32, 18) As Integer.
• Mismatching array rank in a call. If a parameter is declared (,), the argument must be a two-dimensional array.
• Passing a plain variable to an array parameter. The argument must be an array variable, an array field, or an indexed row of a multi-dimensional array.

Current Notes

The current language accepts array declaration syntax in Dim statements, index access syntax in expressions and assignments, and array reference parameters in Function and Sub declarations.

If you are exploring more advanced array scenarios, also read Errors and Current Support so you can compare your code with the current implementation status.