Scripting API

Scripting API

Schedule

Class in Abyss.Core, from Abyss.Core.

An ordered set of systems that the engine can run, sequentially or in parallel.

public sealed class Schedule : IDisposable

Remarks

A schedule turns the access each system declared into an execution plan. Systems that do not conflict may overlap; systems that do are ordered by registration index, which makes parallel execution produce exactly the same result as sequential execution. That equivalence is the property worth having: a parallel run that can differ from a sequential one turns every gameplay bug into a question of whether the scheduler caused it.

Borrows are acquired and released around each system run, so a body never has to think about them. This is the granularity the conflict analysis already reasons in, so one concept covers both jobs.

A failing system does not abort the frame. A script that throws is a bug in that script, not a reason to stop simulating and rendering everything else — an engine that halts the world on one bad component leaves the developer with a frozen screen instead of a working game and an error message. So a throw is caught, reported through Schedule.SystemFailed, and the remaining systems run as normal. This is also what keeps the sequential and parallel paths equivalent: neither one skips systems because an earlier one failed.

Constructors

Schedule

public Schedule(World world)

Creates an empty schedule over world.

Parameters

  • world

Properties

Stopping

public CancellationToken Stopping { get; }

Canceled when this schedule's game stops: Stop in the editor, quitting, the game's scripts built again.

Timings

public ISystemTimings? Timings { get; set; }

What is told how long each system took as it ran and what it allocated, for a profiler; nothing is measured while it is null, as it is unless something sets it. Its Schedule.Fixed systems are told to this schedule's.

World

public World World { get; }

The world this schedule runs against.

Fixed

public Schedule Fixed { get; }

The systems that run at the game's fixed rate rather than once a frame: a schedule of their own over the same world, run once for each step of the game's fixed clock with the step as their SystemContext.DeltaTime — a sixtieth of a second unless the project's Time settings say otherwise — before the frame's systems, as many times a frame as the game's time has moved on by a step. Where what moves must move the same at any frame rate: physics, and what pushes on it.

A system goes in it as in any schedule — schedule.Fixed.Add(...) — or says so itself, with AbyssSystemAttribute.Fixed. Its systems are ordered among themselves, by what they touch and by Schedule.RunBefore, and never overlap the frame's, which run after them. Its own fixed systems are itself.

What runs a game runs it (Schedule.RunFixed): the editor, in Play and for what always runs, and a game on its own. Held while the game is paused, as the game's time is.

IsFixed

public bool IsFixed { get; }

Whether this is a schedule's Schedule.Fixed systems.

Count

public int Count { get; }

Number of systems in the schedule.

Frame

public long Frame { get; }

Frames run so far.

DrawsGizmos

public bool DrawsGizmos { get; set; }

Whether what its systems draw with their SystemContext.Gizmos is kept, for the editor to draw over its Scene panel: set for the schedules the editor runs. Off, as it is in a game on its own, every call to draw returns at once and nothing is kept.

CriticalPathLength

public int CriticalPathLength { get; private set; }

The longest chain of systems that must run one after another.

A lower bound on how many sequential steps a frame needs however many cores are available, so it is the number to watch when a schedule refuses to scale. Available after the plan is built.

SystemFailed

public SystemErrorHandler? SystemFailed { get; set; }

Called when a system throws. Set it to route failures into the host's logging.

When unset, failures go to the engine's Log as errors from schedule, which puts them in the editor's Logs panel and on standard error. That default exists because the alternative — swallowing exceptions silently — is far worse than noisy output: a system that quietly stopped working is a bug that can hide for weeks.

A handler is invoked under a lock, so it does not need to be thread-safe even though systems run in parallel. If it throws, that exception does propagate: a broken error handler is not something to paper over.

FailureCount

public long FailureCount { get; private set; }

Total system failures observed since the schedule was created.

Methods

WhenSpriteResizedInEditor<T>

public Schedule WhenSpriteResizedInEditor<T>(SpriteResizedInEditor<T> follow) where T : unmanaged

