Array

Array<T> — массив только для чтения, который возвращают многие методы KILLSCRIPT API. Это userdata-объект, а не обычная Lua-таблица.

T обозначает тип элемента. Например, Array<Agent> содержит объекты Agent, а Array<Hitbox> — объекты Hitbox.

Зачем нужен и как обрабатывается

Array<T> — общий адаптер между игровыми коллекциями C# и Lua. Метод вроде Agents:GetAll() или Inventory:GetItems() формирует коллекцию, а Array только даёт Lua-коду безопасно прочитать её длину и элементы. Сам массив ничего не ищет, не обновляет и не применяет к игре.

Состав определяет API, который вернул массив. Если мир мог измениться — игрок умер, предмет подобрали или начался новый раунд — заново вызовите исходный метод, а не считайте сохранённый Array актуальным.

Главное

индексация начинается с 1;
количество элементов находится в Length;
выход за диапазон возвращает nil;
элементы и Length доступны только для чтения;
ipairs(array) работает;
оператор # и pairs(array) не поддерживаются;
массивы доступны и в client, и в Reflex server.

Полный пример

Пример получает всех агентов и обходит массив по индексам от 1 до Length.

local AgentsArray = Agents:GetAll()
local Count = 0

for Index = 1, AgentsArray.Length do
    if AgentsArray[Index] ~= nil then
        Count = Count + 1
    end
end

print("[Array example] Iterated " .. Count .. " agents")

Array<T>

Массив объектов одного типа, созданный игровым API.

Length

local count = array.Length

Свойство	Тип	Доступ	Описание
`Length`	`integer`	`get`	Количество элементов массива.

Имя свойства начинается с заглавной буквы. Запись в Length завершается Lua-ошибкой доступа.

Индексация

Первый элемент расположен по индексу 1, последний — по индексу Length.

local first = array[1]
local last = array[array.Length]

Недопустимый индекс не вызывает ошибку и возвращает nil:

array[0]                -- nil
array[-1]               -- nil
array[array.Length + 1] -- nil

Элементы массива доступны только для чтения. Даже присваивание того же объекта не разрешено:

array[1] = array[1] -- Lua access error

Обход элементов

Числовой цикл

Явный цикл лучше всего показывает границы массива и работает в любой Lua-части:

for index = 1, array.Length do
    local value = array[index]
    -- Работа с value
end

ipairs

ipairs поддерживается и возвращает индекс вместе с элементом:

for index, value in ipairs(array) do
    -- index начинается с 1
end

Отличия от Lua-таблицы

Array<T> отображается в Lua как userdata. Поэтому некоторые привычные операции с таблицами не работают.

Оператор длины

Не используйте #array:

local count = #array -- ошибка: attempt to get length of a userdata value

Используйте array.Length.

pairs

pairs(array) завершается ошибкой table expected, got userdata. Для последовательного массива используйте числовой цикл или ipairs.

Пустой массив

Если API вернул массив с Length == 0, цикл от 1 до Length не выполнит ни одной итерации. Дополнительная проверка первого элемента не требуется.

if array.Length == 0 then
    print("Array is empty")
end

Частые ошибки

Цикл начинается с 0

Индекс 0 всегда находится вне диапазона. Начинайте с 1.

Используется #array

Игровой массив не реализует Lua-оператор длины. Читайте Length.

Попытка изменить массив

Массивы API являются представлением данных игры только для чтения. Нельзя заменить элемент или изменить длину массива.