Scripting API

Scripting API

SceneLoader

Class in Abyss.Core.Scenes, from Abyss.Core.

Loads scenes into a world and unloads them while a game plays, a slice at a time, so that no frame pays for a whole scene.

public sealed class SceneLoader

Remarks

In three phases. The file is read and parsed off the frame, on the thread pool — a scene's text, or its image, which a built game reads (SceneImage). The scene is built in slices, as many pieces each frame as fit in SceneLoader.Budget — its prefabs, its assets, and its entities a few at a time — into a scene that is loading, so that nothing of it is seen until all of it is there (World.SetSceneLoading). And then it is shown, all of it at once, unless the game asked to hold it, in which case it waits, SceneState.Ready, until the game says SceneLoader.Activate. A scene big enough that showing all of it at once would be felt can be shown a few entities at a time instead, over several frames (ScenePace.Gradual). An unload hides the scene at once and despawns it a slice at a time, everything under an entity before it; a gradual one hides nothing, and only despawns it.

Asked from anywhere, done in one place. SceneLoader.Load, SceneLoader.Unload and SceneLoader.Activate may be called from a system while others run beside it, as SystemContext.Scenes calls them: each is written down, and the scene's id is reserved and handed back at once, so the game knows which scene it asked for on the line it asked. SceneLoader.Step does the work, on the thread that runs the frame, between the frames the systems run in: once a frame, by whatever runs the world's frames.

A path is under the world's assets (World.AssetRoot), as a game names one: scenes/level.scene — or in a pack mounted on the world, which is looked in first (World.MountPack). What goes wrong — a file that is not there, one this build cannot read — is written to the log under scene, and the scene is gone; what a file could not say exactly is written there as a warning when it is shown.

Properties

Budget

public TimeSpan Budget { get; set; }

How long each frame's step may build and despawn for: four milliseconds unless the game says otherwise, a quarter of a frame at sixty a second.

Checked after each piece rather than before it, so a step does at least one piece and a piece that runs long runs over by that piece alone. Zero builds one piece a frame.

Database

public AssetDatabase Database { get; set; }

What every file under the assets is called, so a scene finds a file that moved; empty to follow paths alone.

Prefabs

public IPrefabSource Prefabs { get; set; }

Where the prefabs a scene instances are read from.

Cache

public string Cache { get; set; }

Where the imports of the project's models are, which a game's code reads a model's prefab from (World.LoadPrefab), its whole path; empty for the cache beside the assets, ModelImporter.CacheFolder, where the editor keeps it.

LetsGo

public bool LetsGo { get; set; }

Whether a scene's load lets go of what it loaded — meshes, materials, images — once its entities hold it, so it goes when they do: when the scene is unloaded. A game's do; the editor keeps what it loaded, which an undo may name again after the entity holding it has gone, and lets go of what a game played loaded when it stops.

IsBusy

public bool IsBusy { get; }

Whether anything is being loaded or unloaded, or is held ready.

Methods

Load

public SceneId Load(string path, SceneMode mode = Single, bool hold = false, ScenePace pace = AtOnce)

Starts loading a scene, and says which it is: at once, before any of it is read.

Parameters

  • path: The scene's file, under the world's assets: scenes/level.scene.
  • mode: SceneMode.Single to unload every other scene when this one is shown; SceneMode.Additive to keep them.
  • hold: Whether to hold it once it is built, SceneState.Ready, until SceneLoader.Activate: for a game that shows a loading screen until the player presses on.
  • pace: Whether it is shown all at once, the default, or over several frames, a few entities at a time, for a scene big enough that all at once would be felt; see ScenePace. A single one unloads the others at the same pace.

Returns The scene, which SceneLoader.StateOf and SceneLoader.ProgressOf follow.

Load

public SceneId Load(SceneAddress scene, SceneMode mode = Single, bool hold = false, ScenePace pace = AtOnce)

Starts loading a scene by its key — Addresses.Scenes.Level — found by its identity wherever it is, then by its address; see SceneLoader.Load.

Parameters

  • scene: The key the build wrote for an addressable scene.
  • mode: Whether the other scenes go once it is shown, or stay.
  • hold: Whether to hold it, built, until SceneLoader.Activate.
  • pace: Whether it is shown all at once, or over several frames, a few entities at a time.

Activate

public void Activate(SceneId scene)

Lets a scene held ready be shown, at the next step; one not held is shown when it is built anyway.

Parameters

  • scene

Unload

public void Unload(SceneId scene, ScenePace pace = AtOnce)

Starts unloading a scene: at the next step everything in it is hidden at once, and then despawned a slice at a time, everything under an entity before it, the scene last. A scene still loading stops loading.

Parameters

  • scene: The scene to unload.
  • pace: ScenePace.Gradual to hide nothing and only despawn it, within the budget, so that no frame pays even for hiding it; what is not despawned yet is still seen. A scene asked to go twice goes at the pace it was first asked to.

StateOf

public SceneState StateOf(SceneId scene)

Where a scene is: loading, held ready, shown, unloading — or none, for one gone or never there.

Parameters

  • scene

A scene made some other way — opened in the editor, applied with SceneFile — is SceneState.Active from the first step after it is made.

ProgressOf

public float ProgressOf(SceneId scene)

How far a scene's load has got, from nothing to all of it: one for a scene shown or held ready.

Parameters

  • scene

A scene shown gradually counts the pieces it is shown in among its pieces, so it is all of it once all of it is shown, and a little short of that while it is held ready.

Step

public void Step()

Does this frame's loading and unloading, within SceneLoader.Budget: on the thread that runs the frame, between the frames systems run in, once a frame.

Forget

public void Forget()

Drops every load and unload, as they are: what Stop does, before it puts the world back as it was when Play was pressed — which takes away whatever they had made.

Constants

LogSource

public const string LogSource = "scene"

What a load's news is written to the log as.