Has the editor change a T on an entity as it resizes the entity's sprite — its Size changed by the Rect tool, typed in the Inspector, given back to the image's, or any of those undone — inside the same step of the undo: how a collider stays fitted to its sprite as the sprite is stretched. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Type parameters

  • T

Parameters

  • follow

Returns This schedule, for chaining.

Told the size the sprite was drawn at and the size it is drawn at now, however it changed, so a drag told at every frame is followed a step at a time and an undo is the way back. One that throws is said in the logs, and the component left as it was.

WhenAddedInEditor<T>

public Schedule WhenAddedInEditor<T>(AddedInEditor<T> fill) where T : unmanaged

Has the editor fill a T it puts on an entity with Add Component — after it starts as its initializers say, before the step of the undo that put it on is over — from what the entity is: how a collider fits the sprite it is put on. For an EditorOnlyAttribute plugin's IPlugin.Build, the ECS way: the component stays plain data, and what fits it is the plugin's.

Type parameters

  • T

Parameters

  • fill

Returns This schedule, for chaining.

Let go of with this schedule, as the editor builds its plugins again with the game's scripts. A component loaded with a scene, spawned by code or added as a game plays is not filled: it is what the editor adds alone, as a person sees it added. One that throws is said in the logs, and the component kept as it started.

BakeInEditor

public Schedule BakeInEditor(string name, string title, string version, MeshBaker bake)

Has the editor bake each mesh of every model ticked for name as the model is imported: bake run on the mesh's corners and triangles, in the background, and what it gives kept beside the import and packed with the model, which a game reads with World.Baked. The model's import settings have a tick, title, and World.WantBaked ticks it. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Parameters

  • name: What the tick is kept as in a model's sidecar, and what the bake is found by: lowercase letters, digits, dots, dashes and underscores, as a package's id is.
  • title: What the tick is called in a model's import settings.
  • version: What it bakes as: a change bakes every ticked model again, as Jolt's version does a Mesh Collider 3D's.
  • bake: What it makes of one mesh, on a thread of its own.

Returns This schedule, for chaining.

Exceptions

  • ArgumentException: The name is not one a file can be called by.

ChoicesInEditor<T>

public Schedule ChoicesInEditor<T>(string field, Func<World, IReadOnlyList<string>> names) where T : unmanaged

Has the Inspector show field — a whole number — of every T as a list of the names names gives, the field holding the place of the one picked, from 0: what a component names out of a list the project keeps, a navmesh surface's agent type out of the Navigation settings'. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Type parameters

  • T

Parameters

  • field
  • names

Returns This schedule, for chaining.

Asked each time the Inspector reads a T, so a name added or renamed shows at once; a number past the last name is shown as the number. One that throws is said in the logs, and the field shown as a number.

MaskInEditor<T>

public Schedule MaskInEditor<T>(string field, Func<World, IReadOnlyList<string>> names) where T : unmanaged

Has the Inspector show field — an int — of every T as a mask of the names names gives, a bit each from the lowest, to tick under Nothing and Everything, as a [Flags] enum is: what a component picks several of out of a list the project keeps, an agent's areas out of the Navigation settings'. Everything is -1, every bit, so a name added later is ticked too. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Type parameters

  • T

Parameters

  • field
  • names

Returns This schedule, for chaining.

Asked each time the Inspector reads a T, as ChoicesInEditor<T> is; names past the 31st are given no bit.

EditInScene<T>

public Schedule EditInScene<T>(string button, SceneHandlesOf<T> handles, SceneEdited<T> edited) where T : unmanaged

Has the editor edit a T in its Scene view: a button called button in its section of the Inspector, which, on, draws the handles handles says on each picked entity carrying one, and changes it as edited says as they are dragged, added and deleted — each drag one step of the undo. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Type parameters

  • T

Parameters

  • button: What the Inspector's button reads.
  • handles: Where the handles are.
  • edited: What a handle dragged, added or deleted does.

Returns This schedule, for chaining.

The ECS way: the component stays plain data, and what its handles are and do is the plugin's. The handles are on the entity's XY plane, in its own units, where its GlobalTransform puts them, so a turned or scaled entity's turn and scale with it. Either delegate that throws is said in the logs, and the component left as it was.

ToolsMenu

