Scripting API
Scripting API
SceneDocument
Class in Abyss.Core.Scenes, from Abyss.Core.
A scene as it exists in a file: entities, what each one carries, and what they are drawn with.
public sealed class SceneDocumentRemarks
This is deliberately a document rather than a world. Nothing here holds an entity id, a component id or an asset id, because every one of those is an index into a table the process that wrote it happened to build — a number that means something else, or nothing, in the process that reads it. What a file can carry is names: a component's registered name, a file path, and keys the document makes up for its own entities and assets.
The translation in both directions is SceneFile. Keeping it out of here is what lets a document be built, inspected and compared in a test with no world at all.
Properties
Derived
public static IReadOnlySet<string> Derived { get; }The components a scene leaves for the engine to recompute.
GlobalTransform is the whole of this set, and it is in it because it is an answer: propagation derives it from the local transform and the parent's, every frame, and a value in a file could only ever be a stale copy of one.
Not listed either. Until version 7 it was, with no values, because an entity that came back without it would not have been propagated and so would not have been drawn. Since Bevy made the transform require it (bevy_transform 0.19.1, src/components/transform.rs:75), a load brings it back with the transform. A version 6 file that lists it loads as it did.
Assigned
public static IReadOnlySet<string> Assigned { get; }The components a load supplies itself, and a capture therefore leaves out.
A different reason from SceneDocument.Derived, which is why it is a different set. InScene holds a SceneId — the scene's entity, which means nothing outside the run that made it — and that is exactly the kind of number this format exists to keep out of files. It is not listed at all, not even empty: the load puts every entity it builds in a scene, so recording it would be recording the loader's own behavior back to itself.
Version
public int Version { get; init; }The format version this document was written at.
NamesThrough
public bool NamesThrough { get; set; }Whether an instance's overrides in it name a part through an instance that holds it, which a build before version 11 would find nothing of: set by a capture that names one so, and by reading a file of version 11; see SceneDocument.WrittenAt.
UiClass
public string? UiClass { get; set; }For a UI document, the name of the class the build makes of it — MainMenu — kept in the file so the class keeps its name as the file is renamed; null for a scene or a prefab.
Assets
public List<SceneAsset> Assets { get; }Everything the entities refer to, by the keys they refer to it with.
Entities
public List<SceneEntity> Entities { get; }The entities, in the order they were captured.
Methods
Reads
public static bool Reads(int version)Whether this build reads a file written at version.
Parameters
version: The version the file says it was written at.
WrittenAt
public static int WrittenAt(SceneDocument document)The version document is written at: the oldest that holds all it says.
Parameters
document: The document about to be written.
Version 9 where nothing in it needs 10, so a scene with no instance added inside another opens in a build from before 10 as it did, and the files a project already has are not rewritten for a change none of them uses. An instance's own overrides say it: only an added instance holds more. 11 where it names a part through the instance holding it, which a number alone does not say, so the capture that names one so says it; see SceneDocument.NamesThrough. 12 where it says a component was taken off. 13 where it holds a corner's two radii or a generic font family as Bevy 0.20 holds them.
ResolveReferences
public void ResolveReferences(AssetDatabase database)Gives every field that names a file — SceneField.Reference — the identity the file has now: its own where database knows it, and otherwise the one of the file at the path the scene wrote beside it. What neither finds keeps the identity it had.
Parameters
database
What a build does once a document's prefabs are expanded, so a field whose file lost its sidecar and was given a new identity still names it, as an asset of the scene's still finds its file.
Constants
CurrentVersion
public const int CurrentVersion = 13The newest format version this build writes, and reads.
What matters is that a file from a later build is refused rather than half-understood: a scene silently missing the entities whose shape changed is worse than a scene that will not open.
Version 7 writes an entity's transform and visibility as fields of its own beside its mesh and material, lists no GlobalTransform, and leaves out a component another one brings back as it is. Version 8 leaves out a field that holds what a load starts it as, too — a scale of one — and so has to be refused by a build before it, which would start a transform's missing fields at zero. Version 9 writes an enum that differs from what a load gives as what differs of it, its variant with only the fields that do, and so has to be refused by a build before it, which would refuse another variant named without all its fields. Versions 6 to 8 are read as they always were; see SceneDocument.OldestReadable.
Version 10 holds an instance added inside another — an override with a SceneOverride.Prefab — which a build before it would build as an entity with nothing in it. Only a file that holds one is written at 10; see SceneDocument.WrittenAt.
Version 11 names a part an instance holds through that instance's id — what two instances of one prefab in another tell their parts apart by; see PrefabExpansion.Through — which a build before it would find no part of, and so drop the change. Only a file that names one so is written at 11; see SceneDocument.NamesThrough.
Version 12 says which of a prefab's components an instance, or a part of one, took off (SceneEntity.Removed, SceneOverride.Removed), which a build before it would put back. Only a file that says one is written at 12.
Version 13 holds what Bevy 0.20 holds as Bevy 0.19 did not: a UI element's corner as its two radii, border_radius.top_left.x and .y, which a build before it would drop, and a text's generic font family as {"Generic": "SansSerif"}, which it would refuse. Only a file that holds one is written at 13; one before it is read as 0.20 holds what it says (SceneJson).
OldestReadable
public const int OldestReadable = 6The oldest format version this build still reads.
Versions 6 and 7 hold nothing version 8 cannot: their transform and visibility may be among the components, and what they write that version 8 leaves out, a load gives the same value. They wrote every field, so none of theirs is left to what a load starts it as. Version 8 wrote every enum whole, which version 9 reads as a value naming all of its variant's fields.
