Manual

Manual

Lists

A list is a component that holds as many items as an entity needs: a path's points, an inventory's stacks, a spawner's waves. This page covers declaring one, reaching it in a system and elsewhere, spawning an entity with one, and how the editor, scenes and Play keep it.

Declaring a list

Mark a partial struct [AbyssList]. The struct is one item. An entity that carries the list holds any number of them, which grows and shrinks:

using System.Numerics;using Abyss.Core;
[AbyssList]public partial struct Waypoint{    public Vector3 Position;
    [Tooltip("How long to wait here, in seconds.")]    public float Wait = 0.5f;}

An item's fields are what a component's can be (see Declaring a component), and the same attributes shape how the Inspector shows them. A field's initializer is what a new item starts as. [AbyssList] takes the same Name and Page settings as [AbyssComponent].

The list is a component of its own, not a field of another: the engine keeps each entity's items, frees them when the list is taken off or the entity goes, and copies them when an entity is copied. An entity that needs a list and other values carries the list beside a component holding them.

Prefer a fixed list where one will do. A list's items are kept apart from the entity's row, so a system reaching them jumps elsewhere in memory for each entity, where a component's values sit side by side in the chunk it walks. Where the items have a most they never pass, a FixedList8<T> up to FixedList128<T> field in a component holds them in the row, and is the better choice. Keep a list for items with no such limit.

The build registers a game's lists with its components. Find one again with world.List<Waypoint>(), which gives the list's ListType<Waypoint>.

Reaching a list

Code reaches an entity's items through a DynamicList<T>, a view of them where the engine keeps them:

MemberWhat it does
Count, CapacityHow many items it holds, and how many it has room for before it needs more.
this[index]The item at index, to read or write in place: path[0].Wait = 1f.
Add(item), AddRange(items)Adds at the end.
Insert(index, item)Puts an item at index, moving those from there on along.
RemoveAt(index)Takes out an item, moving those after it back.
RemoveAtSwapBack(index)Takes out an item and puts the last in its place, for a list whose order does not matter.
Clear()Lets go of every item.
EnsureCapacity(count)Makes room for count items at once.
AsSpan(), ToArray()The items as a span, or a copy of them.

foreach (ref Waypoint point in path) walks the items, each to write in place.

A view lasts as long as the code holding it runs. It is a ref struct, so it cannot be kept in a field or a component. One used after a structural change, an entity spawned or despawned or a component added or taken off, throws: reach the list again. A span from AsSpan is good until the list next needs more room, as one over a List<T> is.

In a system

A system method takes a list as it takes a component, one entity's at a time:

public static partial class Walking{    [AbyssSystem]    [MethodImpl(MethodImplOptions.AggressiveInlining)]    private static void Walk(ref Transform transform, ref Walker walker, DynamicList<Waypoint> path, in SystemContext context)    {        if (path.Count == 0)        {            return;        }
        Vector3 to = path[walker.At].Position;        // ...    }}
// In a plugin's Build:Walking.AddWalk(schedule, world.Transform(), world.Component<Walker>(), world.List<Waypoint>());
ParameterMeaning
DynamicList<T> / ReadOnlyDynamicList<T>Write or read list T, one entity at a time
ListColumn<T> / ReadOnlyListColumn<T>Write or read list T, a chunk's at a time: column[row] is one row's

By hand, a list's term is list.Write() or list.Read(), and chunk.GetLists<T>(column) or chunk.GetReadOnlyLists<T>(column) gives its column.

A list grows only its own entity's items, so a system with Parallel = true adds to each row's list on whichever thread runs it.

Outside a system

world.ListOf<Waypoint>(entity) gives an entity's list, between frames or in an editor tool, as a view: it marks the list changed. world.SetList(entity, path, items) gives a list its items whole. world.ListCount, world.ReadList, world.WriteList and world.ResizeList read and write a list's items as bytes, by its component id, for code that does not have its item's type.

Spawning an entity with a list

An entity spawned with a list, through a command buffer or world.Spawn, starts with an empty one. A command buffer fills it in the same frame:

SpawnBatch spawned = commands.Spawn(world.CreateArchetype(path.Id, walker.Id), 1);commands.SetList(spawned.Entities[0], path, [new Waypoint { Position = start }, new Waypoint { Position = end }]);

AddComponents gives a list to entities that lack it, empty, and leaves the items of one an entity holds as they are.

In the editor, scenes and Play

The Inspector shows a list as Items: its size, + to add a copy of the last item, - to take the last away, and Element 0, Element 1 and on, each item's fields as a component's are. A list of no items adds one as its fields' initializers say. Each change is one undo, and undoing a smaller size puts back the items it took away as they were.

A scene writes a list as Count, how many items it holds, and each item's fields under the item's place, [0].Position.X, leaving out those that hold what a new item starts as:

"Waypoint": { "Count": 2, "[0].Position.X": 4, "[1].Position.Z": -3, "[1].Wait": 2 }

A prefab's instance writes only the items' fields it changed, and each is marked in the Inspector to revert or apply as a component's field is. An item's EntityRef names an entity in the scene, as a component's does. A scene's image, in a built game, keeps a list whole.

Play's snapshot puts each list back as it was on Stop, and Duplicate and Paste give the copy a list of its own. When the game's code is built again with the item changed, each item keeps what its fields hold by their names, and a field renamed with [FormerlySerializedAs] is found by the name it had. A list no code declares any more is kept with what it holds, and is a list again once its code is back.

In the Scripting API