Scripting API

Scripting API

SceneFile

Class in Abyss.Core.Scenes, from Abyss.Core.

Turns a world into a SceneDocument and a document back into a world.

public static class SceneFile

Remarks

Both halves of this were already built; what was missing was the format. The engine can say what an entity carries, what each component is called, and where its fields are — and it can be told to write bytes into one. That is a list of entities with named components holding values, which is what a scene is. The work here is deciding what a file may and may not say.

The rule that shapes all of it: a file may not contain a number that only means something in the process that wrote it. Entity ids, component ids and asset ids are all of that kind, so none of them appears. What appears instead is names — a component's registered name, a file's path, and keys the document invents for its own entities and assets.

Which entities belong to a scene is a mark on the entity. A world also holds the camera, the light, the window and whatever a plugin spawned for itself, and no rule for telling those apart from a game's own entities would be right for long — so the answer is not a rule but a record: every entity a load builds is put in the scene it makes (see SceneId), and SceneFile.Capture asks the world what is in the scene rather than being handed a list. An entity a system spawned into the scene afterwards is saved; one that died is not. A list the caller kept could have known neither.

Methods

Differences

public static PrefabDifferences? Differences(World world, ulong entity, AssetDatabase database, IPrefabSource prefabs, SceneWriting writing)

What entity, the top of an instance or a part a prefab supplied inside one, holds otherwise than its prefab says: the fields a scene writes as the instance's changes, read against the prefab as it is built, and the components it carries the prefab does not give it. Null for an entity no prefab supplied — one of the scene's own, or one it added inside an instance.

Parameters

  • world: The world it is in.
  • entity: The entity.
  • database: What every file under the asset root is called.
  • prefabs: Where its prefab is read.
  • writing: How the project writes its scenes, which a scene's changes are written as.

Where an instance's top is is no change: it is where the instance was put, so its Transform's translation, rotation and scale are left out, as a prefab's top has none.

A component the prefab has not is the instance's own, every field of it, and is said among PrefabDifferences.Added, not as a change of one of the prefab's.

OverridesOf

public static IReadOnlyList<PrefabOverride>? OverridesOf(World world, ulong root, AssetDatabase database, IPrefabSource prefabs, SceneWriting writing)

Everything the instance whose top is root did of its prefab, in the order its entities are listed: each component it changed and each it added, entity by entity, and each entity the scene put inside it, which is one line with all that is under it. Null for an entity that is the top of no instance.

Parameters

  • world: The world it is in.
  • root: The instance's top entity.
  • database: What every file under the asset root is called.
  • prefabs: Where its prefab is read.
  • writing: How the project writes its scenes.

Revert

public static PrefabReverted? Revert(World world, ulong entity, string component, string field, AssetDatabase database, IPrefabSource prefabs, SceneWriting writing)

Takes back what the instance entity is the top of, or is a part of, changed of its prefab in component's field; see SceneFile.Revert. Null where it changed nothing there, or is in no instance.

Parameters

  • world: The world it is in.
  • entity: The entity whose field it is.
  • component: The component's name.
  • field: The field's name, or what the names of several begin with before a dot.
  • database: What every file under the asset root is called.
  • prefabs: Where its prefab, and what it holds, are read.
  • writing: How the project writes its scenes.

Revert

public static PrefabReverted? Revert(World world, ulong root, PrefabOverride? item, AssetDatabase database, IPrefabSource prefabs, SceneWriting writing)

Takes back item of what the instance whose top is root did of its prefab — a change, a component added, which goes, or an entity added, which goes with all under it — or, for null, everything it did but where it was put: the instance written as a scene writes it, that left out, and built again of that in its place. Null where there was nothing to take back, or root is the top of no instance.

Parameters

  • world: The world it is in.
  • root: The instance's top entity.
  • item: What to take back, or null for everything.
  • database: What every file under the asset root is called.
  • prefabs: Where its prefab, and what it holds, are read.
  • writing: How the project writes its scenes.

ApplicableTo

public static IReadOnlyList<AssetGuid> ApplicableTo(World world, ulong root, AssetDatabase database, IPrefabSource prefabs)

The prefabs what the instance whose top is root did can be applied to: its own first, then the one that is a variant of, and so on down to one that is no variant. None for a model's instance, whose prefab its import makes, nor beyond a prefab that cannot be read.

