Scripting API

Scripting API

GameCode

Class in Abyss.Core, from Abyss.Core.

Code of a game's that runs between frames on the engine thread — a flow, a plugin's start — and what it can wait for there: the next frame, seconds of the game's time, a load.

public abstract class GameCode

Remarks

Whatever it awaits, it comes back to the engine thread, between frames, where the world is its own: after await http.GetStringAsync(url) it may spawn, load and write as freely as before it. The request itself goes on wherever .NET runs it; only what follows the await comes back, once a frame, before the systems run.

It stops with the game. GameCode.Stopping is canceled when the game stops — Stop in the editor, quitting, the game's scripts built again — and what it was waiting for then never comes back: no line after an await runs against a world that has moved on. Pass the token to what takes one, as HttpClient does, so the wait ends too.

Properties

World

public World World { get; }

The world, the code's own between frames.

Stopping

public CancellationToken Stopping { get; }

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

Assets

public AssetAccess Assets { get; }

The world's assets, as a system reaches them: loaded by address or by path.

Scenes

public SceneAccess Scenes { get; }

The world's scenes, as a system reaches them: loaded by address or by path.

Packs

public PackAccess Packs { get; }

The world's packs: one mounted over the others, and taken away again.

Methods

NextFrame

public Task NextFrame()

Waits for the next frame of the game's: comes back once, before its systems run.

Seconds

public Task Seconds(float seconds)

Waits for seconds of the game's time, which does not pass while it is paused.

Parameters

  • seconds

Until

public Task Until(Func<bool> done)

Waits until done says so, asking it once a frame.

Parameters

  • done

Loaded

public Task<AssetState> Loaded(PrefabId prefab)

Waits for a prefab's load to end, and says how: AssetState.Loaded or AssetState.Failed.

Parameters

  • prefab

Loaded

public Task<AssetState> Loaded(MeshId mesh)

Waits for a mesh's load to end, and says how.

Parameters

  • mesh

Loaded

public Task<AssetState> Loaded(MaterialId material)

Waits for a material's load to end, and says how.

Parameters

  • material

Loaded

public Task<AssetState> Loaded(ImageId image)

Waits for an image's load to end, and says how.

Parameters

  • image

Loaded

public Task<AssetState> Loaded(AudioClipId clip)

Waits for a sound clip's load to end, and says how.

Parameters

  • clip

Loaded

public Task<SceneState> Loaded(SceneId scene)

Waits for a scene's load to end, and says how: SceneState.Active, SceneState.Ready for one held, or SceneState.None for one that failed.

Parameters

  • scene

Unloaded

public Task Unloaded(SceneId scene)

Waits for a scene to be gone, unloaded or never loaded.

Parameters

  • scene

AnimationEvent<T>

public Task<Fired<T>> AnimationEvent<T>(ulong animator) where T : unmanaged

The next event of type T a clip fires on animator: awaited, it is the event, its struct as the clip's timeline set it.

Type parameters

Parameters

  • animator: The animator: a model's instance's root.

Play

public Task<bool> Play(ulong animator, ClipId clip, float fade = 0, bool? loop = null, string? layer = null, int priority = 0)

Plays a clip on an animator, as World.Play does, and waits for it to end: true once it has played to its end, false once it was stopped, replaced, or refused for one of a higher priority playing on its layer — if (await Play(fox, attack, layer: "Upper", priority: 5)). One that loops ends only as it is stopped or replaced.

Parameters

  • animator: The animator.
  • clip: The clip.
  • fade: How long it takes to come in, in seconds; zero or more.
  • loop: Whether it loops; null for as the clip says.
  • layer: The controller's layer it plays on, by its name; null for the first.
  • priority: How much it matters: one playing on its layer is replaced only by one as high or higher.

Exceptions

  • AbyssException: The animator is not there, the clip id names none, or the fade is no time.

Ended

public Task<bool> Ended(AnimationAction action)

Waits for an action to end: true once it has played to its end, false once it was stopped, replaced or refused, or its animator is gone.

Parameters

Rebind

public Task<RebindResult?> Rebind(PlayerInput input, ActionName action, int binding = 0, string? part = null, RebindOptions? options = null)

Listens for what the player presses next and binds the bindingth binding of action to it, as PlayerInput.Rebind does; null where it was canceled, by Escape or Start unless options say otherwise — RebindResult? done = await flow.Rebind(input, Actions.Player.Jump);.

Parameters

  • input
  • action
  • binding
  • part
  • options

Exceptions

Heard is what goes down after it begins — not the click that began it — on the device the binding reads now, and what fits it: a key or button for a button or a composite's part, a stick for a vector. Anything else is passed over, and it listens on. There is one ear: the editor's Input page listening as well hears the same.

Prepare

public Task Prepare(IEnumerable<(MeshId Mesh, MaterialId Material)>? draws = null, IEnumerable<PrefabId>? prefabs = null, IEnumerable<ulong>? instances = null)

Draws what the game will draw once where nobody sees it, each mesh with its material, an instance of each prefab and each instance the game set up as it will draw it, their particles sent out, and waits until what the GPU compiles to draw them is compiled: what a game does while it loads, so nothing it draws later holds a frame up the first time it is seen. Each is waited for to load first, and one that fails is passed over.

Parameters

  • draws: Each mesh, with the material it will be drawn with.
  • prefabs: Each prefab that will be instanced.
  • instances: The top of each instance the game made and set up as it will draw one, a material given its emitter say; the engine's from then on, and despawned once done.

A desktop compiles off the frame, and what is new shows a frame or two late. A browser has one thread, so the frame waits; Chrome on Windows took seconds over each pipeline of Bevy's lit surface the first time, the game frozen. A browser keeps what it compiled, so it is a new player's first visit this spares.