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 SceneImage

Remarks

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

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

Read

public static SceneImage Read(byte[] bytes)

Reads an image from its bytes, which it keeps.

Parameters

  • bytes

Exceptions

Constants

CurrentVersion

public const int CurrentVersion = 2

The 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.