Scripting API
Scripting API
SystemContext
Struct in Abyss.Core, from Abyss.Core.
What a system body receives when it runs.
public readonly ref struct SystemContextRemarks
A ref struct because it carries SystemContext.Chunks, whose pointers are valid only for the duration of the call. The compiler will not let a body stash it anywhere.
Properties
Commands
public CommandBuffer Commands { get; }Records entities to create or remove, applied after the frame.
Deferred because spawning mid-frame would invalidate the very spans this system is iterating. Each system has its own buffer, so recording needs no synchronization even while systems run in parallel. Not inside SystemContext.ForEachChunkParallel: record after it.
Assets
public AssetAccess Assets { get; }The world's assets, to load, make, copy, change and let go of while the system runs.
At once, not deferred, unlike SystemContext.Commands: an asset is not in any table a chunk points into, so making one moves nothing this system or another is iterating — which is why a copy's id is there to use on the next line. Giving it to an entity is a command, because that is a change to the entity.
MaterialId mine = context.Assets.CopyMaterial(context.Assets.MaterialOf(entity)!.Value);context.Assets.UpdateMaterial(mine, MaterialSpec.Colored(1f, 0.2f, 0.2f));context.Commands.SetMaterial(entity, mine);context.Assets.Release(mine); // the entity keeps it, and it goes when the entity doesSafe from systems running in parallel: the world holds a lock round every asset call.
Scenes
public SceneAccess Scenes { get; }The world's scenes, to load and unload a slice at a time while the game plays; see SceneAccess.
Asked now and done between frames, so safe from systems running in parallel; a scene asked for is told back at once, before any of it is read.
Services
public Services Services { get; }The objects the game keeps that are no data of the ECS's, by their type; see Services.
Input
public PlayerInput Input { get; }Player zero's input actions, to ask about this frame: context.Input.Pressed("Jump"), context.Input.Vector("Move"). See PlayerInput.
Safe from systems running in parallel, and the same for every system in a frame: the frame's states are read once and kept. Not inside SystemContext.ForEachChunkParallel: ask before it.
Localization
public Localization Localization { get; }The game's strings in the player's language, and its languages: context.Localization.Format(Strings.Hud.Coins, ("count", coins)). See Localization.
Safe from systems running in parallel. Not inside SystemContext.ForEachChunkParallel: ask before it.
Gizmos
public Gizmos Gizmos { get; }What this system draws lines with over the editor's Scene panel; see Gizmos. Its own, as SystemContext.Commands is, and kept only in the editor: in a game on its own every call returns at once. Not inside SystemContext.ForEachChunkParallel: draw after it.
Selection
public EditorSelection Selection { get; }What the editor has picked, for drawing more for it; empty in a game on its own. See EditorSelection.
Chunks
public ChunkCollection Chunks { get; }The chunks matching this system's query, already resolved; inside SystemContext.ForEachChunkParallel, the slice alone.
DeltaTime
public float DeltaTime { get; }Seconds since the previous frame.
Frame
public long Frame { get; }Monotonic frame counter, starting at zero.
ResourceCount
public int ResourceCount { get; }Number of resources this system declared.
Methods
InputOf
public PlayerInput InputOf(int player)A player's input actions, to ask about this frame; see SystemContext.Input.
Parameters
player: Which player, from zero.
Events<T>
public IReadOnlyList<Fired<T>> Events<T>() where T : unmanagedThe events of type T clips fired on the last frame, in the order they fired, each its struct as the clip's timeline set it. See World.FiredEvents.
Type parameters
T: The event's struct, markedAnimationEventAttribute.
Safe from systems running in parallel, and the same for every system in a frame: the frame's events are read once and kept.
Text
public SharedText Text(string? text)A text holding text, to put in a component's SharedText field: label.Caption = context.Text($"Score {score}"). See World.Text.
Parameters
text
Safe from systems running in parallel: a text is made under the lock of the world's store of them, and nothing in the world moves. Not inside SystemContext.ForEachChunkParallel: make it before, or in a system of its own.
TextOf
public string TextOf(SharedText text)The string a text holds; see World.TextOf, and SystemContext.Text for where it is refused.
Parameters
text
Resource<T>
public Res<T> Resource<T>(int index) where T : unmanagedRead-only access to a declared resource, by the index it was declared at.
Type parameters
T
Parameters
index
The pointers were fetched once for the whole system run, so reading a resource here costs nothing — the boundary was already crossed.
ResourceMut<T>
public ResMut<T> ResourceMut<T>(int index) where T : unmanagedRead/write access to a declared resource, by declaration index.
Type parameters
T
Parameters
index
Not inside SystemContext.ForEachChunkParallel, where slices would write it at once.
ForEachChunkParallel
public void ForEachChunkParallel(ParallelChunkBody body, int minimumSlice = 1024)Runs body over this system's chunks a slice at a time, the slices spread across the machine's cores, and returns when every one has run.
Parameters
body: What runs for each slice. Astaticlambda, so nothing is allocated for it.minimumSlice: The fewest rows a slice is given: a loop whose rows cost little wants more, so that handing a slice to a thread does not cost more than running it.
Exceptions
InvalidOperationException: Called inside anotherSystemContext.ForEachChunkParallel.
For a loop over many entities that each stand alone: an entity's row read and written, and nothing else in the world. A slice is part of one chunk — minimumSlice rows at least, and a few slices for each core — and its spans start at its first row.
schedule.Add("Wobble", [transform.Write(), wobble.Write()], static context => context.ForEachChunkParallel(static (Chunk chunk, in SystemContext slice) => { Span<Transform> transforms = chunk.GetSpan<Transform>(0); Span<Wobble> wobbles = chunk.GetSpan<Wobble>(1); for (int i = 0; i < transforms.Length; i++) { ref Wobble bob = ref wobbles[i]; bob.Phase += bob.Speed * slice.DeltaTime; transforms[i].TranslationY = bob.Height * MathF.Sin(bob.Phase); } }));What a slice has is its chunk, SystemContext.DeltaTime, SystemContext.Frame, the resources read through SystemContext.Resource and SystemContext.Selection. What changes the world or is kept for the system as a whole is refused, as it would be written from several threads at once: SystemContext.Commands, SystemContext.Gizmos, SystemContext.ResourceMut, SystemContext.Assets, SystemContext.Scenes, SystemContext.Services, SystemContext.Events, SystemContext.Input, and any call on the world. Read what the body needs before the call, and record, draw and write after it. A body run with a few entities, on one slice, keeps the same rules, so a test with a few finds what a game with thousands would.
The same result as the loop run on one thread, as long as a slice writes its own rows alone: which thread runs which slice changes from frame to frame, and nothing a slice can reach depends on it. If a slice throws, the slices not yet begun are skipped and the exception is thrown here, so the system fails as it would have.
Allocates nothing once it has run a frame or two: the slices go to the .NET thread pool as one work item kept between runs, and this thread takes slices too.
