Game arrays

Many native methods return LuaArray<T>. Despite the name in TypeScript, this is not a JavaScript array: it is read-only userdata exposed by the game.

• valid indexes run from 1 through Length;
• there is no JavaScript .length property;
• pairs and ordinary JavaScript array methods cannot iterate it directly;
• writing values[index] or values.Length is rejected by the game.

The arrays helpers generate the correct one-based loops for you.

Read and search a collection

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,
);

Callback indexes intentionally remain one-based because they identify the position in the native collection.

Create an ordinary array

map, filter and toArray return a normal TypeScript array represented by a Lua table in the bundle:

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

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

Keep the result dense: a map() transform must not return undefined. Lua stores undefined as nil, which creates a hole and makes array length and later operations unreliable. Use filter() first when an element should be omitted.

Use this when later code needs ordinary array operations, wants to keep a snapshot, or should not depend on the native collection changing underneath it. The copied elements are still native objects; only the collection itself is copied.

Helper summary

Helper	Result
forEach	Visits every value
some	true when at least one value matches
every	true when every value matches
find	First matching value or undefined
map	Ordinary array of transformed values
filter	Ordinary array of matching values
toArray	Shallow ordinary-array copy
first / last	Boundary value or undefined

The small array-helper runtime is added only when the module uses at least one of these helpers. For reusable agent-specific chains, see Agent selections.