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:
| Member | What it does |
|---|---|
Count, Capacity | How 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>());| Parameter | Meaning |
|---|---|
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
- AbyssListAttribute: declares a list's item.
- ListType<T>: a registered list, with its query terms.
- DynamicList<T> and ReadOnlyDynamicList<T>: one entity's list.
- ListColumn<T> and ReadOnlyListColumn<T>: a chunk's lists.
- ListLayout: what one item of a list is.
