Scripting API
Scripting API
SceneEntity
Class in Abyss.Core.Scenes, from Abyss.Core.
One entity, and everything about it a file can hold.
public sealed class SceneEntityProperties
Id
public ulong? Id { get; init; }What this entity is called inside this document, for something else to refer to.
Not a position and not a world id — a name that outlives both. SceneEntity.Parent can be an index because the reader is holding the array it indexes, and an entity id cannot be written down at all because it means something only in the process that issued it. This is the third thing: a number the document owns, minted when the entity is first written and carried back into the world so that saving again writes the same one.
It exists so that something outside the file can point inside it. A scene that instances this document as a prefab says "the entity called 8,123,948,201 sits one meter to the left" — and that has to keep meaning the same entity after the prefab is edited, its entities reordered, and two more added. An index would not survive any of those and a name would not survive a rename.
Forty-eight bits of randomness, not a counter. A counter would make two documents edited apart collide the moment one was instanced into the other, which is the case that matters. Forty-eight rather than sixty-four so that every JSON reader holds it exactly, including the ones that parse every number as a double.
null means a document written before ids existed, or one built by hand in a test. An entity with no id cannot be overridden and says so rather than being guessed at.
Name
public string? Name { get; init; }What the entity is called, or null if nothing named it.
The entity's own name and nothing else. Earlier versions of this format invented keys here — entity0, entity1 — because an entity had no name and parents had to be expressed somehow. Entities can be named now, so SceneEntity.Parent refers by index instead and this field went back to meaning what it says. A scene full of invented names was the cost of not having real ones.
Parent
public int? Parent { get; init; }The index in SceneDocument.Entities of this one's parent.
An index into this file's own array, which is not the kind of number the format bans. What it bans is a number that means something only in the process that wrote it — an entity id, a component id, an asset id. A position in a list the reader is holding is self-contained, the way a glTF accessor index is.
Mesh
public string? Mesh { get; init; }The key of the mesh asset this entity is drawn with, if any.
Material
public string? Material { get; init; }The key of the material asset this entity is drawn with, if any.
Prefab
public string? Prefab { get; init; }The key of the prefab this entity is an instance of, or null for an ordinary entity.
An instance is one entity in the file and a subtree in the world. Opening the scene reads the prefab, builds what it describes, and puts this entity in the place of its root — so twenty instances of a lamp are twenty short entries rather than twenty copies, and changing the lamp changes all twenty.
What this entity says overrides what the prefab's root says. Its SceneEntity.Components are merged over the root's field by field, and its SceneEntity.Name, SceneEntity.Mesh and SceneEntity.Material replace the root's when they are set. A field the instance does not mention keeps following the prefab, which is the whole point of the reference: it is not a copy.
What is deeper inside the instance is in SceneEntity.Overrides, keyed by SceneEntity.Id. This entry is the root and nothing else.
Overrides
public List<SceneOverride> Overrides { get; init; }What this scene changed or added below the root of the instance, or empty.
Meaningless unless SceneEntity.Prefab is set, and dropped rather than written when it is not. See SceneOverride.
Components
public List<SceneComponent> Components { get; init; }What the entity carries, in name order.
Removed
public List<string> Removed { get; init; }For an instance, the components of its prefab's root it took off, by name, or empty; see SceneOverride.Removed.
