Scripting API
Scripting API
SceneImage
Class in Abyss.Core.Scenes, from Abyss.Core.
A scene as a built game reads it: each set of components its entities carry a column at a time, in the bytes the engine keeps them in, with what cannot be bytes beside them.
public sealed class SceneImageRemarks
A column image. The entities that carry the same components are one group, and each of those components that is made from bytes (ComponentTraits.PlainData) is one column of the group: every entity's value of it, one after another, as a spawn lays it out. A load spawns a group a few entities at a time and copies each column into the spawn as one block, where a scene file's values are written one field at a time. What is not bytes is said beside the columns: each entity's name, its parent, what it draws, and the values of the components Bevy or a plugin makes, which are added with their defaults and written over.
Each component's layout is carried — its size, and its fields' names, kinds, places and counts — with a hash of it. A component laid out as it was when the image was written is copied whole; one changed since, as a game's components change between a build and a patch, is copied a field at a time by name, a field renamed found by the name it says it had, one added starting as a new one does, and one gone said in a note.
Written from the scene's file, its prefab instances built into it and every mark a load puts on — an entity's name in its file, its prefab's — so a scene loaded from its image is the scene loaded from its file. See Write and SceneFile.Apply; SceneLoader reads either.
The file, little-endian: a 64-byte header — ABYSCENE, the version, how many entities, components, assets, groups, value records and strings it holds, where each of their sections starts, and how long the file is — then the components, each its name, whether it is made from bytes, its size, how many fields and the layout's hash, then its fields; the assets, each its kind, name, path, identity and the material it describes where it does; the entities, each its name, its parent, its mesh and its material, sixteen bytes; the groups, each its components, its members and then a column for each component made from bytes, starting on an eight-byte boundary; the value records, each an entity, a component, its fields' values and its choices; and the strings, each followed by a zero.
Properties
EntityCount
public int EntityCount { get; }How many entities it builds.
Methods
Is
public static bool Is(ReadOnlySpan<byte> start)Whether these bytes start as an image does: what tells one from a scene's text.
Parameters
start
Write
public static SceneImageWritten Write(World world, SceneDocument document, IPrefabSource prefabs, Stream output, Action<SceneDocument>? packing = null)Writes a scene's image: its prefab instances built, each entity planned as a load in world would plan it, and its components laid out as that world lays them.
Parameters
world: The world whose components the image lays out.document: The scene, as its file holds it.prefabs: Where the prefabs it instances are read.output: Where the image goes.packing: What a pack does to the scene once its prefab instances are built into it, before anything is laid out: its assets named as the pack names them, a model's material made the scene's own. The document it is given is the scene's and its instances', and is the caller's to change.
Returns How many entities it holds, and what could not be written exactly.
Exceptions
SceneFormatException: The document is not a version this build applies.
The world is the one whose components the image is to hold: a game's, with its components registered, as the editor's is. Nothing is spawned in it; what a scene names that nothing declares is kept there, as a load keeps it.
Read
public static SceneImage Read(Stream stream)Reads an image from a stream, all of it.
Parameters
stream
Exceptions
SceneFormatException: The bytes are not an image this build reads.
Read
public static SceneImage Read(byte[] bytes)Reads an image from its bytes, which it keeps.
Parameters
bytes
Exceptions
SceneFormatException: The bytes are not an image this build reads.
Constants
CurrentVersion
public const int CurrentVersion = 2The image version this build writes, and the newest it reads.
2: a value record's field naming an entity holds the entity's place among the image's and one more, as a column's does. Version 1 held the id the scene's file gave it, which named nothing in a built game: a Camera Follow 2D followed no target.