public Schedule ToolsMenu(string path, Action<World> run)

Puts a command in the editor's Tools menu, under the plugin's package's name — the game's own first, outside any — at path, its folders and its name between slashes; picked, the editor runs it. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Parameters

  • path
  • run

Returns This schedule, for chaining.

Whatever it changes in the world is one step of the undo, named as the item is, which the editor finds by keeping the world as it runs; one that changes nothing is no step. One that throws is said in the logs.

EntityMenu

public Schedule EntityMenu(string path, Action<World, ulong> fill)

Puts a kind of entity in the editor's Entity menu and the Hierarchy's Create menu, under the plugin's package's name, at path: picked, the editor makes an entity named as the item is, where the menu makes one, and has fill give it what it is made of — its components, what is under it — in the same step of the undo; made again by a redo, it is filled again. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Parameters

  • path
  • fill

Returns This schedule, for chaining.

ComponentMenu<T>

public Schedule ComponentMenu<T>(string path, ComponentMenuAction<T> act) where T : unmanaged

Puts an item on the menu of every T the Inspector shows, at path: picked, act changes that component, which is written back as one step of the undo. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Type parameters

  • T

Parameters

  • path
  • act

Returns This schedule, for chaining.

Only what it changes of the component is undone. One that throws is said in the logs, and the component left as it was.

EditorWindow

public Schedule EditorWindow(string path, EditorWindowDraw draw)

Gives the editor a window, in its Window menu under the plugin's package's name — the game's own first, outside any — at path, its folders and its name between slashes: picked, it opens in a window of its own the first time, and wherever it was left after, and draw draws it once a frame while it shows. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Parameters

  • path
  • draw

Returns This schedule, for chaining.

One that throws is said in the logs, once, and in the window until it draws again.

EditorWindow<T>

public Schedule EditorWindow<T>(string path, EditorWindowDraw<T> draw) where T : unmanaged

Gives the editor a window, as Schedule.EditorWindow does, with a state of its own: T, a WindowStateAttribute struct, which the editor keeps for each person from one start to the next — its fields drawn with EditorUi.Fields — and hands to draw to read and change.

Type parameters

  • T

Parameters

  • path
  • draw

Returns This schedule, for chaining.

Exceptions

  • InvalidOperationException: T is no window's state registered in this world.

Its state is no part of the scene: changed, it is no step of the undo, and the scene is as it was saved.

AddFlow

public void AddFlow(string name, Func<Flow, Task> body)

Adds a flow: an async method of the game's, run once the game has started — after every plugin's IPlugin.BeforeFirstScene, the first scene active — on the engine thread, awaiting frames, seconds and loads, and stopped with the game. See Flow.

Parameters

  • name: What it is called.
  • body: The flow.

Begin

public Task Begin(SceneAddress? firstScene, bool inEditor, out GameStart start)

Starts the game: every plugin's IPlugin.BeforeFirstScene, one after another in the order they were built, each awaited before the next. What it gives back is over when they all are; what one throws is said in the log, and the next goes on. What runs a game calls it — the engine's player, and the editor at Play — and loads the first scene after.

Parameters

  • firstScene: The scene the build opens, which a plugin may change; null for none.
  • inEditor: Whether the editor plays it, from the scene open there.
  • start: What the plugins are given, and say the first scene in.

Started

public void Started()

The game has started, its first scene active: every plugin's IPlugin.Started, then its flows.

Stop

public void Stop()

Stops the game: every plugin's IPlugin.Stopping, then its async code — its token canceled, and nothing it was waiting for come back. Once; disposing does it too.

NoteInEditor<T>

public Schedule NoteInEditor<T>(NotedInEditor<T> note) where T : unmanaged

Has the Inspector say a line under a T's section, above its fields, from what its entity is now: how a component says what it will do that its fields alone do not — a mesh collider on a dynamic body meeting its mesh as its hull. For an EditorOnlyAttribute plugin's IPlugin.Build; let go of with this schedule.

Type parameters

  • T

Parameters

  • note

Returns This schedule, for chaining.

