Scripting API

Scripting API

SystemContext

Struct in Abyss.Core, from Abyss.Core.

What a system body receives when it runs.

public readonly ref struct SystemContext

Remarks

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 does

Safe 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 : unmanaged

The 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

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 : unmanaged

Read-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 : unmanaged

Read/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. A static lambda, 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

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.