Scripting API

Scripting API

StructuralAccess

Struct in Abyss.Core, from Abyss.Core.

What a system is allowed to change about the shape of the world.

public readonly struct StructuralAccess

Remarks

Query terms say what a system reads and writes within entities. This says what it may do to which entities exist and what they are made of — and the two are deliberately separate declarations, because a system that spawns projectiles does not touch any existing projectile's columns. Folding structural access into the query terms would make that spawner conflict with every system reading those components and serialize it for nothing.

This takes no part in the conflict analysis, and that is not an oversight. Commands are recorded into a per-system buffer and applied after the frame, in schedule order, when no chunk pointer is outstanding — so two systems recording into the same archetype genuinely cannot interfere, and ordering them would cost parallelism to prevent nothing. What the declaration buys is honesty: without it a system can change which queries an entity matches without having named any of the components involved, and every later check trusts a declaration that was never complete.

The default is StructuralAccess.None — declaring nothing means recording nothing. A system that genuinely cannot say in advance what it will restructure can say StructuralAccess.Everything, which is the same escape hatch as before this existed, except that it is now written down.

Properties

None

public static StructuralAccess None { get; }

Declares no structural change at all. The default.

Everything

public static StructuralAccess Everything { get; }

Declares that anything goes, for a system whose restructuring cannot be enumerated.

An escape hatch rather than a convenience. It says the same thing the engine assumed of every system before this declaration existed — the difference is that it now appears at the call site, where a reader can see which systems are outside the contract.

AndDespawn

public StructuralAccess AndDespawn { get; }

The same declaration, also permitting despawns.

Separate from the archetype list because a despawn names no archetype: it takes everything the entity has, whatever that turns out to be when the buffer applies.

AndReparent

public StructuralAccess AndReparent { get; }

The same declaration, also permitting parenting and unparenting.

AndSetMesh

public StructuralAccess AndSetMesh { get; }

The same declaration, also permitting entities to be given a mesh.

Separate from the archetype list for the same reason a despawn is: the components involved carry asset handles, so they are not in any archetype a caller could name.

AndSetMaterial

public StructuralAccess AndSetMaterial { get; }

The same declaration, also permitting entities to be given a material of their own.

What a copy of a material is for: one entity of many drawn with a surface gets one of its own, and keeps its mesh. See CommandBuffer.SetMaterial.

AndSetScene

public StructuralAccess AndSetScene { get; }

The same declaration, also permitting entities to be put in a scene or taken out of one.

Spawning into a scene needs it as well as the archetype: which scene an entity is in is a component of its own, and one no archetype names. See CommandBuffer.Spawn.

AndInstantiate

public StructuralAccess AndInstantiate { get; }

The same declaration, also permitting instances of prefabs to be made.

Separate from the archetype list because an instance is whatever its prefab is made of, which no caller could name in advance. See CommandBuffer.Instantiate.

AndAnimate

public StructuralAccess AndAnimate { get; }

The same declaration, also permitting clips to be played and stopped.

Separate from the archetype list for the reason giving a mesh is: what a clip plays on is Bevy's player, which no archetype names. See CommandBuffer.Play.

AndSetName

public StructuralAccess AndSetName { get; }

The same declaration, also permitting entities to be named, or their names taken away.

A name is Bevy's Name, which no archetype a caller builds names, and giving or taking one moves an entity between archetypes. See SetName.

Methods

Using

public static StructuralAccess Using(params ReadOnlySpan<Archetype> archetypes)

Declares that the system may spawn, add, or remove these archetypes.

Parameters

  • archetypes