Parameters

  • world
  • root
  • database
  • prefabs

ApplyTo

public static PrefabApplied? ApplyTo(World world, ulong root, PrefabOverride? item, AssetGuid into, AssetDatabase database, IPrefabSource prefabs, SceneWriting writing)

Applies item of what the instance whose top is root did — or, for null, everything it did but where it was put — to into, its prefab or one that is a variant of: what the prefab's file says with that said in it, as it would be written had it been done to the prefab open on its own. Nothing is written: what the file held and is to hold are given, with the instance as it was. Null where into is not among SceneFile.ApplicableTo, or does not have what the item is of — an entity a variant added, applied to its base — or there is nothing to apply.

Parameters

  • world: The world it is in.
  • root: The instance's top entity.
  • item: What to apply, or null for everything.
  • into: The prefab to apply it to.
  • database: What every file under the asset root is called.
  • prefabs: Where its prefabs are read.
  • writing: How the project writes its scenes, which its prefabs are written as.

Built as an instance of the prefab with only that change, in a scene of its own: its top under the prefab's own name for it, unpacked once — a variant's top an instance of its base then — the names the prefab gave its own entities, which unpacking takes, given back, and written as a scene writes it. So what the change is inside — an instance the prefab holds, a variant's base — is said where a save of the prefab would say it. The scene goes after.

Capture

public static SceneCapture Capture(World world, SceneId scene)

Writes everything in a scene into a document.

Parameters

  • world: The world to read.
  • scene: Which scene to save.

The engine is asked what is in the scene rather than told. Membership is a component on the entity, so an entity a gameplay system spawned into the scene is saved and one that died is not — neither of which a list the caller kept could have known.

The order is stable — two captures of an unchanged scene agree — and is the engine's rather than the order things were spawned in. See Capture for the overload that keeps the caller's.

Capture

public static SceneCapture Capture(World world, SceneId scene, AssetDatabase database)

Writes a scene into a document, naming its files by identity as well as by path.

Parameters

  • world: The world to read.
  • scene: Which scene.
  • database: What every file under the asset root is called.

Capture

public static SceneCapture Capture(World world, ReadOnlySpan<ulong> entities)

Writes what the named entities hold into a document.

Parameters

  • world: The world to read.
  • entities: The entities that belong to this scene, in the order they should be written. Anything they refer to that is not in the list — a parent, say — is treated as outside the scene and dropped, with a note.

Capture

public static SceneCapture Capture(World world, ReadOnlySpan<ulong> entities, AssetDatabase database)

Writes what the named entities hold into a document.

Parameters

  • world: The world to read.
  • entities: The entities that belong to this scene, in order.
  • database: What every file under the asset root is called. Each asset that came from a file is written down with its identity as well as its path, so the scene still opens after somebody moves the file. AssetDatabase.Empty writes paths alone, which is what every scene looked like before identities existed.

Capture

public static SceneCapture Capture(World world, ReadOnlySpan<ulong> entities, AssetDatabase database, IPrefabSource prefabs)

Writes what the named entities hold, folding instances back into references.

Parameters

  • world: The world to read.
  • entities: The entities that belong to this scene, in order.
  • database: What every file under the asset root is called.
  • prefabs: Where the prefabs this scene instances come from, so that an instance can be written as what it is: a reference, plus the fields that differ from it.

An instance is one entry and not a subtree. Every entity the prefab supplied is left out, because it is in the prefab; what is written is which prefab, and the values on the root that are not what the prefab says. Editing the prefab afterwards then reaches every scene that used it, which is the whole reason for a reference instead of a copy.

Without a prefab source an instance is still a reference, with every value on it. Nothing is lost and nothing is wrong — the scene opens identically — but the values were not compared against anything, so they are all written as overrides and stop following the prefab. That is the honest outcome for a capture that cannot read the file it is referring to.

Capture

public static SceneCapture Capture(World world, ReadOnlySpan<ulong> entities, AssetDatabase database, IPrefabSource prefabs, SceneWriting writing)

Writes what the named entities hold, as a project says scenes are written.

Parameters

  • world: The world to read.
  • entities: The entities that belong to this scene, in order.
  • database: What every file under the asset root is called.
  • prefabs: Where the prefabs this scene instances come from.
  • writing: Whether every field is written, or only what a load would not give back; see SceneWriting.

