Игровые массивы

Многие методы нативного API возвращают LuaArray<T>. Несмотря на имя в TypeScript, это не JavaScript-массив, а доступное только для чтения userdata игры.

• допустимые индексы идут от 1 до Length;
• свойства JavaScript .length нет;
• pairs и обычные методы JavaScript-массивов не обходят значение напрямую;
• запись в values[index] или values.Length отклоняется игрой.

Методы arrays генерируют правильные циклы с индексацией от единицы.

Чтение и поиск в коллекции

import { agents, arrays } from "@killscript/sdk/client";

const enemies = agents.enemies();

arrays.forEach(enemies, (enemy, index) => {
  print(`${index}: ${enemy.Nickname}`);
});

const firstAlive = arrays.find(
  enemies,
  (enemy) => enemy.Stats.IsAlive,
);

const anyVisible = arrays.some(
  enemies,
  (enemy) => enemy.IsVisible,
);

Индекс в обработчике намеренно остаётся с единицы: он указывает позицию именно в нативной коллекции.

Создание обычного массива

map, filter и toArray возвращают обычный TypeScript-массив, который в собранном скрипте представлен Lua-таблицей:

const living = arrays.filter(
  enemies,
  (enemy) => enemy.Stats.IsAlive,
);

const names = arrays.map(enemies, (enemy) => enemy.Nickname);
const count = living.length;

Массив должен оставаться плотным: преобразование в map() не должно возвращать undefined. В Lua это значение становится nil, создаёт пропуск и ломает надёжное определение длины. Если элемент нужно исключить, сначала используйте filter().

Копия полезна для дальнейших обычных операций с массивом, сохранения снимка или независимости от изменения исходной коллекции. Сами элементы всё ещё остаются нативными объектами — копируется только контейнер.

Краткий справочник

Метод	Результат
forEach	Посещает каждое значение
some	true, если подходит хотя бы одно значение
every	true, если подходят все значения
find	Первое подходящее значение или undefined
map	Обычный массив преобразованных значений
filter	Обычный массив подходящих значений
toArray	Поверхностная копия в обычный массив
first / last	Крайнее значение или undefined

Небольшая реализация методов массивов добавляется в Lua, только если модуль использует хотя бы один из них. Для цепочек условий по игрокам смотрите Выборки игроков.