Asked each time the Inspector reads the entity, so it follows what changes; it says nothing where it gives null or nothing. One that throws is said in the logs, and says nothing.

AddPlugin

public Schedule AddPlugin(IPlugin plugin)

Builds a plugin into this schedule; given to a schedule's Schedule.Fixed systems, into the schedule they are of, which starts and stops it.

Parameters

  • plugin

Returns The schedule it was built into, for chaining.

AddPlugins

public Schedule AddPlugins(Assembly assembly)

Builds every plugin an assembly names with AbyssPluginAttribute<T> into this schedule, but those marked EditorOnlyAttribute: what a game's Program plays with, and so exactly what the editor plays. The ones marked ExecuteAlwaysAttribute are built first, so their systems come first where two touch the same thing, as they do in the editor.

Parameters

  • assembly

Returns This schedule, for chaining.

AddPlugins

public Schedule AddPlugins(Assembly game, IReadOnlyList<Assembly> packages)

Builds every plugin a game and its packages name into this schedule (see Schedule.AddPlugins): each package's first, after the packages it needs, as packages has them, so a game's plugins build on its packages'.

Parameters

  • game: The game's assembly.
  • packages: Its packages' assemblies, each after the packages it needs.

Returns This schedule, for chaining.

RunFixed

public void RunFixed(float step)

Runs the Schedule.Fixed systems once, for one step of step seconds: what a game's fixed clock does once for each step. Nothing until this schedule has run its first frame, so a game's fixed systems never run before its first frame's.

Parameters

  • step: Seconds of the step: the project's Fixed Timestep.

Drawn

public int Drawn(List<GizmoSegment> into)

Adds the lines each system drew with its gizmos when it last ran to into, system by system in the order they were added: what was drawn before a pause, while the schedule is not run.

Parameters

  • into

Returns How many lines were added.

Add

public SystemId Add(string name, ReadOnlySpan<QueryTerm> terms, SystemBody body, bool? markChanged = null, StructuralAccess structural = default)

Adds a system.

Parameters

  • name: Display name, used in diagnostics.
  • terms: The components the system reads and writes.
  • body: What the system does.
  • markChanged: Whether to bump Bevy's change ticks for this system's write columns after it runs. It costs a write per entity per write column, so it is not free, and most systems have nothing watching them. Left unset it decides itself: on when the system writes a component the engine declares, off otherwise. Those are exactly the components the engine's own systems change-detect, and a write they cannot see is a write that silently does nothing — an entity that simply does not move, with nothing to indicate why. Pass it explicitly to override either way.
  • structural: What the system may change about the shape of the world — which archetypes it may spawn, add or remove, and whether it may despawn or reparent. Defaults to StructuralAccess.None: a system that declares nothing may record nothing.

Add

public SystemId Add(string name, ReadOnlySpan<QueryTerm> terms, ReadOnlySpan<QueryFilter> filters, SystemBody body, bool? markChanged = null, StructuralAccess structural = default)

Adds a system whose query is narrowed by presence filters.

Parameters

  • name
  • terms
  • filters
  • body
  • markChanged
  • structural

There is deliberately no (terms, resources, body) overload: it would differ from this one only in the element type of a span, and an empty collection expression would then be ambiguous at every call site. Pass default for filters to reach the full form.

Add

public SystemId Add(string name, ReadOnlySpan<QueryTerm> terms, ReadOnlySpan<QueryFilter> filters, ReadOnlySpan<ResourceTerm> resources, SystemBody body, bool? markChanged = null, StructuralAccess structural = default)

Adds a system declaring components, filters and resources.

Parameters

  • name
  • terms
  • filters
  • resources
  • body
  • markChanged
  • structural

Filters are what let two writers of the same component be recognized as compatible, so a system that only applies to some entities should say so — it is the difference between running in parallel and being serialized.

AddNative

public SystemId AddNative(string name, NativeBody body, ReadOnlySpan<QueryTerm> terms, ReadOnlySpan<QueryFilter> filters = null, bool? markChanged = null)

Adds a system whose body is native engine code rather than a C# delegate.

