Scripting API
Scripting API
CommandBuffer
Class in Abyss.Core, from Abyss.Core.
Records entity creation and removal for the engine to apply at the end of the frame.
public sealed class CommandBufferRemarks
A system holds raw pointers into Bevy's storage. Spawning moves entities between tables and can reallocate those columns, so a spawn performed during a system would invalidate the spans that system — and every concurrently running one — is iterating. Commands are therefore recorded, not executed, and applied where no chunk pointer is outstanding.
The buffer lives in managed memory and crosses the boundary once per frame. Recording through the FFI would put a crossing on every spawn, which is exactly the per-item cost the engine exists to avoid: a game spawning a thousand projectiles would pay a thousand crossings.
Each system owns its own buffer, so recording needs no synchronization even while systems run in parallel. Buffers are applied in the schedule's execution order, which keeps a parallel frame producing the same world as a sequential one.
Properties
Count
public int Count { get; }Number of commands recorded and not yet applied.
IsEmpty
public bool IsEmpty { get; }Whether anything has been recorded.
Methods
Spawn
public SpawnBatch Spawn(Archetype archetype, int count)Records the creation of count entities, returning spans to fill with their initial values.
Parameters
archetype: The component set the new entities will carry.count: How many to create.
Values are written through spans rather than passed as arguments so that creating a thousand entities is one command with one contiguous payload, and so the shape matches how components are read everywhere else in the engine.
The returned spans point into the buffer and stay valid until the next recording on this buffer, which may move the backing array. Fill them before recording anything else.
Spawn
public SpawnBatch Spawn(Archetype archetype, int count, SceneId scene)Records the creation of count entities in a scene, returning spans to fill with their initial values.
Parameters
archetype: The component set the new entities will carry.count: How many to create.scene: The scene they are in;SceneId.Nonefor none.
In the scene from the frame they appear, and gone when it is unloaded. CommandBuffer.Spawn makes entities in no scene, which no unload takes; this is the same spawn, followed in the same buffer by putting them in scene. A scene unloaded before the buffer applies leaves them in none.
The spans are what CommandBuffer.Spawn gives, valid until the next recording.
Instantiate
public ulong Instantiate(PrefabId prefab, Vector3 position, Quaternion rotation, ulong parent = 0, SceneId scene = default)Records an instance of a prefab, and gives the entity at its top: at position and turned by rotation — under parent, relative to it, when one is given — its scale the prefab's.
Parameters
prefab: A prefab loaded, or loading, and not given back.position: Where the instance is, relative to its parent if it has one.rotation: How it is turned, relative to its parent if it has one.parent: What it is put under; zero for nothing.scene: The scene it is in, and goes with when it is unloaded;SceneId.Nonefor none.
Exceptions
InvalidOperationException: The prefab was given back, or never loaded; or the system did not declareStructuralAccess.AndInstantiate.
Built as the buffer applies, where it was recorded, for a prefab that has loaded: what is recorded after it — a component given to its top, its top put under something — finds it there. A prefab still loading is built once it has loaded, and its top is there from then; what the buffer said of it before is passed over, as a command naming an entity that is not there is. Despawned before then, it is never built.
The instance holds the prefab until it is built, so letting go of the prefab at once is safe; despawning the entity this gives despawns all of the instance. See World.LoadPrefab.
MoveToScene
public void MoveToScene(ulong entity, SceneId scene)Records putting one entity with no parent, and everything under it, in a scene.
Parameters
entityscene
A child is in its parent's scene, so an entity with a parent is skipped: move the entity at the top of it. Put under another entity later, an entity takes that one's scene, or none; taken out from under it, it stays in the scene it was in.
An entity no longer alive is skipped, and so is a scene unloaded before this applies, by the rule every non-spawn command follows.
MoveToScene
public void MoveToScene(ReadOnlySpan<ulong> entities, SceneId scene)Records putting several entities with no parent, and everything under each, in a scene.
Parameters
entitiesscene
LeaveScene
public void LeaveScene(ulong entity)Records taking one entity with no parent, and everything under it, out of every scene, so no unload takes it.
Parameters
entity
AddComponents
public ComponentBatch AddComponents(Archetype archetype, ReadOnlySpan<ulong> entities)Records giving entities the archetype's components, returning spans to fill with the values.
Parameters
archetype: The components to give them.entities: The entities to change.
A component an entity already carries is overwritten rather than rejected: "make sure this entity has a Stunned with two seconds on it" is the thing gameplay code actually wants to say, and it should not have to ask first.
An entity that is no longer alive when the buffer applies is skipped, not an error — see CommandOutcome.Added. The payload has the same shape as a spawn's, so the returned spans behave the same way: they point into the buffer and stay valid only until the next recording on it.
RemoveComponents
public void RemoveComponents(Archetype archetype, ulong entity)Records taking the archetype's components away from one entity.
Parameters
archetypeentity
RemoveComponents
public void RemoveComponents(Archetype archetype, ReadOnlySpan<ulong> entities)Records taking the archetype's components away from several entities.
Parameters
archetypeentities
Removing a component an entity does not have is ignored, as is naming an entity that is no longer alive. Both are the ordinary result of several systems deciding things independently during one frame, so neither fails the buffer.
SetList<T>
public void SetList<T>(ulong entity, ListType<T> list, ReadOnlySpan<T> items) where T : unmanagedRecords giving entity's list items, in place of what it holds: what an entity spawned with a list, which is empty, is filled with. An entity that has gone by the time the buffer is applied, or carries no such list, is skipped.
Type parameters
T
Parameters
entitylistitems
SetName
public void SetName(ulong entity, ReadOnlySpan<char> name)Records naming entity name, or taking its name away for an empty one: what a system names an entity with, as a name given in place would move it under the spans it holds. An entity that has gone by the time the buffer is applied is skipped.
Parameters
entityname
A system records it once it declares StructuralAccess.AndSetName.
SetParent
public void SetParent(ulong child, ulong parent)Records making child a child of parent.
Parameters
childparent
SetParent
public void SetParent(ReadOnlySpan<ulong> children, ReadOnlySpan<ulong> parents)Records making each of children a child of the matching parent.
Parameters
childrenparents
Exceptions
ArgumentException: The two spans are different lengths.
Parenting is what makes GlobalTransform mean anything: a child's world transform is its own composed onto its parent's, computed by Bevy's propagation during World.RunBevyFrame.
A pair naming a parent that is no longer alive is skipped rather than half-applied — the alternative is a child pointing at nothing. Naming a dead child is skipped too, on the same rule every non-spawn command follows.
SetMesh
public void SetMesh(ulong entity, MeshId mesh, MaterialId material)Records giving one entity a mesh and a material.
Parameters
entitymeshmaterial
SetMesh
public void SetMesh(ReadOnlySpan<ulong> entities, MeshId mesh, MaterialId material)Records giving several entities the same mesh and material.
Parameters
entitiesmeshmaterial
The common case by a wide margin — a thousand identical trees are a thousand entities, one mesh and one material — so it is the overload that does not need the caller to build two arrays of repeated ids.
SetMesh
public void SetMesh(ReadOnlySpan<ulong> entities, ReadOnlySpan<ulong> meshes, ReadOnlySpan<ulong> materials)Records giving each entity its own mesh and material.
Parameters
entitiesmeshesmaterials
Exceptions
ArgumentException: The three spans are not the same length.
This is the command that cannot be an AddComponents. What it inserts carries Bevy asset handles, which are reference-counted and have destructors — not bytes a caller can hand over — so the engine resolves the ids and constructs the components itself. See MeshId.
An entity that is no longer alive when the buffer applies is skipped, on the same rule every non-spawn command follows. An id naming an asset that does not exist is not skipped: the caller chose that number, and a silently undrawn entity is worse than an error.
A material of default, 0, keeps the material the entity has, or none, and changes only its mesh; a mesh of default leaves it a Mesh3d holding no mesh, as one added from Add Component holds.
The inserted mesh brings a transform with it, because Bevy's Mesh3d requires one. An entity that had none is positioned at the origin rather than left unpositioned.
Play
public void Play(ulong entity, ClipId clip, float fade = 0, bool? loop = null, string? layer = null, int priority = 0)Records playing a clip on an animator: faded in from what it was playing over fade seconds, or cut to at once for zero; looping, or once, as loop says, or as the clip's own Loop setting says for null.
Parameters
entity: The animator.clip: The clip.fade: How long it takes to come in, in seconds; zero or more.loop: Whether it loops; null for as the clip says.layer: The controller's layer it plays on, by its name; null for the first.priority: How much it matters: one playing on its layer is replaced only by one as high or higher.
Exceptions
ArgumentOutOfRangeException: The fade is negative, or not a number.
Playing what already plays carries it on, so a system may record the clip it wants at every frame. An animator that has gone is skipped when the buffer applies; one that is not one yet — a prefab's instance recorded in the same frame — plays it once it is. See World.Play.
On an animator a controller runs, it plays on layer at priority, as World.Play says; what it gives to wait on is not recorded.
A system records it once it declares StructuralAccess.AndAnimate.
Stop
public void Stop(ulong entity, string? layer = null)Records stopping every clip an animator plays, at once; on one a controller runs, what code played on layer, or on every layer for null. See World.Stop.
Parameters
entity: The animator.layer: The controller's layer whose action is stopped, by its name; null for every layer's.
A system records it once it declares StructuralAccess.AndAnimate.
SetLayerWeight
public void SetLayerWeight(ulong entity, string layer, float weight, float fade = 0)Records laying a layer of an animator a controller runs over the layers under it as much as weight, going there over fade seconds. See World.SetLayerWeight.
Parameters
entity: The animator.layer: The layer, by its name.weight: How much of it is laid over: held to 0 to 1.fade: How long it takes to get there, in seconds; zero or more.
Exceptions
ArgumentOutOfRangeException: The weight is not a number, or the fade is negative or not a number.
A system records it once it declares StructuralAccess.AndAnimate.
SetMaterial
public void SetMaterial(ulong entity, MaterialId material)Records giving one entity a material, keeping the mesh it has.
Parameters
entitymaterial
What a copy of a material is for: one of many entities drawn with a surface gets one of its own. See World.CopyMaterial.
The rules SetMesh follows hold: an entity no longer alive is skipped, and an id naming no material is an error. A material let go of in the same frame, before this applies, is still given — the world lets go of nothing until the frame's commands have run — so copying, giving and releasing in one breath leaves the entity holding it.
SetMaterial
public void SetMaterial(ReadOnlySpan<ulong> entities, MaterialId material)Records giving several entities the same material, keeping their meshes.
Parameters
entitiesmaterial
ClearParent
public void ClearParent(ulong child)Records detaching one entity from its parent.
Parameters
child
ClearParent
public void ClearParent(ReadOnlySpan<ulong> children)Records detaching several entities from their parents.
Parameters
children
An entity that has no parent is reached and left alone, which is not an error.
Despawn
public void Despawn(ulong entity)Records the removal of one entity.
Parameters
entity
Removing an entity that is already gone — because another system decided the same thing this frame — is ignored rather than an error. Two systems independently concluding something should die is ordinary gameplay, not a bug to report.
Despawn
public void Despawn(ReadOnlySpan<ulong> entities)Records the removal of several entities in one command.
Parameters
entities
Clear
public void Clear()Discards everything recorded without applying it, releasing any reserved entity ids.
Releasing is best-effort: measurement against Bevy 0.19.1 shows the ids are not actually made available again, so abandoning a recorded spawn does consume entity indices. The call is still made because it is the documented counterpart to reserving. See command::release in the Rust core for the measurement.