A field that holds what a load starts it as is left out: a transform at the origin writes nothing of its translation, and a light nobody changed names itself and nothing more. What a load starts it as is asked of the engine rather than assumed; see Given. A component that is an enum still says which of its values it holds, which is what says it is there.

A component marked SerializeAllFieldsAttribute, or every component under SceneWriting.ForceSerializeAllFields, is written whole instead.

Copied

public static void Copied(World world, IReadOnlyList<ulong> copies)

Takes off copies of a scene's entities the name a file knows each original by, which the next save gives each afresh — except what a prefab supplied inside a copy of an instance of it, where the name is the prefab's.

Parameters

  • world: The world the copies are in.
  • copies: The copies, each after the one it is under; see World.PutBackEntities.

Two entities under one name are one entity to whatever names it: an override in a scene that instances this one, above all, which would change the first of them and never the second. A copy is another entity, so it is given a name of its own, as one made is.

Below a copied instance's root, a part's name is the prefab's, and it is how a save tells what the prefab has there from what the scene added, as it does for the instance copied — so it is kept, as a second instance of the prefab has the same names in it as the first. What the scene added inside it, an instance included, is the scene's, and named afresh as anything else copied is; see PrefabPart. So is what a prefab supplied copied on its own, with no copy of its instance: no prefab put the copy there, so it loses the part's mark as well.

PrefabOf

public static AssetGuid? PrefabOf(World world, ulong entity)

The prefab an entity is the top of an instance of, or null for one that is none: what the editor's Open Prefab opens. See PrefabInstance.

Parameters

  • world
  • entity

EntitiesIn

public static ulong[] EntitiesIn(World world, SceneId scene)

Every entity in a scene, by entity id, in the order the hierarchy lists them.

Parameters

  • world: The world to ask.
  • scene: The scene to look for.

Exceptions

  • AbyssException: The scene is not one, or has been unloaded.

NameOf

public static string NameOf(string path)

What a scene read from path is called: the file's name, its extension off.

Parameters

  • path

scenes/orbit.scene is called orbit.

Apply

public static SceneLoad Apply(World world, SceneDocument document)

Builds the document's entities in a world, and returns what became of them.

Parameters

  • world: The world to build in.
  • document: What to build.

Nothing existing is removed: a scene is applied to a world rather than replacing it, because what else is in the world — a camera, a light, another scene — is not the file's business. A caller that wants a clean world despawns first.

Apply

public static SceneLoad Apply(World world, SceneDocument document, AssetDatabase database)

Builds the document's entities, finding its files by identity where it can.

Parameters

  • world: The world to build in.
  • document: What to build.
  • database: What every file under the asset root is called.

Apply

public static SceneLoad Apply(World world, SceneDocument document, SceneId scene)

Builds the document's entities as part of a scene that already exists.

Parameters

  • world: The world to build in.
  • document: What to build.
  • scene: The scene every entity is put in.

Which scene is not in the file and never could be — a SceneId is an entity of one run — so it is given here, and it is what lets the scene be found, saved and unloaded afterwards without anybody keeping a list.

Apply

public static SceneLoad Apply(World world, SceneDocument document, SceneId scene, AssetDatabase database)

Builds the document's entities as part of a scene that already exists.

Parameters

  • world: The world to build in.
  • document: What to build.
  • scene: The scene every entity is put in.
  • database: What every file under the asset root is called, so that a reference whose file has moved since the scene was written still finds it. AssetDatabase.Empty follows the paths alone, which is what every load did before identities existed.

Apply

public static SceneLoad Apply(World world, SceneDocument document, SceneId scene, AssetDatabase database, IPrefabSource prefabs)

Builds the document's entities, building any prefabs it instances too.

Parameters

  • world: The world to build in.
  • document: What to build.
  • scene: The scene every entity is put in.
  • database: What every file under the asset root is called.
  • prefabs: Where the prefabs this scene instances come from.

Instances are expanded before anything is spawned, and the expansion is a document. What reaches the rest of this method is a scene with no instances in it — which is a thing it already knew how to build — so prefabs cost the loader one call and the engine nothing. See PrefabExpansion.

Save