Parameters

  • name: Display name, used in diagnostics.
  • body: The native body to run.
  • terms: The components it reads and writes, matching the body's columns.
  • filters: Presence constraints narrowing which entities it applies to.
  • markChanged: See Add.

Exceptions

  • ArgumentException: The terms are not the columns the body expects.

A native system is an ordinary member of this schedule. It declares terms the same way, registers in the same registry, and is judged by the same conflict analysis — so it can be ordered against C# systems, run concurrently with them where they do not conflict, and reported through Schedule.SystemFailed when it fails. Nothing here special-cases it beyond calling a different kind of body.

The terms must be exactly the columns the body expects, checked here. That check is the only place it can happen: a chunk carries base pointers and a row count but no element sizes, so a body handed the wrong columns would reinterpret whatever memory it was given rather than fail.

A native body cannot record commands. It receives no world handle — which is what lets it run outside the native lock, at full speed, alongside everything else — and that leaves it nothing to record against.

AddHosted

public SystemId AddHosted(string name)

Adds a system the engine runs itself, such as transform propagation.

Parameters

  • name: The name the engine registered the system under.

Exceptions

  • AbyssException: No system is registered under that name.

A hosted system is a real bevy_ecs system, and unlike a native body it needs the world rather than a set of chunks — which is exactly why it exists. Transform propagation cannot be expressed over chunks at all: a child's world transform depends on its parent's, which lives in a different row of a possibly different table.

A hosted system is a barrier: nothing overlaps it. Running one takes &mut World, a claim of exclusivity the engine cannot honor while another system's body is dereferencing chunk pointers, and a hosted system holding Commands could move entities between tables while those pointers are live. Serializing the whole frame around it is the conservative choice; the conflict analysis still decides everything else.

It still declares access, so it is still part of the conflict graph — a C# system writing Transform is correctly ordered against propagation rather than merely happening not to overlap it.

RunBefore

public void RunBefore(SystemId earlier, SystemId later)

Requires earlier to finish before later starts.

Parameters

  • earlier
  • later

Conflict analysis decides what may overlap; it says nothing about what must come first. Two systems touching disjoint components are free to run in any order as far as the data is concerned, but a game usually still wants input read before movement is applied. That intent has to be stated, and this is how.

For a pair that already conflicts, an explicit order also overrides the registration-order default, so a system registered later can still be made to run first.

RunAfter

public void RunAfter(SystemId later, SystemId earlier)

Requires later to start only after earlier finishes.

Parameters

  • later
  • earlier

The mirror of Schedule.RunBefore; use whichever reads better at the call site.

RunAlone

public void RunAlone(SystemId system)

Makes system run alone: every system added before it finishes before it starts, and every one added after it starts after it finishes, whatever they touch.

Parameters

  • system

For a system whose work every later one reads in a way no access declaration says: a physics step, whose contacts every system after it sees and whose queries none may ask while it steps. Bevy's exclusive systems are the same. What overlaps nothing holds the schedule up as it runs, so it is for a system that does much of its schedule's work anyway.

Its order is the order the systems were added in, over any Schedule.RunBefore that says otherwise; added first, it runs before them all.

Build

public void Build()

Computes the execution plan from the conflict graph and any explicit ordering.

Exceptions

  • InvalidOperationException: The ordering constraints form a cycle.

Called automatically by the first run after a change, so calling it directly is only useful to pay the cost at a chosen moment, to read Schedule.CriticalPathLength up front, or to surface an ordering cycle at startup rather than on the first frame.

Run

public void Run(float deltaTime)

Runs every system once, in registration order, on the calling thread.

Parameters

  • deltaTime

RunParallel

public void RunParallel(float deltaTime, int maxDegreeOfParallelism = 0)

Runs every system once, overlapping those that do not conflict.

Parameters

  • deltaTime: Seconds since the previous frame.
  • maxDegreeOfParallelism: Worker threads to use, or 0 for ProcessorCount.

The result is identical to Schedule.Run: conflicting systems are ordered by registration index, so only genuinely independent work overlaps.

Dispose

public void Dispose()

Releases every query the schedule owns.

Constants

LogSource

public const string LogSource = "schedule"

The source a failure is written to the Log under, when nothing handles it.