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 SceneLoaderRemarks
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.Singleto unload every other scene when this one is shown;SceneMode.Additiveto keep them.hold: Whether to hold it once it is built,SceneState.Ready, untilSceneLoader.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; seeScenePace. 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, untilSceneLoader.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.Gradualto 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.