public static SceneCapture Save(World world, SceneId scene, string path)

Captures a scene and writes it to a file.

Parameters

  • world: The world to read.
  • scene: Which scene to save.
  • path: Where to write, on the ordinary filesystem.

Save

public static SceneCapture Save(World world, SceneId scene, string path, AssetDatabase database)

Captures a scene and writes it to a file, naming its assets by identity too.

Parameters

  • world: The world to read.
  • scene: Which scene.
  • path: Where to write, on the ordinary filesystem.
  • database: What every file under the asset root is called.

Save

public static SceneCapture Save(World world, ReadOnlySpan<ulong> entities, string path)

Captures the entities and writes them to a file.

Parameters

  • world: The world to read.
  • entities: The entities that belong to this scene.
  • path: Where to write, on the ordinary filesystem.

The path is not resolved against the asset root and is not checked against it. A scene is written by a tool, by somebody who chose where it goes; the root exists to stop a running game reading a path a player typed, which is a different question.

Save

public static SceneCapture Save(World world, ReadOnlySpan<ulong> entities, string path, AssetDatabase database)

Captures the entities and writes them to a file.

Parameters

  • world: The world to read.
  • entities: The entities that belong to this scene.
  • path: Where to write, on the ordinary filesystem.
  • database: What every file under the asset root is called.

Save

public static SceneCapture Save(World world, ReadOnlySpan<ulong> entities, string path, AssetDatabase database, IPrefabSource prefabs)

Captures the entities and writes them to a file, instances included.

Parameters

  • world: The world to read.
  • entities: The entities that belong to this scene.
  • path: Where to write, on the ordinary filesystem.
  • database: What every file under the asset root is called.
  • prefabs: Where the prefabs this scene instances come from.

Save

public static SceneCapture Save(World world, ReadOnlySpan<ulong> entities, string path, AssetDatabase database, IPrefabSource prefabs, SceneWriting writing)

Captures the entities and writes them to a file, as a project says scenes are written.

Parameters

  • world: The world to read.
  • entities: The entities that belong to this scene.
  • path: Where to write, on the ordinary filesystem.
  • database: What every file under the asset root is called.
  • prefabs: Where the prefabs this scene instances come from.
  • writing: Whether every field is written; see SceneWriting.

Open

public static SceneLoad Open(World world, string path)

Reads a scene from a file and applies it to the world.

Parameters

  • world: The world to build in.
  • path: Where to read from.

Exceptions

Open

public static SceneLoad Open(World world, string path, AssetDatabase database)

Reads a scene from a file and applies it, finding its files by identity.

Parameters

  • world: The world to build in.
  • path: Where to read from.
  • database: What every file under the asset root is called.

Exceptions

Open

public static SceneLoad Open(World world, string path, AssetDatabase database, IPrefabSource prefabs)

Reads a scene from a file and applies it, building the prefabs it instances.

Parameters

  • world: The world to build in.
  • path: Where to read from.
  • database: What every file under the asset root is called.
  • prefabs: Where the prefabs this scene instances come from.

Exceptions

Apply

public static SceneLoad Apply(World world, SceneImage image, SceneId scene, AssetDatabase database)

Builds an image's entities as part of a scene that already exists, all at once.

Parameters

  • world: The world to build in.
  • image: What to build.
  • scene: The scene every entity is put in.
  • database: What every file under the asset root is called, so a file that moved is found.

ListItemField

public static string ListItemField(int index, string field)

The name a list's item's field has in a scene: [2].Wait for the third's Wait.

Parameters

  • index
  • field

TryListItemField

public static bool TryListItemField(string name, out int index, out string field)

The item and the field of the item a list's field in a scene names — 2 and Wait for [2].Wait — or false for a name that is no item's.

Parameters

  • name
  • index
  • field

Constants

SceneExtension

public const string SceneExtension = ".scene"

What a scene file's name ends with: one that opens in place of the scene that is open.

PrefabExtension

public const string PrefabExtension = ".prefab"

What a prefab file's name ends with: one instanced into the scene that is open. Inside it is the same document a scene is.

ListCount

public const string ListCount = "Count"

The field a list's scene holds how many items it has in.

MaximumListItems

public const long MaximumListItems = 1048576

The most items a scene gives a list: more is a file written wrong, not a list.