Scripting API
Scripting API
World
Class in Abyss.Core, from Abyss.Core.
A Bevy ECS world that C# gameplay code can operate on directly.
public sealed class World : IDisposableRemarks
Component data lives in native memory owned by Bevy. C# never copies it: a query resolves to a small set of Chunks, each exposing its columns as Span{T} over the real storage. Writing to one of those spans writes to Bevy's memory.
A world is not thread-safe. Use it from one thread at a time.
Properties
AddOns
public AddOnList AddOns { get; }The add-ons the game's main pack lists — the first pack mounted — which its build made apart, for it to attach once it has them; the project's, while the editor plays the game (World.SimulateAddOns); none for a game playing from its folders otherwise.
Application
public GameApplication Application { get; }The game as an application: its name and version, whether it is in the editor, and Quit; see GameApplication.
Audio
public WorldAudio Audio { get; }Sound, as a game plays it from its code; see WorldAudio.
BakersVersion
public int BakersVersion { get; }A number that changes as bakers are registered and let go of, for the editor to see they have.
BakesWantedCount
public int BakesWantedCount { get; }How many models plugins have asked to be baked since the world was made; see World.BakesWanted.
Cameras
public WorldCameras Cameras { get; }Cameras, as a game shakes them; see WorldCameras.
DataAssetsVersion
public int DataAssetsVersion { get; private set; }A number that changes whenever a kind of data asset is registered or let go of, for an editor to see the list has.
Display
public GameDisplay Display { get; }How the game is shown as it plays, and how many frames a second it draws; see GameDisplay.
EditableInScene
public IReadOnlyList<SceneEditable> EditableInScene { get; }Every component the editor can edit in its Scene view, and what its button reads: each a plugin said, and a Line's points (World.LinePoints). Engine thread.
MenuItems
public IReadOnlyList<EditorMenuItem> MenuItems { get; }The items plugins put in the editor's menus, in the order they were put there.
MenuItemsVersion
public int MenuItemsVersion { get; private set; }Moves on whenever an item is put in or taken out: what the editor reads them again at.
EditorWindows
public IReadOnlyList<EditorWindowItem> EditorWindows { get; }The windows plugins gave the editor, in the order they were given.
EditorWindowsVersion
public int EditorWindowsVersion { get; private set; }Moves on whenever a window is given or taken away: what the editor reads them again at.
Services
public Services Services { get; }The objects a game keeps that are no data of the ECS's — a web client, a save system — found by their type. See Services.
Selection
public EditorSelection Selection { get; }What the editor has picked, for the game's C# systems to read as SystemContext.Selection: what Select last said, and nothing in a game on its own.
Time
public GameTime Time { get; }The game's clock: this frame's share of the game's time, the time since it started, its fixed step and how fast it runs. See GameTime.
Ui
public GameUi Ui { get; }The game's interface as it plays: the documents its UI Documents show; see GameUi.
Layers
public LayerSettings Layers { get; }The project's layers by name, as the game or the editor last told them (World.UseLayers).
Lights2D
public WorldLights2D Lights2D { get; }2D lights, as a game asks them how lit a point is; see WorldLights2D.
Lines
public WorldLines Lines { get; }Lines, as a game drives them from its code; see WorldLines.
Localization
public Localization Localization { get; }The game's languages and strings, and the language the player uses; see Localization.
PackageFolders
public IReadOnlyDictionary<string, string> PackageFolders { get; }Each package put in, by id, and its folder, whole.
Packs
public IReadOnlyList<Pack> Packs { get; }The packs mounted on this world, the first mounted first, each opened again for reading from any thread: what a scene is read from off the frame.
Particles
public WorldParticles Particles { get; }Particles, as a game plays them from its code; see WorldParticles.
GameMode
public GameMode GameMode { get; set; }Which of the game's own systems — its Rust plugins' — run on this world's frames.
Exceptions
ArgumentOutOfRangeException: Set to a value that is not one of the modes.
GameMode.Playing in a new world, so a game plays from its first frame. Setting it takes effect from the next of the game's schedules to run, which may be later in the same frame: set from inside the frame loop, the game's Update and what follows it run in that frame. Bevy's clock, which the game's Rust systems read, is held while it says GameMode.Paused, so the game's time does not move while it is paused.
InputActions
public InputActions InputActions { get; }The input actions in use: what World.UseInputActions was last given, or InputActions.Default from when the world was made.
A copy of what the world was given: changing it changes nothing until it is given again.
Input
public PlayerInput Input { get; }Player zero's input actions, to ask about each frame; see PlayerInput.
Cursor
public GameCursor Cursor { get; }The cursor as the game asks for it: held for a camera turned by the mouse, and hidden. A game on its own has it on its window; the editor holds it in the Game panel while the panel has focus, and Escape lets it go there until a click into the panel takes it again.
HeardInput
public HeardInput? HeardInput { get; }What has been heard since World.ListenForInput began, or null for nothing yet.
Preferences
public Preferences Preferences { get; }The player's own data: typed settings and files, in a folder of theirs; see Preferences.
SettingsVersion
public int SettingsVersion { get; private set; }A number that changes whenever settings are registered or let go of, for an editor to see the list has.
Missing
public IReadOnlyList<(string Name, ComponentId Id)> Missing { get; }Every component kept that no code declares any more, by name, in the order they went missing.
Tilemaps
public WorldTilemaps Tilemaps { get; }Tilemaps, as a game drives them from its code; see WorldTilemaps.
Trails
public WorldTrails Trails { get; }Trails, as a game drives them from its code; see WorldTrails.
SceneLoader
public SceneLoader SceneLoader { get; }Loads and unloads this world's scenes a slice at a time; a system reaches it through SystemContext.Scenes, and whatever runs the frames steps it once a frame.
AssetRoot
public string? AssetRoot { get; private init; }The folder the world's assets are read from, whole, as AssetSetup named it; null for a world made without assets.
What SceneLoader reads a scene named by its path under the assets from: scenes/level.scene, as a game names one.
Version
public ulong Version { get; }The world's structural version, mirrored in managed memory.
Every structural change — spawning, despawning — invalidates outstanding chunk pointers, because Bevy may move entities between tables or reallocate a table's columns. Chunks carry the version they were resolved at and refuse to hand out spans once it goes stale.
The value is cached rather than read across the boundary each time, so the check on the hot path is a field comparison rather than a P/Invoke. It is refreshed after every mutating call this class makes; World.RefreshVersion covers the case where the world was changed through some other route.
EntityCount
public int EntityCount { get; }Number of live entities. Diagnostic only: this walks entity metadata.
AnimationEvents
public IReadOnlyCollection<string> AnimationEvents { get; }The animation events registered with this world, by the names clips' events name them by.
AnimationEventsVersion
public int AnimationEventsVersion { get; private set; }A number that changes whenever an animation event is registered, for an editor to see the list has.
ComponentsVersion
public int ComponentsVersion { get; private set; }A number that changes whenever a component is registered with a field table, for an editor to see what curves can name has.
BorrowChecking
public bool BorrowChecking { get; set; }Whether development-time borrow checking is active. Off by default.
When on, resolving a query takes borrows of the components its terms name, and a resolve that would hand out spans aliasing an outstanding borrow fails instead. This is what catches two queries writing the same column at once — a silent logic bug single-threaded, and a data race once systems run in parallel.
Turn it on in development builds. It costs a counter update per component per resolve — not per entity — but the release frame loop should not pay for checks that development and the schedule-level conflict analysis have already made.
SystemCount
public int SystemCount { get; }Number of systems registered with this world.
LoopEnded
public bool LoopEnded { get; private set; }Whether RunFrameLoop ran and ended, taking the world with it: every call on it fails with AbyssStatus.AppExited from then on, so what is let go of afterwards — a game stopped as the editor closes — asks nothing of it.
LoopOnPage
public bool LoopOnPage { get; private set; }Whether RunFrameLoop started the loop on a page's frames, in a browser, and returned as it did: the world is the page's from then on, run for as long as the page is open, and World.Dispose lets it be.
Methods
SimulateAddOns
public void SimulateAddOns(AddOnList? list, bool attached, long bytesPerSecond)Plays the game with the project's add-ons, as the editor's Play does: list is the project's add-on groups, each with its files' catalog, every one attached, as the Game panel's Add-ons at Attached has them, or none, as a new player has them at To Download, so a load of what only one holds finds nothing and says which add-on. A download takes as long as the add-on's size at bytesPerSecond — at once for 0 — and attaches it from the project. Null stops, the game's folders read as they are.
Parameters
listattachedbytesPerSecond
IsAttached
public bool IsAttached(AddOn addOn)Whether a build of an add-on is attached: a pack mounted whose stamp says it is the game's, of the add-on's group; as the editor plays the game, one of the project's attached.
Parameters
addOn
WhyNotAttached
public string? WhyNotAttached(string path)Why the pack at path is not one the game attaches, or null where it is: a pack another game's build made, or one no build stamped, where the game's own are stamped.
Parameters
path
Exceptions
AbyssException: It is not a pack this build reads.
Unattached
public AddOn? Unattached(AssetGuid id, string address)The add-on listed as holding an asset — by its identity, else its address — that is not attached; null for none.
Parameters
idaddress
FillAddedInEditor
public void FillAddedInEditor(ulong entity, ComponentId component)Fills component, just put on entity by the editor, as the plugins asked (Schedule.WhenAddedInEditor): what the editor calls as it adds one, and nothing else. Engine thread.
Parameters
entitycomponent
FollowSpriteResize
public void FollowSpriteResize(ulong entity, Vector2 from, Vector2 to)Changes what is on entity as the plugins asked (Schedule.WhenSpriteResizedInEditor), its sprite just resized by the editor from from to to: what the editor calls as it resizes one, and nothing else. Nothing where the size did not change. Engine thread.
Parameters
entityfromto
Addressed
public string? Addressed(string address)The file an address names: in the packs mounted, the last mounted first, and then in the project's folders; null for an address nothing has.
Parameters
address: The address, matched exactly.
An address is a file's while it is ticked Addressable in the editor — its path, unless it was given another — and a built game's pack keeps it in its AssetCatalog. Where two files have one address, the first by path.
Labeled
public IReadOnlyList<string> Labeled(string label)The addressable files with a label, by path: the packs' mounted, the last mounted first, and then the project's, each once.
Parameters
label: The label, matched exactly.
LoadClip
public ClipId LoadClip(string path)Starts loading a model's clip — models/fox.gltf#Walk — or a clip file — sprites/coin.anim — and returns the id it will be known by: a model's read with its skins and clips, off the frame, and a clip file at once; playable at once, moving what it plays on once it has landed. A clip file's frames are shown by the animator's own sprite; see AnimationClipFiles.
Parameters
path: The model's path under the asset root,#, and the clip's name.
Exceptions
AbyssException: Assets are not enabled, or the path names no clip.
The same clip again is the same id, held once more, as a mesh's path is; each load is let go of with World.Release. World.StateOf says whether it has landed, and failed for a model with no clip of its name — whose clips the log lists.
LoadClip
public ClipId LoadClip(ClipAddress clip)Starts loading a clip by its key — a model's, Addresses.Fox.Walk, or a clip file's — found by its identity wherever it is, then by its address.
Parameters
clip: The key the build wrote for a clip of an addressable model, or an addressable clip file.
StateOf
public AssetState StateOf(ClipId clip)How far along a clip's load is.
Parameters
clip
PathOf
public string PathOf(ClipId clip)What a clip was loaded by: its model's path, #, and its name.
Parameters
clip
Exceptions
AbyssException: The world never gave out that id, or it has gone.
Release
public void Release(ClipId clip)Lets go of one load of a clip; what plays it plays it on, and it goes once nothing does.
Parameters
clip
Play
public AnimationAction Play(ulong entity, ClipId clip, float fade = 0, bool? loop = null, string? layer = null, int priority = 0)Plays 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. Gives the action it is, to ask how it is getting on.
Parameters
entity: The animator: an entity with anAnimator, the root of a model's instance.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
AbyssException: The entity is not there, the clip id names none, or the fade is no time.
Playing what already plays carries it on, so a system may ask for the clip it wants at every frame; a clip that played once and is done starts again. An entity with no animator yet — a prefab's instance not built yet — plays it once it has one.
On an animator a controller runs, it plays over the list of the layer layer names — the first for null — which is held until it is done, or stopped. One action plays on a layer at a time: another played there takes its place, unless the one playing has a higher priority, when it is refused — so a flinch interrupts an attack only when it should. The same clip played again is carried on. On a layer that adds, the clip's movement since its first frame is laid on. A layer the controller has not is the first, said once in the log. On an animator no controller runs, the layer and the priority are not read.
Not from a system, whose frame may be running: there, CommandBuffer.Play.
StateOf
public ActionState StateOf(AnimationAction action)How an action played on an animator is getting on, or how it ended.
Parameters
action: The action, asWorld.Playgave it.
Exceptions
AbyssException: Its animator is not there.
SetLayerWeight
public void SetLayerWeight(ulong entity, string layer, float weight, float fade = 0)Has a layer of an animator a controller runs laid over the layers under it as much as weight, from 0 to 1, going there from where it is over fade seconds: in place of its file's weight, until the game stops.
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
AbyssException: The entity is not there, no controller runs it as the game plays, the weight is not a number or the fade is no time.
Asked before the controller is read, it is set once it is. The first layer, which every other is laid over, is not weighed. Not from a system: there, CommandBuffer.SetLayerWeight.
Pose
public void Pose(ulong entity, ClipId clip, float time)Holds an animator time seconds into a clip, paused there, as an editor's playhead shows it: played looping, and held. Asked again with another time, it moves there; with another clip, that one is cut to, and nothing else is drawn with it.
Parameters
entity: The animator.clip: The clip.time: How far into it, in seconds; zero or more.
Exceptions
AbyssException: The entity is not there, the clip id names none, or the time is none.
A clip new to the animator is drawn a frame later, once Bevy has taken in the graph it was added to. An entity with no animator yet plays it once it has one, and is held at the next asking.
CurveValue
public (float Value, LengthUnit Unit)? CurveValue(ulong entity, string field)What a curve writing field — BackgroundColor.a, Node.width — would start from on entity, as it is shown: the copy a UI document's canvas draws for an element of the draft among it, as its sheets style it. A color's part in sRGB, an angle in degrees, a length in its own unit, one the layout works out as wide or tall as it was laid out, in pixels. Null where the entity carries no such component.
Parameters
entityfield
Exceptions
AbyssException: The field is not one a curve can write; the message says why.
PoseUiCanvas
public bool PoseUiCanvas(ulong entity, ClipId clip, float time)Holds the copy a UI document's canvas draws for the draft's animator entity time seconds into clip, as the Animation window's playhead shows it: its curves written into the copy alone, never the document. Asked each frame, as the copy is made again whenever the document changes. False where the canvas draws no copy of it.
Parameters
entitycliptime
EndUiCanvasPose
public bool EndUiCanvasPose(ulong entity)Lets go of the copy World.PoseUiCanvas held, what its clip wrote put back. False where the canvas draws no copy of it.
Parameters
entity
FiredClipEvents
public IReadOnlyList<FiredClipEvent> FiredClipEvents()The events clips fired on the last frame, in the order they fired: of the clips an animator plays at once, only the one drawn most fires, and a clip held by World.Pose fires none.
EventsOf
public IReadOnlyList<ClipEvent> EventsOf(ClipId clip)The events on a clip, in the order of their times, as its model's import settings wrote them; none until the clip has landed.
Parameters
clip: The clip.
Exceptions
AbyssException: The clip id names no clip.
Stop
public void Stop(ulong entity, string? layer = null)Stops every clip an animator plays, at once, and what was played on it before it had an animator. On one a controller runs, stops only what code played over its layers' lists — over layer's alone where it is named — and the lists take over again.
Parameters
entity: The animator.layer: The controller's layer whose action is stopped, by its name; null for every layer's.
Exceptions
AbyssException: The entity is not there.
AnimatorOf
public AnimatorState AnimatorOf(ulong entity)What an animator plays: each clip, its time and length, its weight while it fades, the one last played first.
Parameters
entity: The animator.
Exceptions
AbyssException: The entity is not there, or has no animator.
ReloadAnimationClip
public void ReloadAnimationClip(string path)Reads a clip file again into the clips loaded of it, so what plays it plays it as it is now.
Parameters
path: Relative to the asset root.
Exceptions
AbyssException: The path is not a clip file's, or it cannot be read; the one read before is kept.
What the editor does when a clip file is saved. One nothing has loaded is left to be read when it is.
PackAnimationClip
public byte[] PackAnimationClip(string path)What a built game reads of a clip file: each frame's image named where it is now, and no JSON.
Parameters
path: Relative to the asset root.
Exceptions
AbyssException: The path is not a clip file's, or it cannot be read.
SetSpriteImage
public bool SetSpriteImage(ulong entity, ImageId image, string slice)Has an entity's sprite draw the slice called slice of image, an image cut into slices, giving it a Sprite if it carries none; false where the entity is gone.
Parameters
entityimageslice
Exceptions
AbyssException: The image is no file's, is not cut into slices, or has no slice of that name — the message lists the ones it has — or the id names no image.
A slice is found by the name the Sprite Editor gave it, coins_3; the image's own settings place it, by the slice's pivot. A scene keeps the slice by its identity, as it keeps one picked in the inspector.
PreviewSpriteFrame
public bool PreviewSpriteFrame(ulong entity, string image, ulong? slice)Has an entity's sprite drawn at another frame — the image at image, and its slice of identity slice or the whole of it — by a stand-in the engine owns, which copies the sprite's place, size and sorting and is never saved; the sprite itself is left as it is, only not drawn. What the editor previews a clip's playhead with. False where the entity is gone.
Parameters
entityimageslice
Exceptions
AbyssException: The path is outside the asset root, or the image cannot be loaded.
EndSpritePreview
public bool EndSpritePreview(ulong entity)Stops drawing an entity's sprite at another frame: its stand-in taken away. False where it was not.
Parameters
entity
FiredEvents<T>
public IReadOnlyList<Fired<T>> FiredEvents<T>() where T : unmanagedThe events of type T clips fired on the last frame, in the order they fired, each its struct made of its fields: of the clips an animator plays at once, only the one drawn most fires, and a clip held by World.Pose fires none.
Type parameters
T: The event's struct, registered byRegisterAnimationEvent<T>.
Read once a frame from the engine and kept until the world's next World.Tick, so every system asking in a frame sees the same, from any thread.
UseSpriteSheet
public void UseSpriteSheet(string path, string? json)Gives the world the slices of the image at path, as SpriteSheet.EngineJson writes them, or takes them away with null: every sprite drawing one moved to where its slice now is, or drawing the whole image where it is gone, and a sprite waiting for them given its slice.
Parameters
path: The image, by its path under the asset root.json: Its slices, or null for none.
Exceptions
AbyssException: The slices cannot be read; the world keeps what it had.
LoadAudioClip
public AudioClipId LoadAudioClip(string path)Starts loading the sound clip at path and returns the id it will be known by: read off the frame, kept as its import settings say, and played as soon as it is asked, starting once it has landed.
Parameters
path: The clip's path under the asset root:audio/hit.wav.
Exceptions
AbyssException: Assets are not enabled, or the path leaves the asset root.
The same path again is the same id, held once more; each load is let go of with World.Release. World.StateOf says whether it has landed, and failed for a file that is not there or is no sound, which the log says.
LoadAudioClip
public AudioClipId LoadAudioClip(AudioAddress clip)Starts loading a sound clip by its key — Addresses.Audio.Hit — found by its identity wherever it is, then by its address.
Parameters
clip: The key the build wrote for an addressable sound.
StateOf
public AssetState StateOf(AudioClipId clip)How far along a clip's load is.
Parameters
clip
InfoOf
public (TimeSpan Duration, AudioLoadType? Kept)? InfoOf(AudioClipId clip)How long a clip plays, at its own pitch, and how it is kept, once it has landed; null while it is on its way, and a kept load type of null for a clip that could not be read.
Parameters
clip
Exceptions
AbyssException: The id names no clip.
PathOf
public string PathOf(AudioClipId clip)What a clip was loaded by: its path.
Parameters
clip
Exceptions
AbyssException: The world never gave out that id, or it has gone.
Release
public void Release(AudioClipId clip)Lets go of one load of a clip; what plays it plays it on, and it goes once nothing holds it.
Parameters
clip
UseAudioMix
public void UseAudioMix(AudioMix mix)Plays the game's mix from the next frame, what its code changed in the one before forgotten: what the editor tells the world as the Audio tab changes it, and a game as it starts. A world with no sound plays none.
Parameters
mix
Exceptions
AbyssException: The engine cannot use the mix, saying why.
UseAudioSettings
public void UseAudioSettings(string path, AudioSettings settings)Says what the project's clip at path is played with, as its import settings say: what the editor tells the world it plays a project in. A clip loaded already is read again with them. A clip in a pack is played with the settings it was packed with.
Parameters
pathsettings
Exceptions
AbyssException: The path leaves the asset root, or the settings say what the engine does not have.
UseImportedAudio
public void UseImportedAudio(string path, string? artifact)Says the project's clip at path is read from its import at artifact, in place of its file, or from its file again for null: every load of the path reads it, and a clip loaded already is read again from it, under the id it has. A sound of it playing on goes on as it began.
Parameters
path: The clip, by its path under the asset root.artifact: The import, its whole path; null to read the clip's file again.
Exceptions
AbyssException: The path leaves the asset root.
Bakers
public IReadOnlyList<BakerInfo> Bakers()The bakers the plugins registered, as the editor knows them, in the order they were.
WantBaked
public void WantBaked(MeshId mesh, string baker)Asks the editor to tick the model mesh is a part of for baker, which bakes it as it is imported: what a plugin does as a collider of the mesh is added. Nothing for a mesh of no model's — made by code, or a primitive — or one asked for already. Engine thread.
Parameters
meshbaker
BakesWanted
public IReadOnlyList<BakeWanted> BakesWanted(int from)The models plugins asked to be baked (World.WantBaked), from the fromth on: what the editor takes and ticks.
Parameters
from
BakeModel
public Task BakeModel(string artifact, IReadOnlyList<string> bakers, Action<BakeLanded> done)Bakes the imported model artifact by each baker named, in the background: each of its meshes of triangles read out of the import and handed to the baker, and what it made written beside the import (ModelImporter.BakedOf); then done told what each made, on that thread. A baker no plugin registered is left out. Engine thread.
Parameters
artifact: The model's import, its whole path.bakers: The bakers' names.done: Told what was baked, on the thread that baked it.
Returns The bake, under way.
Baked
public byte[]? Baked(MeshId mesh, string baker)What baker baked of mesh as the editor imported its model — from the packs mounted, in a built game, or from beside the model's import — as the baker gave it; null for a mesh of no model's, or one not baked.
Parameters
meshbaker
ForgetBaked
public void ForgetBaked(string model)Lets go of what has been read of a model's bakes, which the editor has just baked again.
Parameters
model: The model, by its path under the asset root.
ScreenToWorld
public Vector2? ScreenToWorld(ulong camera, Vector2 screen)The point of the world on the XY plane under screen, in logical pixels from the top left of where camera draws — its window, as InputState.CursorX and InputState.CursorY measure — or null where it sees none there. A Pixel Perfect Camera's point goes through its enlargement, so what is under the pointer is found whether the camera draws small or not.
Parameters
camera: The camera, by its entity.screen: The point, in logical pixels from the top left.
Exceptions
AbyssException:AbyssStatus.MalformedEntityIdfor bits that pack no entity, andAbyssStatus.InvalidProjectionfor a point that is not one.
ScreenRay
public Ray3D? ScreenRay(ulong camera, Vector2 screen)The ray camera sees along through screen, in logical pixels from the top left of where it draws, as InputState.CursorX and InputState.CursorY measure the pointer; null where it sees nothing through it. What is under the pointer in a 3D world is what the ray meets first: cast it into the world's colliders, Physics3D.Raycast(ray.Origin, ray.Direction). Through a Pixel Perfect Camera's enlargement, as World.ScreenToWorld.
Parameters
camera: The camera, by its entity.screen: The point, in logical pixels from the top left.
Exceptions
AbyssException: AsWorld.ScreenToWorldsays.
WorldToScreen
public Vector2? WorldToScreen(ulong camera, Vector3 point)Where the world's point is drawn, in logical pixels from the top left of where camera draws, or null where it does not see it: through a Pixel Perfect Camera's enlargement, as World.ScreenToWorld.
Parameters
camera: The camera, by its entity.point: The point of the world.
Exceptions
AbyssException: AsWorld.ScreenToWorldsays.
Children
public ComponentLayout Children()Bevy's Children: the entities under an entity, which Bevy keeps as each child's parent is set. A system reads a row's as a ChildrenView, its term this one's ComponentLayout.Read; an entity with no children carries none.
Name
public ComponentLayout Name()Bevy's Name: what an entity is called. A system reads a row's as a NameView, its term this one's ComponentLayout.Read; an entity nothing named carries none. See World.EntityName.
ChildrenOf
public ulong[] ChildrenOf(ulong entity)The entities under entity, in the order the hierarchy lists them; empty for one with none.
Parameters
entity
Exceptions
AbyssException: The world does not hold that entity.
A system reads them a row at a time instead, as a ChildrenView.
HintsInEditor
public IReadOnlyList<FieldHint> HintsInEditor(ComponentId component, IReadOnlyList<FieldHint> hints)hints, component's, with the names plugins have the Inspector offer for its fields as their choices: each name's place its number (ChoicesInEditor<T>), or for a mask its bit, ticked (MaskInEditor<T>); the same hints where none do. What the editor asks as it reads an entity. Engine thread.
Parameters
componenthints
ReloadController
public void ReloadController(string path)Reads an animator controller again for every animator naming it, what each plays kept by its name.
Parameters
path: Relative to the asset root.
Exceptions
AbyssException: The path is not a controller file's, or it cannot be read; the one read before is kept.
What the editor does when a controller file is saved. One no animator has named yet is left to be read when one does.
PackController
public byte[] PackController(string path)What a built game reads of an animator controller: each clip named where its model is now, and no JSON.
Parameters
path: Relative to the asset root.
Exceptions
AbyssException: The path is not a controller file's, or it cannot be read.
CheckCondition
public ConditionMistake? CheckCondition(string text)The mistake in a controller state's condition in this world, or null for none: a character it cannot have, something missing or left over, a field no component has, a number where true or false goes. An empty one always holds.
Parameters
text
ConditionFields
public IReadOnlyList<ConditionField> ConditionFields()Every field a controller state's condition can read: a game's own components' first, then the engine's, each in the order of their names.
LayersOf
public IReadOnlyList<LayerRun> LayersOf(ulong entity)What an animator plays, layer by layer, as its controller runs it; none for an animator no controller runs, or not run yet.
Parameters
entity
Exceptions
AbyssException: The entity is not there, or has no animator.
RegisterDataAsset<T>
public ComponentType<T> RegisterDataAsset<T>(ReadOnlySpan<ComponentFieldSpec> fields, ReadOnlySpan<FieldHint> hints, string name, string title, string menu, in T start) where T : unmanagedRegisters a kind of data asset: as a component nothing carries, so its fields are described and shown as a component's are, and listed among the world's World.DataAssetTypes. What the generator behind DataAssetAttribute calls; a game's or a package's registration calls that. The same struct again is the registration it had.
Type parameters
T: The struct.
Parameters
fields: Where its fields are, measured.hints: What its fields' attributes say of showing them.name: Its full name, which a file names it by and its component is registered by.title: Its name, which Create offers.menu: Where Create offers it, its parts joined by/; empty for Create itself.start: What one starts as.
Returns The struct, as a component of this world.
DataAssetTypes
public IReadOnlyList<DataAssetType> DataAssetTypes()The kinds of data asset code declares, described for an editor, in the order of where Create offers them.
Data<T>
public T Data<T>(AssetRef<T> asset) where T : unmanagedThe data asset asset names, read the first time it is asked for — from the pack the game plays from, or its file — and kept: a copy of its struct.
Type parameters
T
Parameters
asset
Exceptions
InvalidOperationException:Tis no kind of data asset registered here, or the asset is another kind, or cannot be read.KeyNotFoundException: It names nothing, or nothing the game has.
Safe from any system, parallel ones included: a read is made once, under the world's assets. A field its file cannot say is what it starts as, and said once in the log.
TryData<T>
public bool TryData<T>(AssetRef<T> asset, out T value) where T : unmanagedThe data asset asset names, as World.Data reads it; false where it names nothing or nothing that can be read.
Type parameters
T
Parameters
assetvalue
ForgetData
public void ForgetData(AssetGuid id)Has the next World.Data of the asset id read it again: what the editor does as its file changes.
Parameters
id
ForgetData
public void ForgetData()Has the next World.Data of every asset read it again.
SceneEditBytes
public byte[]? SceneEditBytes(ulong entity, ComponentId component)The bytes of component on entity as they are now, for the editor to edit in its Scene view: null where it edits no such component there, or the entity carries none. Engine thread.
Parameters
entitycomponent
SceneHandles
public bool SceneHandles(ulong entity, ComponentId component, ReadOnlySpan<byte> bytes, SceneEditHandles handles)Says the handles of component, as bytes hold it, into handles, emptied first, as its plugin says (Schedule.EditInScene): false where none says, or it threw, which is logged. Engine thread.
Parameters
entitycomponentbyteshandles
SceneEdited
public byte[]? SceneEdited(ulong entity, ComponentId component, ReadOnlySpan<byte> from, in SceneEdit edit)component as from holds it, changed as its plugin says edit changes it (Schedule.EditInScene), and nothing written: null where none says, or it threw, which is logged. Engine thread.
Parameters
entitycomponentfromedit
RunTool
public bool RunTool(EditorMenuItem item)Runs a plugin's Tools command; one that throws is said in the logs. Engine thread.
Parameters
item
Returns Whether it ran through.
RunCommand
public bool RunCommand(string name, Action<World> run)Runs a plugin's command called name — a Tools item's, or a window's (Command); one that throws is said in the logs. Engine thread.
Parameters
namerun
Returns Whether it ran through.
RunComponentItem
public (byte[] Before, byte[] After)? RunComponentItem(EditorMenuItem item, ulong entity)Has a plugin's item change the component it is on the menu of, on entity: the component's bytes before and after, for the step of the undo; null where it is no component's item, or it threw, which is said in the logs and leaves the component as it was. Engine thread.
Parameters
itementity
Exceptions
AbyssException: The entity is gone, or does not carry the component.
DrawEditorWindow
public bool DrawEditorWindow(EditorWindowItem window, EditorUi ui, byte[] state)Draws a plugin's window with ui, its state the bytes of state, which are left as its state is after. One that throws is said in the logs, once until it draws again. Engine thread, while the editor's panels are drawn.
Parameters
windowuistate
Returns Whether it drew through; false where it threw.
Exceptions
ArgumentException:stateis not as long as its state.
RegisterWindowState<T>
public ComponentType<T> RegisterWindowState<T>(ReadOnlySpan<ComponentFieldSpec> fields, ReadOnlySpan<FieldHint> hints, string name, in T start) where T : unmanagedRegisters a window's state struct: as a component nothing carries, so its fields are described and shown as a component's are. What the generator behind WindowStateAttribute calls; a game's or a package's registration calls that.
Type parameters
T: The struct.
Parameters
fields: Where its fields are, measured.hints: What its fields' attributes say of showing them.name: Its full name, which its component is registered by.start: What it starts as.
Returns The struct, as a component of this world.
The same struct again is the registration it had.
EditorWindowStateOf
public SettingsType? EditorWindowStateOf(ComponentId component)A window's state struct, described: its fields, how to show them and what it starts as, kept as a project's settings are (ProjectSettingsFile); null where component is none.
Parameters
component
Repoint
public int Repoint(IReadOnlyList<(ulong Was, ulong Is)> back, IReadOnlyCollection<ulong>? within = null)Points every EntityRef naming an entity that came back as another at the one it is now: what Stop and an undo putting back what was deleted do with what came back, since a C# component comes back as its bytes, the numbers in it as they were. A Rust component's field naming an entity (abyss_core::hint::EntitySlot) is pointed as a C# one's is.
Parameters
back: Each entity that came back, as its old number and its new one.within: Only the fields of these entities, or every entity's for null: the copies a duplicate made, which name each other where the originals did, while what names an original still does.
Returns How many fields it pointed elsewhere.
ReadFile
public byte[] ReadFile(FileRef file)The file file names, as it is: from the pack the game plays from, which carries every file a scene's reference reaches, or from the project's folders while the game is edited or played from them. Read again each time it is asked for; what is made of it is the asker's to keep.
Parameters
file
Exceptions
KeyNotFoundException: It names nothing, or nothing the game has.
Safe from any system, parallel ones included: a read is made under the world's assets.
SaveAssetFile
public FileRef SaveAssetFile(string path, ReadOnlySpan<byte> bytes)Writes bytes to the file path under the project's assets, its folders made where they are not there, and gives a reference to it: what a plugin bakes in the editor, a navmesh beside its scene. The file keeps its identity when it is written again.
Parameters
path: Where, relative to the assets, with forward slashes:scenes/Level1/Ground.abynav.bytes: What it holds.
Exceptions
InvalidOperationException: No project is open, whose assets it would be among.ArgumentException: The path leaves the assets.
The project is scanned again, so the new file has its identity at once. Engine thread.
TryReadFile
public bool TryReadFile(FileRef file, out byte[] bytes)The file file names, as World.ReadFile reads it; false where it names nothing the game has.
Parameters
filebytes
SetFog
public void SetFog(ulong camera, CameraFog? fog)Fogs a camera of the game's — a scene's camera — as fog says, or clears it of fog for null. Writes nothing where it is fogged so already, so it may be asked every frame: a fog that turns blue as the camera goes under water, say.
Parameters
camerafog
Exceptions
AbyssException:AbyssStatus.InvalidFogfor an entity that is no camera, or a fog that fogs nothing: a linear one whose end is not past its start or that starts behind the camera, a density not more than nothing, or a number that is not one.
FogOf
public CameraFog? FogOf(ulong camera)How a camera of the game's is fogged; null where it is not.
Parameters
camera
Exceptions
AbyssException:AbyssStatus.InvalidFogfor an entity that is no camera.
StepAsync
public void StepAsync(float delta, bool paused = false)Moves a game's async code along, once a frame on the engine thread before the systems run: what it waits for that is over let go of, and what follows an await whose task has finished run. Its waits for frames and for seconds stand still while paused.
Parameters
delta: The game's time the frame takes, in seconds.paused: Whether the game is paused.
GameGizmos
public int GameGizmos(ref GizmoSegment[]? buffer)The lines a game's Rust last drew with Bevy's Gizmos, for the editor's Scene panel to draw. Written into buffer, which is made bigger when it is too small, so a caller asking every frame asks once a frame.
Parameters
buffer: Where the lines are written; null is a buffer of none.
Returns How many lines there are, from the start of buffer.
See abyss_core::game_gizmos: a group switched off draws nothing, and while the game is paused what it drew last is kept.
Select
public int Select(ReadOnlySpan<ulong> picked, Span<ulong> kept)Says which entities the editor has picked, for a game's systems to read: its Rust as the resource EditorSelection, its C# as World.Selection. Those that are not in the world are left out, and each is said once.
Parameters
picked: The entities picked, packed as the engine packs them, in the order they were picked.kept: Where those that are picked go: those in the world, each once, in that order. As long aspickedat least.
Returns How many of them are picked, from the start of kept.
Exceptions
ArgumentException:keptis shorter thanpicked.AbyssException: One of them is not an entity's bits at all; nothing is said then.
SetUiReference
public void SetUiReference(float width, float height, float matchHeight = 1, bool scaled = true)Lays the game's interface out for a screen width by height pixels big, and scales it with the screen it is drawn to from there: matching its width at matchHeight zero, its height at one, and between them between.
Parameters
width: The reference screen's width.height: The reference screen's height.matchHeight: Zero to one.scaled: Whether it is scaled at all; off, it is drawn at the window's own scale.
UiDropdownOptions
public string[] UiDropdownOptions(ulong entity)The words of each of a dropdown's options, in order: what an inspector lists its Picked from.
Parameters
entity
Exceptions
AbyssException: The entity is gone, or is no dropdown.
ReloadStyleSheet
public void ReloadStyleSheet(string path)Reads the stylesheet at path, under the assets folder, again, and restyles each document it styles: what the editor does as one is saved.
Parameters
path
SceneMarkers
public SceneMarker[] SceneMarkers()Every light and camera the editor's Scene panel marks, by entity, a light before a camera on one that is both.
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
Not the engine's own camera and light, nor anything hidden or switched off. See abyss_core::gizmo.
SceneBones
public SceneBone[] SceneBones()Every joint of every skin the editor's Scene panel draws the bones of, each once, however many skins share it, by entity.
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
Not the engine's own skins, nor one hidden or switched off. See abyss_core::gizmo.
Outline
public int Outline(ReadOnlySpan<ulong> picked, in Lens lens, ref OutlineEdge[]? buffer)The outline of what picked draws, and of what is under it, seen through lens: round the shape each group makes on the screen, through whatever is in front of it. Written into buffer, which is made bigger when it is too small, so a caller asking every frame asks once a frame.
Parameters
picked: The entities picked, packed as the engine packs them.lens: How the view they are outlined in sees.buffer: Where the edges are written; null is a buffer of none.
Returns How many edges there are, from the start of buffer.
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
What is under what is picked is every entity below it that is not picked itself, whose edges say so (OutlineEdge.Child) to be drawn in a second color. What is not drawn is not outlined. See abyss_core::gizmo.
UseLayers
public void UseLayers(LayerSettings settings)The project's layers by name: what World.Layers says from now on. What the editor tells the world as Project Settings changes them, and a game as it starts.
Parameters
settings
LayerOf
public int LayerOf(ulong entity)The layer an entity is on: Default, 0, for one that says none.
Parameters
entity
Exceptions
AbyssException: The entity is gone.
SetLayer
public bool SetLayer(ulong entity, int layer)Puts an entity on layer layer, of the project's 32: what it is drawn on, as a camera's culling mask draws it. Default, 0, is where an entity is until it says otherwise, and one put back on it says nothing again, so a scene does not keep it.
Parameters
entitylayer
Returns Whether that changed anything: false when it was on it already.
Exceptions
ArgumentOutOfRangeException: The number is not one of the 32.AbyssException: The entity is gone.
CullingMaskOf
public LayerMask CullingMaskOf(ulong camera)The layers a camera draws: every one unless it says otherwise.
Parameters
camera
Exceptions
AbyssException: The entity is gone.
SetCullingMask
public bool SetCullingMask(ulong camera, LayerMask mask)Has a camera draw the layers of mask, and no other.
Parameters
cameramask
Returns Whether that changed anything.
Exceptions
AbyssException: The entity is gone.
SetLight
public void SetLight(ulong light, Vector3 color, float intensity)Gives a light of the game's — a scene's directional, point or spot light — the color (sRGB) and intensity asked. Writes nothing where it is so already, so it may be asked every frame: a sun going down, say.
Parameters
lightcolorintensity
Exceptions
AbyssException:AbyssStatus.InvalidLightfor an entity that is no light, an intensity less than nothing, or a number that is not one.
LightOf
public SceneLight LightOf(ulong light)A light's kind, color and strength.
Parameters
light
Exceptions
AbyssException:AbyssStatus.InvalidLightfor an entity that is no light.
SetAmbientLight
public void SetAmbientLight(ulong camera, AmbientLighting? ambient)Lights what a camera of the game's sees by ambient, or by the world's ambient light again for null. Writes nothing where it is so already, so it may be asked every frame: a night darkening, say.
Parameters
cameraambient
Exceptions
AbyssException:AbyssStatus.InvalidLightfor an entity that is no camera, a brightness less than nothing, or a number that is not one.
AmbientLightOf
public AmbientLighting? AmbientLightOf(ulong camera)The ambient light a camera of the game's sees by as its own; null where it sees by the world's.
Parameters
camera
Exceptions
AbyssException:AbyssStatus.InvalidLightfor an entity that is no camera.
LinePointsOf
public static List<Vector3>? LinePointsOf(ReadOnlySpan<byte> json)A Line's points as their JSON's UTF-8 says them, each [x, y, z]; null for anything else.
Parameters
json
LinePointsWritten
public static string LinePointsWritten(IEnumerable<Vector3> points)A Line's points written as the engine reads its points choice: [[x, y, z], …].
Parameters
points
RegisterList<T>
public ListType<T> RegisterList<T>(ReadOnlySpan<ComponentFieldSpec> fields, ReadOnlySpan<FieldHint> hints, string? name, in T start) where T : unmanagedRegisters a list component whose items are T, with where its fields are and how to show them, as RegisterComponent<T> registers a component; start is what a new item starts as. The generator behind AbyssListAttribute calls this.
Type parameters
T: The plain-data struct one item is.
Parameters
fields: Where an item's fields are.hints: How to show them.name: The name the engine knows it by; defaults to the type's.start: A new item, as it starts.
Exceptions
ArgumentException: A hint does not fit the fields.AbyssException: The fields do not fit an item, or the item has no size.
List<T>
public ListType<T> List<T>() where T : unmanagedThe list component T is the item of, as it was registered here.
Type parameters
T
Exceptions
InvalidOperationException: Nothing has registered it in this world.
IsList
public bool IsList(ComponentId component)Whether a component is a list.
Parameters
component
ListOf<T>
public DynamicList<T> ListOf<T>(ulong entity) where T : unmanagedAn entity's list of T, to read and write in place, and marked changed. Valid until the world's next structural change; see DynamicList<T>.
Type parameters
T
Parameters
entity
Exceptions
InvalidOperationException: Nothing has registeredTas a list's item.AbyssException: The entity is gone, or carries no such list.
ListLayoutOf
public ListLayout? ListLayoutOf(ComponentId component)What one item of a list component is; null for one that is no list.
Parameters
component
ListCount
public int ListCount(ulong entity, ComponentId list)How many items an entity's list holds.
Parameters
entitylist
Exceptions
AbyssException: The entity is gone, or the component is no list it carries.
ReadList
public byte[] ReadList(ulong entity, ComponentId list)A copy of an entity's list's items, as bytes: ListLayout.ItemSize of them to an item.
Parameters
entitylist
Exceptions
AbyssException: The entity is gone, or the component is no list it carries.
WriteList
public void WriteList(ulong entity, ComponentId list, int offset, ReadOnlySpan<byte> bytes)Writes bytes into an entity's list's items, offset bytes in, and marks it changed.
Parameters
entitylistoffsetbytes
Exceptions
AbyssException: The write reaches past the items the list holds, the entity is gone, or the component is no list it carries.
SetList
public void SetList(ulong entity, ComponentId list, ReadOnlySpan<byte> bytes)Gives an entity's list bytes as its items, in place of what it held.
Parameters
entitylistbytes
Exceptions
AbyssException: The bytes are not whole items, the entity is gone, or the component is no list it carries.
SetList<T>
public void SetList<T>(ulong entity, ListType<T> list, ReadOnlySpan<T> items) where T : unmanagedGives an entity's list items, in place of what it held.
Type parameters
T
Parameters
entitylistitems
Exceptions
AbyssException: The entity is gone, or carries no such list.
ResizeList
public void ResizeList(ulong entity, ComponentId list, int count)Makes an entity's list hold count items: those past it let go of, and each new one a copy of the last it held, or a new item as its declaration starts one where it held none. What the Inspector's size does.
Parameters
entitylistcount
Exceptions
AbyssException: The entity is gone, or the component is no list it carries.
UseLocalized
public void UseLocalized(IReadOnlyList<(string Path, AssetGuid Id, LocalizedAsset Asset)> assets)Uses the project's localized assets, each by its path and identity: what the editor does, and a game played from its folders; a built game reads its packs'. Each is shown in the file its language is, at once; one no longer given shows its default.
Parameters
assets
LocalizedFileOf
public string? LocalizedFileOf(string path)The file the localized asset at path shows now; null where none is known by it.
Parameters
path
ReloadMaterial
public MaterialId? ReloadMaterial(string path)Reads a material file again, if it has been read, and returns the material it is now; null for a file not read, which is left to be read when something asks for it.
Parameters
path: Relative to the asset root.
Exceptions
AbyssException: The file cannot be read, or says what cannot be.
What the editor does when a material file is saved. The material changes where it is, so everything drawn with it is drawn with what the file says now; what the file no longer says starts as its shader says. A file that cannot be read leaves the material as it was.
A file that changes between Bevy's own surface and a game's shader is a new material: the two are two kinds of material, and an id says which. Everything drawn with the old one is drawn with the new one, the path is the new one's, and the world lets go of the old one, which goes once nothing else holds it. From one shader to another, the id is kept.
MaterialFileText
public string MaterialFileText(MaterialId material)A material as a material file says it, to be written to one.
Parameters
material
Exceptions
AbyssException: No material has that id, or a model's has not arrived yet;World.StateOfsays when it has.
Its shader, every value it holds now, and the images its slots hold by their paths. For one read out of a material file, what that file said that the shader does not take is kept; for any other — a model's, or one made in code — it is what a new file for it would say. An image made from pixels has no path, and its slot is written empty.
UseAssetIndex
public void UseAssetIndex(AssetDatabase assets, AssetDatabase? shaders = null)Tells the engine every file's identity and where it is now, replacing what it was told before: what a material file's references by identity are found through.
Parameters
assets: The asset root's files.shaders: The game's shaders folder's files, or null for none.
Exceptions
AbyssException: The world has been disposed of.
Told again whenever either database is read again, so a file moved or renamed is found where it is now. A game's shaders are named as a material file names them, under shaders/.
UseAssetIndex
public void UseAssetIndex(IEnumerable<(string Path, AssetGuid Id)> assets, IEnumerable<(string Path, AssetGuid Id)>? shaders = null)Tells the engine every file's identity and where it is now, from lists of them: what the editor hands the world's thread, read while its databases may be read again on its own.
Parameters
assets: The asset root's files, by their paths under it.shaders: The game's shaders folder's files, by their paths in it, a package's after its id, or null for none.
Exceptions
AbyssException: The world has been disposed of.
UseImportedModel
public void UseImportedModel(string path, string artifact)Says the model at path has been imported into artifact: every mesh of it is read out of the import, on the engine's IO threads, and each already asked for is too, in place, under the id it has; and its materials are what the import says, at the next tick. A model is never read from its source, so one asked for before its import is told of draws nothing until then.
Parameters
path: The model, by its path under the asset root: the file, with no mesh named in it.artifact: The import, its whole path.
Exceptions
AbyssException: The path names a mesh rather than a file, or the import's tables cannot be read; the path goes on waiting for one that can be.
NoteInEditor
public string NoteInEditor(ulong entity, ComponentId component)What the plugins have the Inspector say under component on entity (Schedule.NoteInEditor), each a line; empty for nothing. What the editor asks as it reads an entity. Engine thread.
Parameters
entitycomponent
PutPackage
public void PutPackage(string id, string folder)Says the package id is folder, which holds its own assets and shaders, so a path in it — acme.physics://models/rock.glb — is read from there from now on, in place of any folder it was.
Parameters
idfolder
Exceptions
AbyssException: The id is not a package's; seePackagePath.IsId.
TakeOutPackage
public bool TakeOutPackage(string id)Takes the package id out, so nothing more is read from it, and says whether there was one; what was read from it already stays.
Parameters
id
AssetFileOf
public string? AssetFileOf(string path)The file on disk an asset path names: under World.AssetRoot, or under its package's assets; null for a world with no asset root, or a path in a package it has not.
Parameters
path
ShaderFileOf
public string? ShaderFileOf(string path)The file on disk a shader's path names: under the shaders folder beside World.AssetRoot, or under its package's shaders; null as for World.AssetFileOf.
Parameters
path
MountPack
public int MountPack(string path)Mounts the pack at path over any mounted already, so every load looks in it before the world's folder — an image, a model's meshes, a material, a shader, and a scene the SceneLoader loads — and says how many entries it holds.
Parameters
path
Exceptions
AbyssException: The file is not a pack this build reads.
What a built game does as it starts, with Pack.Main beside its executable. Every identity the pack holds is known as an index says it, and a game's shaders are drawn from their compiled variants, as there is no text in a pack to draw them from.
UnmountPack
public bool UnmountPack(string path)Takes away the pack mounted from path — the last mounted, if it was mounted twice — and its catalog with it, and says whether one was: what a game does with a pack it no longer needs, a level it has left.
Parameters
path
What was loaded from it stays loaded; what is loaded after is looked for in the packs left, and the folder.
Packed
public (Pack Pack, PackEntryKind Kind)? Packed(string name)What the mounted packs hold under a path, from the last mounted that holds it: the pack, and what it holds.
Parameters
name
PackMaterial
public byte[] PackMaterial(string path)The .abymat the material file at path packs into, every file it names by its identity.
Parameters
path
Exceptions
AbyssException: The file, or its shader, cannot be read, or names a file the index does not know.
PackedShaderLayout
public byte[] PackedShaderLayout(ShaderId shader)What a pack holds of a game's shader as its part 0: its layout, with what each value starts as.
Parameters
shader
Exceptions
AbyssException: The id names no shader.
Placements
public HandlePlacement[] Placements(ReadOnlySpan<ulong> picked)Each of picked that the editor's move, rotate and scale handles can move, in the order given and once each: what it takes to draw a handle where it goes and to move each by what it did. Not the engine's own camera and light, nor an entity with no transform or that is not there. See abyss_core::handle.
Parameters
picked
SetTransforms
public void SetTransforms(ReadOnlySpan<Placed> moves)Gives each entity its transform, and works out at once where it and what is under it are in the world, as Bevy's propagation will after the frame's own work: so what is drawn over the scene this frame, the outline of what is picked, is where the scene is drawn. All of them or none. See abyss_core::handle.
Parameters
moves
Exceptions
AbyssException:AbyssStatus.EntityNotFoundfor an entity that is not there,AbyssStatus.ComponentNotPresentfor one with no transform, andAbyssStatus.InvalidPlacementfor the engine's own or a transform with a number that is not one. Nothing is written then.
RestartGame
public void RestartGame()Makes the next frame the game plays its first again: its startup systems run before it, as they did before its first, and Bevy's clock, which its Rust systems read, starts again from zero. What an editor does at every Play. What always runs is not started again; it has been running all along.
StepGame
public void StepGame()Lets the game have the whole of the next frame, and holds it again at the start of the one after: what an editor's Step does. World.GameMode says GameMode.Playing for that frame and GameMode.Paused from the next.
The whole of a frame from its start, so Bevy's clock moves on by that frame, as it would had the game been playing: held while the game is paused, it cannot be let go of halfway through a frame it has already been read in. Setting World.GameMode forgets a step not yet taken.
Snapshot
public WorldSnapshot Snapshot(ReadOnlySpan<ulong> except = null)Keeps what every entity holds, to be put back with WorldSnapshot.Restore.
Parameters
except: Entities to leave out, and alone when it is put back: what the caller drives itself, such as an editor's camera. The engine's own entities — windows, observers — are always left alone.
Exceptions
AbyssException: An id inexceptis not one.
UseInputActions
public void UseInputActions(InputActions actions)Uses actions from the next frame — what the editor tells the world as a game plays, and a game as it starts — every player starting again: its maps on as the actions say, nothing held, and its own bindings as the player's folder keeps them, where there is one.
Parameters
actions
Exceptions
AbyssException: The engine cannot use them, saying why; it keeps the ones it had.
ChangeInputActions
public void ChangeInputActions(InputActions actions)Changes to actions from the next frame as the game plays — what the editor tells the world as its Input page changes them — each player keeping the maps it has on, what it holds and its own bindings that still fit, by their identities; a map or action new to them starts as they say.
Parameters
actions
Exceptions
AbyssException: The engine cannot use them, saying why; it keeps the ones it had.
SetGameInput
public void SetGameInput(GameInput input)Says what of the devices the game has and where its picture is: what the editor says each frame — the keyboard and mouse only while its Game panel has focus — and a game on its own never does, having all of them in its window.
Parameters
input
Exceptions
AbyssException: The picture's window is none of the engine's.
ListenForInput
public void ListenForInput(bool on, MouseButtons? mouse = null)Starts listening for the next key, gamepad button, stick pushed past halfway or mouse button of mouse — every one where it says nothing — or stops; see World.HeardInput.
Parameters
onmouse
Heard whatever the game has of the devices, and only what goes down after it begins: not a key already held, and not the click that began it. The editor's Input page hears the middle and side buttons alone, as its own clicks, left and right, are what stop it listening.
InputOf
public PlayerInput InputOf(int player)A player's input actions, to ask about each frame; see PlayerInput.
Parameters
player: Which player, from zero to belowWorld.MaxPlayers.
SimulateKey
public void SimulateKey(Key key, bool down)Writes a key going down or up, as a keyboard would: read on the next frame. For a test of a game's input.
Parameters
keydown
SimulateMouseButton
public void SimulateMouseButton(MouseButtons button, bool down)Writes a mouse button going down or up.
Parameters
buttondown
Exceptions
AbyssException:buttonis not one button.
SimulateMouseMotion
public void SimulateMouseMotion(float x, float y)Writes the mouse moving by x and y pixels, down positive as the screen's are.
Parameters
xy
SimulateScroll
public void SimulateScroll(float x, float y)Writes the mouse's wheel turning by x and y lines.
Parameters
xy
SimulateGamepad
public SimulatedGamepad SimulateGamepad(ushort vendor = 0)Connects a gamepad that is not there, a pad from the next frame.
Parameters
vendor: Its maker's number, as USB numbers them — 0x054C for one of Sony's — or zero for none.
SetBloom
public void SetBloom(ulong camera, CameraBloom? bloom)Gives a camera of the game's the bloom bloom says, drawing it in HDR, or takes its bloom away for null (it goes on drawing in HDR). Writes nothing where it has that bloom already, so it may be asked every frame.
Parameters
camerabloom
Exceptions
AbyssException:AbyssStatus.InvalidCameraEffectfor an entity that is no camera, a strength, boost or threshold below nothing, a high pass or softness outside 0 to 1, a composite there is none of, a largest picture of no pixels, a spread of nothing, or a number that is not one.
BloomOf
public CameraBloom? BloomOf(ulong camera)A camera of the game's bloom; null where it has none.
Parameters
camera
Exceptions
AbyssException:AbyssStatus.InvalidCameraEffectfor an entity that is no camera.
SetDepthOfField
public void SetDepthOfField(ulong camera, CameraDepthOfField? depth)Gives a camera of the game's the depth of field depth says, or takes it away for null. Writes nothing where it has that depth of field already, so it may be asked every frame: focused on what the player looks at, say.
Parameters
cameradepth
Exceptions
AbyssException:AbyssStatus.InvalidCameraEffectfor an entity that is no camera, a mode there is none of, a focal distance, sensor, f-number or farthest depth of nothing or less, a widest blur below nothing, or a number that is not one but the farthest depth's infinity.
DepthOfFieldOf
public CameraDepthOfField? DepthOfFieldOf(ulong camera)A camera of the game's depth of field; null where it has none.
Parameters
camera
Exceptions
AbyssException:AbyssStatus.InvalidCameraEffectfor an entity that is no camera.
LoadPrefab
public PrefabId LoadPrefab(string path)Starts loading a prefab to make instances of: a .prefab under the assets, or a model — models/pyramid.gltf — whose prefab its import made. Read off the frame, with the meshes, materials and images it is drawn with, so an instance made of it is drawn whole from its first frame.
Parameters
path: The prefab or the model, under the assets.
The same prefab again is the same id, held once more, as a mesh's path is: each load is given back with World.Release, and the prefab and what it is drawn with go once the last load is, and the last instance waiting for it is built. World.StateOf says how far it is.
From the pack a built game plays from when one holds it, and from the folders beside it otherwise — a model's prefab from the editor's cache.
LoadPrefab
public PrefabId LoadPrefab(AssetGuid prefab)Starts loading a prefab by its identity, which finds it wherever it has been moved. See World.LoadPrefab.
Parameters
prefab: The prefab's or the model's identity.
LoadPrefab
public PrefabId LoadPrefab(PrefabRef prefab)Starts loading the prefab a component names. See World.LoadPrefab.
Parameters
prefab: What the component holds: a prefab's or a model's identity.
Exceptions
ArgumentException: It names no prefab.
LoadPrefabs
public IReadOnlyList<PrefabId> LoadPrefabs(string label)Starts loading every addressable prefab and model with a label — in order of their paths — each held as World.LoadPrefab holds one, and each given back with World.Release.
Parameters
label: The label, matched exactly.
Returns The prefabs, none for a label no prefab has.
A label is given in a file's inspector, under its address; what else has the label — a texture, a material — is not a prefab, and is left out.
LoadPrefabs
public IReadOnlyList<PrefabId> LoadPrefabs(LabelName label)Starts loading every addressable prefab and model carrying a label, by the name the build wrote for it — Labels.Enemies; see World.LoadPrefabs.
Parameters
label: The label.
LoadPrefab
public PrefabId LoadPrefab(PrefabAddress prefab)Starts loading a prefab or a model by its key — Addresses.Pyramid — found by its identity wherever it is, then by its address; see World.LoadPrefab.
Parameters
prefab: The key the build wrote for an addressable prefab or model.
StateOf
public AssetState StateOf(PrefabId prefab)How far a prefab's load is: AssetState.Loading until it and what it is drawn with are here, AssetState.Loaded, AssetState.Failed when it cannot be read — the log says why — and AssetState.Unloaded once every load of it is given back.
Parameters
prefab
Release
public void Release(PrefabId prefab)Gives back one load of a prefab. With the last — and once every instance waiting for it is built — the prefab goes, and what it is drawn with goes as the instances made of it do.
Parameters
prefab
Exceptions
InvalidOperationException: Every load of it was given back already, or it was never loaded.
Instantiate
public ulong Instantiate(PrefabId prefab, Vector3 position, Quaternion rotation, ulong parent = 0, SceneId scene = default)Makes an instance of a prefab now, between frames, 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. A prefab still loading is made once it has loaded, and the entity is there from then.
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.
What a system does is CommandBuffer.Instantiate; this is for what runs between frames, where the world is the caller's alone. Despawning the entity it gives despawns all of the instance.
Prepare
public ulong Prepare(ReadOnlySpan<(MeshId Mesh, MaterialId Material)> draws, ReadOnlySpan<ulong> instances)Starts preparing what the game will draw: each mesh with its material, and each of instances, the top of a prefab's instance, drawn once where nobody sees it so what the GPU compiles to draw them is compiled before they are first seen. Gives the batch, which World.IsPrepared asks after. The instances are the engine's from then on, and despawned with what the meshes were drawn on once the batch is done. What a game awaits is Prepare.
Parameters
draws: Each mesh, with the material it is drawn with.instances: The top of each instance.
Exceptions
AbyssException: A mesh or a material is unknown, or an instance is not there; nothing is started then.
IsPrepared
public bool IsPrepared(ulong batch)Whether batch batch of Prepare is done; true for one never begun.
Parameters
batch
RegisterSettings<T>
public ResourceType<T> RegisterSettings<T>(ReadOnlySpan<ComponentFieldSpec> fields, ReadOnlySpan<FieldHint> hints, string name, string title, string file, in T start) where T : unmanagedRegisters a project's settings struct: as a component nothing carries, so its fields are described and shown as a component's are, and as the resource T, which it is from now on what it starts as. What the generator behind ProjectSettingsAttribute calls; a game's or a package's registration calls that.
Type parameters
T: The struct.
Parameters
fields: Where its fields are, measured.hints: What its fields' attributes say of showing them.name: Its full name, which its component is registered by.title: Its page's name in Project Settings.file: Its file undersettings, without.json.start: What it starts as.
Returns The resource it is, which World.Resource finds too.
Exceptions
ArgumentException: The title or the file is the engine's, or no file's name.InvalidOperationException: Other settings have the title or the file already.
The same struct again is the registration it had. The same struct built again — a game's or a package's scripts rebuilt, its full name the same — takes its place, whether or not World.ForgetTypesFrom let go of the one it replaces.
SettingsTypes
public IReadOnlyList<SettingsType> SettingsTypes()The project's settings declared in code, described for an editor, in the order of their titles.
UseSettings
public IReadOnlyList<string> UseSettings(string file, string? json)Makes the settings kept in file what their file's text says: what the project's file says as a game starts, and as the editor changes it.
Parameters
file: The settings' file undersettings, without.json.json: The file's text, or null for none, which is what they start as.
Returns What could not be read, to be said; empty where all of it could.
Exceptions
KeyNotFoundException: No settings are kept in that file.
SettingsBytes
public byte[] SettingsBytes(string file)The bytes the settings kept in file are now, as a game may have changed them.
Parameters
file
Exceptions
KeyNotFoundException: No settings are kept in that file.
Settings<T>
public ref T Settings<T>() where T : unmanagedThe project's settings T as they are now, to read and to change for this run: outside a system, where a system takes Res<T> or ResMut<T>.
Type parameters
T
Exceptions
InvalidOperationException:Tis no settings registered in this world.
CastRay
public RayHit[] CastRay(Vector3 origin, Vector3 direction)The entities whose drawn meshes and sprites a ray passes through, each once, what is drawn over the rest first: what a click in the editor's Scene panel picks from.
Parameters
origin: Where the ray starts, in world space.direction: Which way it goes, of any length.
What is drawn is what can be hit: a hidden or disabled entity, a mesh on a layer the engine's camera does not see, a side of a surface its material does not draw, and where a sprite's image is clear are passed through. Sprites are drawn over everything 3D, so they come first, the one furthest along +Z first, as it is drawn over the others; then meshes, nearest first. See abyss_core::pick. A direction with no length hits nothing.
SeenIn
public ulong[] SeenIn(in Lens lens, Vector2 from, Vector2 to)The entities seen in the rectangle from from to to of the view lens sees, each once, in no order: what a rectangle dragged in the editor's Scene panel picks from.
Parameters
lens: How the view sees.from: One corner of the rectangle, from the view's top-left corner, in the lens's units.to: The opposite corner.
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
An entity is seen where a pixel the rectangle covers shows it, nearer than anything else drawn there; a part of it is enough, and what is hidden behind something else is not seen. What is drawn is what a ray can hit (see World.CastRay), and nothing else hides anything; a sprite hides what it is drawn over, as a ray finds it first. See abyss_core::seen.
MoveComponent
public ComponentMove MoveComponent(ComponentId from, ComponentId to)Moves every entity's from onto to, field by field by name, and takes from off.
Parameters
fromto
Exceptions
AbyssException:AbyssStatus.ComponentNotPlainDataunless both were declared from C#.
What becomes of a game's component when the game's C# is built again with the editor open: what its fields held before the build is put back after it, by the fields' names. A field of the same kind is copied; one of another kind now is converted as writing its number from the inspector would convert it; one the new component lacks is dropped and named in ComponentMove.Dropped; one only the new component has starts as a new one does, as its declaration's initializer says (World.StartOf), else at zero. So a component kept from a scene while nothing declared it, which holds only what the file wrote, has what the file left out as a load would give it.
Or by the name a field had before, where its own is gone: what to's fields say they were called, from FormerlySerializedAsAttribute and kept with its hints, is worked out here and handed to the engine, and a value under an old name goes to the field that has it now (ComponentMove.Renamed). A name still there comes first; see the attribute.
Every entity that carries it, switched off or not. A structural change, so chunks resolved before it are stale.
StripComponent
public int StripComponent(ComponentId component)Takes a component declared from C# off every entity that carries it, switched off or not.
Parameters
component
Returns How many entities carried it.
Exceptions
AbyssException:AbyssStatus.ComponentNotPlainDataunless it was declared from C#.
Its values go with it, and its name finds nothing afterwards. What became of a game's component the rebuilt game no longer declared, before one was kept instead (World.KeepMissing). A structural change when it took anything, so chunks resolved before it are stale.
KeepMissing
public int KeepMissing(ComponentId component)Keeps a component declared from C# on every entity that carries it, with what it holds, once no code declares it.
Parameters
component
Returns How many entities carry it.
Exceptions
AbyssException:AbyssStatus.ComponentNotPlainDataunless it was declared from C#.
Its name finds nothing afterwards (World.ComponentByName), and the list a component is added from leaves it out: no code declares it. It is still called what it was (World.NameOf), a scene writes it by that name with what it holds, and one opened while it is kept puts what it names back into it (World.MissingNamed). Once a component is declared by that name again, or says it was called that, World.MoveComponent carries its values over and it is no longer missing.
KeepMissing
public ComponentId KeepMissing(string name, IReadOnlyList<(string Name, int Count, bool Text)> fields)Makes a component to keep what a scene says of one that no code declares, and keeps it missing, as World.KeepMissing keeps one a rebuild left behind.
Parameters
name: What the scene calls it.fields: Each field the scene gives it, by name, with how many values it holds, or whether it is a text.
Returns The component, carried by nothing yet.
Every value a scene holds for a component declared from C# is a number or a text, so each field is made a double, of as many as the scene holds, which holds any of them exactly but a 64-bit whole number past 2^53; or a SharedText, for a text. Once a component of the name is declared, World.MoveComponent carries each field onto it by its name, converted to what it is declared as, a text onto a fixed text's room or a shared text, and one the scene did not name starts as it would have, at zero: a field the scene left out was at zero when it was written.
For a component whose values are all numbers. One holding an enum is not made; see SceneField.Choice.
MissingNamed
public ComponentId? MissingNamed(string name)The component kept for a name no code declares any more, or null if there is none.
Parameters
name: What it was called.
The latest, where more than one is kept by one name.
IsMissing
public bool IsMissing(ComponentId component)Whether a component is one no code declares any more; see World.KeepMissing.
Parameters
component
ForgetTypesFrom
public int ForgetTypesFrom(Assembly assembly)Lets go of every type from assembly that registered a component here, so that the assembly can be unloaded.
Parameters
assembly
Returns How many types it let go of.
The components stay registered — a world cannot take a registration back — and World.Component no longer finds them by those types; the project's settings it declared and the resources its plugins registered are let go of, their values taken out with the entities they were held on. What loading a game's rebuilt assembly does to the one it replaces.
AdoptTypes
public int AdoptTypes(Assembly old, Func<Type, Type?> twinOf)Hands everything old's types registered here to their twins, as twinOf names them: the types of the same build loaded again. Each component, resource, animation event, project's settings and kind of data asset is found by its twin from then on, under the registration it had; and old's services are taken away and disposed.
Parameters
old: The load whose types registered what is handed across.twinOf: A type's twin in the new load — of the same full name, and a generic made of twins where it was made ofold's types — or null where the new load has none. Asked of every type that registered something here and isold's or made of its.
Returns How many types were handed across.
Exceptions
ArgumentException: A type has no twin; nothing is handed across then.
What the editor does at every Play: it loads the game's scripts afresh, so their static fields start as they do in a game on its own, where a game played again would otherwise start with what its last play left in them. Registering the fresh load's types again would add a component of each kind at every Play, which a world never takes back, and move every value across; handed across, nothing is registered and nothing moves.
Only the same build: two loads of one compilation, of one Module.ModuleVersionId, whose types are laid out alike, which is the caller's to be sure of. A rebuilt game's types are registered afresh and their values moved; see World.MoveComponent and World.ForgetTypesFrom.
SetSceneDraw
public SceneDraw SetSceneDraw(SceneDraw draw)Has the Scene panel's camera draw the scene as draw says, and says how it is drawn: as asked, or shaded where the GPU draws no lines, before the renderer has its device, and in a world with no renderer.
Parameters
draw
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
Asked again the same, the world writes nothing, so the editor asks at every frame: a draw asked for before the renderer had its device is drawn once it has. See abyss_core::scene_draw.
SetSceneGrid
public void SetSceneGrid(bool shown, bool upright)Has the Scene panel draw its grid, or not: lines across the ground a unit apart, every tenth stronger, fading out, at a tenth, ten or a hundred units apart as the camera is closer to or further from the ground, hidden by what stands on it; upright on the XY plane for the 2D view.
Parameters
shown: Whether it is drawn.upright: Whether it stands on the XY plane, for the 2D view, rather than lies on the ground.
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
Seen by the Scene panel's camera alone, never a game's, and made the first time it is asked for; asked again the same, the world writes nothing, so the editor asks at every frame. Nothing in a world with no renderer. See abyss_core::scene_grid.
DrawInScene
public void DrawInScene(string name, ReadOnlySpan<Vector3> triangles, Vector4 fill, ReadOnlySpan<Vector3> lines, Vector4 lineColor)Draws triangles — three corners each — in fill, and lines — two corners each — in lineColor, in the Scene panel under name, replacing what was drawn under it: what a plugin shows of what it works out, a navmesh's floor and its edges.
Parameters
nametrianglesfilllineslineColor
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
In the world, as the grid is: hidden by what is in front of it, unlit and blended, the triangles drawn a little toward the camera so a floor drawn on the scene's floor shows over it; lines are not, so lift them where they lie on something. Colors are sRGB, red, green, blue and alpha, as the editor's interface draws in.
The engine's: seen by the Scene panel's camera alone, never a game's, never saved with a scene, put back by Stop, picked or listed. Corners past the last whole triangle or line are left out. Nothing in a world with no renderer. See abyss_core::scene_drawing. Engine thread.
Gone with the scripts that drew it: letting go of a game's scripts, or loading them again, takes away everything drawn, as the plugins built again draw what they show anew.
DrawInScene2D
public void DrawInScene2D(string name, ReadOnlySpan<Vector2> triangles, Vector4 fill, ReadOnlySpan<Vector2> lines, Vector4 lineColor, float depth)Draws as DrawInScene does, but flat, for a game in 2D: triangles and lines on the XY plane at depth along Z, over what the scene draws in 2D — its sprites and Tilemaps — and under its gizmos: a navmesh in 2D over the floor it was baked from.
Parameters
nametrianglesfilllineslineColordepth
Exceptions
AbyssException: In a game's executable (AbyssStatus.NotInBuiltGame).
Over the scene's 2D: the Scene panel's 2D camera draws a scene's sprites over everything in the world, so a drawing in the world would lie under the floor it shows. A flat drawing is drawn by that camera after everything a scene draws in 2D, whatever its sorting layers and orders, see-through where its colors are; depth orders it among other flat drawings and keeps it in the camera's view.
Under the same names as DrawInScene: one replaces the other, and World.ForgetSceneDrawing takes either away. Engine thread.
ForgetSceneDrawing
public void ForgetSceneDrawing(string name)Takes away what was drawn in the Scene panel under name; nothing where nothing was. Engine thread.
Parameters
name
Exceptions
AbyssException: In a game's executable (AbyssStatus.NotInBuiltGame).
SetSceneLights2D
public void SetSceneLights2D(bool shown)Has the Scene panel draw what it shows lit by the 2D lights, as the game does, or as its art is drawn: a dark level worked on in the light. A game's cameras are lit whatever it says.
Parameters
shown
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
Asked again the same, the world writes nothing, so the editor asks at every frame. See abyss_core::light2d::SceneLights2D.
DrawnVariants
public IReadOnlyList<DrawnVariant> DrawnVariants()The variants drawing has asked the game's shaders for since this was last asked, each once.
Bevy composes a shader for each set of switches — shader defs — a draw asks for: the mesh's attributes, the camera's settings, the lights, the pass. A built game draws its shaders from SPIR-V compiled ahead for exactly those, so the editor takes them as they are drawn and compiles them (World.ShaderCompiler).
ForgetVariants
public void ForgetVariants(string path)Forgets which variants of a shader drawing has asked for, so World.DrawnVariants tells each again the next time it is drawn: what the editor does when its variants are cleared.
Parameters
path: The shader, relative to theshadersfolder.
UseCompiledShaders
public void UseCompiledShaders(bool on)Draws every game shader from its compiled variants, as a built game does, or from its text again.
Parameters
on: Whether to draw from compiled variants.
While on, a shader is drawn from the variants UseCompiledVariants gave it — none until then — and a variant nobody compiled draws magenta and is said in the log, as shader, with how it differs from the nearest compiled one.
UseCompiledVariants
public bool UseCompiledVariants(string path, IReadOnlyList<CompiledVariant> variants)Gives a shader the compiled variants it is drawn from while World.UseCompiledShaders is on, in place of any it had; and says whether it is — while off, the files are not read.
Parameters
path: The shader, relative to theshadersfolder.variants: Each variant's switches and SPIR-V file.
Exceptions
AbyssException: A file cannot be read.
ShaderCompiler
public ShaderCompiler ShaderCompiler(ShaderTarget target = Native)A compiler of the game's shaders as their files are now, against Bevy's shader library as this world holds it, for target: its GPU, or WebGL2 for a game built for the web. Dispose of it when done.
Parameters
target: What the variants it compiles are for.
Exceptions
AbyssException: The world has no assets, or a file in theshadersfolder cannot be read.
LoadShader
public ShaderId LoadShader(string path)Reads a shader out of the game's shaders folder, beside its assets.
Parameters
path: Relative to theshadersfolder.
Exceptions
AbyssException: The path leaves the folder, the file cannot be read, or what it takes cannot be: a binding 0 that is not a uniform struct, a value that is not a number, a vector or a matrix, or more than 256 bytes of them.
A WESL fragment shader whose entry point is called fragment, taking Bevy's VertexOutput, as Bevy's own shaders do. Its values are the struct at @group(constants::MATERIAL_BIND_GROUP) @binding(0), up to 256 bytes of 32-bit numbers, vectors of them and 4×4 matrices; its textures are texture_2d<f32> at bindings 1, 3, 5 and 7, each with its sampler after it. A value starts as a comment after it says — roughness: f32, // = 0.5 — or at zero, and a color white. It may import Bevy's shader library — bevy_pbr::render::pbr_functions lights a surface as Bevy's are lit — and the game's other shader files by their paths in the shaders folder, import package::noise::noise; for noise.wesl.
Read at once, not on the asset server's time, so what it takes is known on the next line. The renderer compiles it when something is first drawn with it, and a mistake in it is said in the log then. Asking for one file twice gives one id.
ShaderId water = world.LoadShader(Shaders.Water); // shaders/water.wesl, by the key the build writesMaterialId sea = world.CreateMaterial(water);world.SetFloat(sea, "speed", 2f);commands.SetMaterial(entity, sea);LoadShader
public ShaderId LoadShader(ShaderAddress shader)Reads the shader a key names (World.LoadShader): its file by its identity, where the world has been told where that is (World.UseAssetIndex), and otherwise by its address, its path in the shaders folder.
Parameters
shader: The key the build wrote for one of the game's shaders, or a package's.
Exceptions
AbyssException: As forWorld.LoadShader.
ReloadShader
public bool ReloadShader(string path)Reads a shader file again, if it has been read, and says whether it had.
Parameters
path: Relative to theshadersfolder.
Exceptions
AbyssException: The file cannot be read, or what it takes cannot be.
What the editor does when a shader is saved. The shader is replaced where it is, so everything drawn with it is drawn with what the file says now, and every material running it keeps each value whose name, kind and size are the same; a value new to the file starts as the file says. A file whose values cannot be read leaves the shader as it was.
LayoutOf
public ShaderLayout LayoutOf(ShaderId shader)What a shader takes.
Parameters
shader
Exceptions
AbyssException: No shader has that id, or it was released and has gone.
LayoutOf
public ShaderLayout LayoutOf(MaterialId material)What a material's shader takes.
Parameters
material
Exceptions
InvalidOperationException: The material is Bevy's own surface, which runs no shader.AbyssException: No material has that id.
CreateMaterial
public MaterialId CreateMaterial(ShaderId shader)Makes a material that runs a shader, its values what the shader says they start as.
Parameters
shader
Exceptions
AbyssException: No shader has that id, or it was released and has gone.
An ordinary MaterialId: given to an entity by CommandBuffer.SetMaterial or CommandBuffer.SetMesh, copied by World.CopyMaterial and let go of by World.Release. Its values are set by the names the shader gives them — World.SetFloat, World.SetVector, World.SetColor, World.SetTexture — rather than by a MaterialSpec, which only Bevy's own surface has.
PathOf
public string PathOf(ShaderId shader)What file a shader was read from, relative to the shaders folder.
Parameters
shader
StateOf
public AssetState StateOf(ShaderId shader)How far along a shader is: AssetState.Loaded from the moment it is read.
Parameters
shader
Release
public void Release(ShaderId shader)Lets go of a shader: it stays while a material runs it. See World.Release.
Parameters
shader
Exceptions
AbyssException: It was let go of already, or the world never gave out that id.
ShaderOf
public ShaderId? ShaderOf(MaterialId material)The shader a material runs, or null for one that is Bevy's own surface.
Parameters
material
Exceptions
AbyssException: No material has that id.
SetFloat
public void SetFloat(MaterialId material, string name, float value)Sets a material's value of one float, by the name its shader gives it.
Parameters
materialnamevalue
Exceptions
AbyssException: The material runs no shader, its shader takes no value of that name, or the value is not one number.
For everything drawn with the material, as World.UpdateMaterial is.
SetInt
public void SetInt(MaterialId material, string name, int value)Sets a material's value of one 32-bit integer, signed or not, by name.
Parameters
materialnamevalue
Exceptions
AbyssException: AsWorld.SetFloat.
SetVector
public void SetVector(MaterialId material, string name, Vector4 value)Sets a material's vector value, by name: as many of the vector's numbers as the value holds.
Parameters
materialnamevalue
Exceptions
AbyssException: AsWorld.SetFloat, or a value that is not a vector of floats.
A vec2 takes X and Y, a vec3 X, Y and Z, a vec4 all four.
SetVector
public void SetVector(MaterialId material, string name, Vector2 value)Sets a material's vec2 value, by name.
Parameters
materialnamevalue
Exceptions
AbyssException: AsWorld.SetVector.
SetVector
public void SetVector(MaterialId material, string name, Vector3 value)Sets a material's vec3 value, by name.
Parameters
materialnamevalue
Exceptions
AbyssException: AsWorld.SetVector.
SetColor
public void SetColor(MaterialId material, string name, Vector4 color)Sets a material's color, by name: red, green, blue, and alpha where it has one.
Parameters
materialnamecolor
Exceptions
AbyssException: AsWorld.SetVector.
Linear, as every color a material holds is.
SetMatrix
public void SetMatrix(MaterialId material, string name, Matrix4x4 value)Sets a material's 4×4 matrix value, by name, row by row as .NET writes a matrix.
Parameters
materialnamevalue
Exceptions
AbyssException: AsWorld.SetFloat, or a value that is not a 4×4 matrix.
WGSL's matrices are columns, so this crosses the transpose: what a shader multiplies a column vector by is what Vector4.Transform does here.
GetFloat
public float GetFloat(MaterialId material, string name)What a material's float value holds, by name.
Parameters
materialname
Exceptions
AbyssException: AsWorld.SetFloat.
GetInt
public int GetInt(MaterialId material, string name)What a material's integer value holds, by name.
Parameters
materialname
Exceptions
AbyssException: AsWorld.SetFloat.
GetVector
public Vector4 GetVector(MaterialId material, string name)What a material's vector value holds, by name, its numbers past the value's zero.
Parameters
materialname
Exceptions
AbyssException: AsWorld.SetVector.
SetAlphaMode
public void SetAlphaMode(MaterialId material, AlphaKind alpha)Says how a material running a shader is drawn over what is behind it, as Bevy's own surface's MaterialSpec.Transparency does: opaque, as it starts; cut out (AlphaKind.Mask), where its shader leaves a pixel out with discard; or blended, premultiplied, added or multiplied, drawn after everything opaque.
Parameters
materialalpha
Exceptions
AbyssException: The material runs no shader, or the mode is none there is.
A cut-out material casts the shadow of what it keeps. Its depth and its shadows are drawn with its own shader too, Bevy's PREPASS_PIPELINE defined, where it discards what it leaves out as it does in its main pass; the Lit Shader template shows how. Every other material's are drawn with Bevy's own. A UI element's material is blended whatever it says.
AlphaModeOf
public AlphaKind AlphaModeOf(MaterialId material)How a material running a shader is drawn over what is behind it; see World.SetAlphaMode.
Parameters
material
Exceptions
AbyssException: The material runs no shader.
SetDoubleSided
public void SetDoubleSided(MaterialId material, bool on)Says whether a material running a shader is drawn from both sides, as Bevy's own surface's MaterialSpec.DoubleSided does: its back faces drawn too, in its shadows as well, where one drawn from one side, as it starts, has them culled.
Parameters
materialon
Exceptions
AbyssException: The material runs no shader.
A back face takes the normal of its front: a shader lighting one turns it round, as the Lit Shader template does with pbr_functions::prepare_world_normal.
IsDoubleSided
public bool IsDoubleSided(MaterialId material)Whether a material running a shader is drawn from both sides; see World.SetDoubleSided.
Parameters
material
Exceptions
AbyssException: The material runs no shader.
SetTexture
public void SetTexture(MaterialId material, string name, ImageId? image)Gives a material's texture an image, by the name its shader binds it by; null takes it away.
Parameters
materialnameimage
Exceptions
AbyssException: The material runs no shader, its shader binds no texture of that name, or no image has that id.
A slot with no image samples white.
SetWords
public void SetWords(MaterialId material, string name, ReadOnlySpan<uint> words)Sets a material's value by name as the 32-bit words its shader reads: a float's bits, or an integer's, one for each of its numbers.
Parameters
materialnamewords
Exceptions
AbyssException: AsWorld.SetFloat, or a count the value does not hold.
What the typed setters come to, for a caller that has the value's kind from its ShaderLayout.
WordsOf
public uint[] WordsOf(MaterialId material, string name)What a material's value holds, by name, as the 32-bit words its shader reads.
Parameters
materialname
Exceptions
AbyssException: AsWorld.SetFloat.
Text
public SharedText Text(string? text)A text holding text, to put in a component's SharedText field: the one already made if an equal text is held, a new one otherwise; empty for an empty string. See SharedText for how long it lives.
Parameters
text
TextOf
public string TextOf(SharedText text)The string a text holds: empty for SharedText.Empty.
Parameters
text
Exceptions
AbyssException: Its text was let go of, nothing holding it; seeSharedText.
TryTextOf
public string? TryTextOf(SharedText text)The string a text holds, or null for one let go of.
Parameters
text
SetSky
public void SetSky(ulong camera, CameraSky? sky)Gives a camera of the game's — a scene's camera — the sky sky says, or takes its sky away for null, its clear color showing again. Writes nothing where it has that sky already, so it may be asked every frame: a sky going from day to dusk, say.
Parameters
camerasky
Exceptions
AbyssException:AbyssStatus.InvalidSkyfor an entity that is no camera, a horizon reaching less than a degree or past 90, a glow's exponent below 1, or a number that is not one.
SkyOf
public CameraSky? SkyOf(ulong camera)The sky a camera of the game's has; null where it has none.
Parameters
camera
Exceptions
AbyssException:AbyssStatus.InvalidSkyfor an entity that is no camera.
UseSortingLayers
public void UseSortingLayers(SortingLayers layers)Sorts sprites by the game's sorting layers from the next frame drawn: what the editor tells the world as Project Settings changes them, and a game as it starts.
Parameters
layers
Exceptions
AbyssException: The engine cannot use the list, saying why; it keeps the one it had.
SortingLayerNamed
public uint? SortingLayerNamed(string name)The identity of the game's sorting layer called name, which a sprite's SortingOrder keeps in its layer; null where the list has none so called.
Parameters
name
StyleProperties
public IReadOnlyList<StyleProperty> StyleProperties()Every property a stylesheet's rule can set, as bevy_flair has them, with what each is and starts as.
Exceptions
AbyssException: The world has no interface.
StyleRuleValues
public IReadOnlyList<StyleValue> StyleRuleValues(string text, int rule)What the rule at rule among the rules of the sheet whose text is text sets, each property once, as it sets it last.
Parameters
textrule
Exceptions
AbyssException: The world has no interface.
EditStyleSheet
public (string Text, bool Done) EditStyleSheet(string text, string edit)The sheet whose text is text with edit — one of StyleSheetText's — done to it; or why it cannot be.
Parameters
textedit
Returns The text edited and true, or why it cannot be and false.
Exceptions
AbyssException: The world has no interface.
StyleValueProblem
public string? StyleValueProblem(string css, string value)Why value is no value of the property css bevy_flair reads, or null where it is one.
Parameters
cssvalue
Exceptions
AbyssException: The world has no interface.
UseImported
public void UseImported(string path, string artifact, ImportSettings settings)Says the image at path has been imported into artifact with settings: every load of the path reads the import, and an image already loaded from it is the import from now on, under the id it has, every material drawn with it drawing the import. A source still being read is waited for.
Parameters
path: The image, by its path under the asset root.artifact: The import, its whole path.settings: The settings it was imported with, which say how it is sampled too.
Exceptions
AbyssException: The import cannot be read; the path goes on reading its source.
UseImageSettings
public void UseImageSettings(string path, ImportSettings settings)Says how the project's image at path is read, as its import settings say: every load of it from its source from now on reads it so, whoever asks for it — a sprite a scene names, a frame of a clip, a material file's slot — with its own filter and wrap and its colors read as it says. What a game played from its folders tells its world of each image before anything is loaded: an image read from its source already keeps how it was read.
Parameters
path: The image, by its path under the asset root.settings: Its import settings;ImportSettings.NothingSaidforgets what was said.
Exceptions
AbyssException: The path leaves the asset root, or the settings name what this build does not.
UseTimeSettings
public void UseTimeSettings(TimeSettings settings)Gives the game's clock a game's Time settings: its fixed timestep, its largest frame and its time scale. What the editor tells the world as Project Settings changes them and at every Play, and a game as it starts.
Parameters
settings
Exceptions
ArgumentException: A number is one no clock can be given (TimeSettings.WhyNot).
SetSceneDraft
public int SetSceneDraft(SceneId scene, bool draft)Makes scene a UI document being edited, everything in it a draft that every query leaves out and whatever is put in it after, or a scene again.
Parameters
scenedraft
Returns How many entities are in the scene.
Exceptions
AbyssException: The entity is not a scene.
ShowUiCanvasIn
public void ShowUiCanvasIn(SceneId scene, uint texture, uint width, uint height, Vector2 screen)Draws the draft scene scene on the canvas: into paint texture texture, width by height physical pixels, laid out as a screen screen pixels big at the scale the project's reference resolution gives it, whatever the game's own documents are drawn at. Its camera is made the first time, on a render layer nothing else is on.
Parameters
scenetexturewidthheightscreen
Exceptions
AbyssException: Rendering is not enabled, the scene is not a draft, or the picture or the screen has no size.
Saying the same again changes nothing, so a caller can say it at every frame.
HideUiCanvas
public void HideUiCanvas()Stops drawing the canvas, its copy taken away. Nothing, if it was never shown.
PickInUiCanvas
public ulong[] PickInUiCanvas(Vector2 at)The elements of the draft drawn under at, a point of the canvas's picture as a share of its width and its height, zero to one from its top left: the one on top first, then each drawn beneath it. None where nothing is drawn.
Parameters
at
UiCanvasCorners
public Vector2[]? UiCanvasCorners(ulong element)Where the element of the draft element is drawn on the canvas: its corners as shares of the picture's width and height, from the top left round clockwise; null where it is not drawn.
Parameters
element
Exceptions
AbyssException: The bits are no entity's.
UiCanvasRules
public IReadOnlyList<UiRule> UiCanvasRules(ulong element)Each field of the element of the draft element a stylesheet's rule sets as it is drawn on the canvas, with the rule that sets it; none where it is not drawn.
Parameters
element
Exceptions
AbyssException: The bits are no entity's.
UiCanvasMatched
public IReadOnlyList<UiMatch> UiCanvasMatched()Every rule of the document's sheets applying to an element drawn on the canvas, as bevy_flair applies it now — the states held there with the rest — with the elements of the draft it applies to; none while the canvas is hidden. A rule that sets nothing applies to nothing.
UiCanvasNamed
public UiNamed? UiCanvasNamed(ulong element)What a selector can name the element of the draft element by as it is drawn on the canvas: its kind, its name and its classes; null where it is not drawn.
Parameters
element
Exceptions
AbyssException: The bits are no entity's.
HoldInUiCanvas
public void HoldInUiCanvas(ulong element, UiStates states)Holds the element of the draft element in states on the canvas, so what its sheets say for each is what it is drawn by with nothing pointing at it; or lets it go, with none. Each copy made of it after is held so too.
Parameters
elementstates
Exceptions
AbyssException: The bits are no entity's.
UiCanvasLaidOut
public UiCanvasLaid? UiCanvasLaidOut(ulong element)How the element of the draft element is laid out on the canvas, in the document's own pixels; null where it is not drawn.
Parameters
element
Exceptions
AbyssException: The bits are no entity's.
UseUiSettings
public void UseUiSettings(UiSettings settings)Styles every document by the game's theme and lays them out for its reference resolution: what the editor tells the world as Project Settings changes them, and a game as it starts.
Parameters
settings
Exceptions
AbyssException: The engine cannot read the theme's name, saying why; it keeps the one it had.
SpawnWindow
public WindowId SpawnWindow(int x, int y, uint width, uint height, WindowFlags flags = None, uint background = 4278190080, string? title = null)Opens a window beside the primary one, hidden.
Parameters
x: Left edge of its client area, in physical pixels.y: Top edge of its client area, in physical pixels.width: Width of its client area, in physical pixels.height: Height of its client area, in physical pixels.flags: How it behaves.background: What it is cleared to when painting is enabled, packed as aPaintVertexcolor is: red in the lowest byte.title: What its title bar, the taskbar and Alt+Tab call it.
Exceptions
AbyssException: For a window with no pixels in it.
DespawnWindow
public void DespawnWindow(WindowId window)Closes a window opened with World.SpawnWindow, and everything drawing into it.
Parameters
window
Exceptions
AbyssException: For a window that is not one of those.
If the engine's camera was in it, the camera goes back to the primary window first; see World.SetCameraWindow.
PlaceWindow
public void PlaceWindow(WindowId window, int x, int y)Moves a secondary window's top left corner, in physical pixels.
Parameters
windowxy
Cheap to call every frame: saying where a window already is changes nothing.
ResizeWindow
public void ResizeWindow(WindowId window, uint width, uint height)Sizes a secondary window's client area, in physical pixels.
Parameters
windowwidthheight
ShowWindow
public void ShowWindow(WindowId window)Shows a secondary window, which opens hidden.
Parameters
window
FocusWindow
public void FocusWindow(WindowId window)Gives a secondary window the keyboard.
Parameters
window
RetitleWindow
public bool RetitleWindow(WindowId window, string title)Changes what a window is called: the title bar, the taskbar and Alt+Tab.
Parameters
windowtitle
The main window's too, which is where an editor says what is open and whether it is saved. Saying what it is already called changes nothing, so this can be said every frame; false, rather than an exception, when there is no such window, as World.SetCursor — the main window does not exist before the first frame.
HoldWindowClose
public void HoldWindowClose(bool held)Says whether the platform's request to close the main window is the caller's to answer.
Parameters
held
Not held, the main window closes when the platform asks — its close button, Alt+F4 — and the application with it. Held, it stays, and the request is reported once by World.WindowStateOf as WindowState.CloseRequested, the way a secondary window's is: an editor with work not yet saved asks about it, then quits or does not.
Before the main window exists too, so it can be said once at the start.
WindowStateOf
public WindowState? WindowStateOf(WindowId window)What a window is doing, or null if there is no such window.
Parameters
window
Null rather than an exception for a window that is not there, because that is an answer: the primary does not exist before the first frame or on a world with no windowing at all, and a caller asking every frame should not have to catch its way through the first one.
WindowStateFlags.CloseRequested is reported once and then forgotten.
SetCursor
public bool SetCursor(WindowId window, CursorShape shape)Sets the shape the pointer takes over a window.
Parameters
windowshape
The window's rather than the application's: each keeps its own, and the platform shows whichever belongs to the window under the pointer. So an interface spread over several windows tells every one the same shape and lets the platform pick. Saying the shape a window already has changes nothing, so this can be said every frame.
False, rather than an exception, when there is no such window — for the same reason World.WindowStateOf returns null: the primary does not exist on a headless world.
CursorOf
public CursorShape? CursorOf(WindowId window)The shape the pointer takes over a window, or null if there is no such window.
Parameters
window
CaptureCursor
public bool CaptureCursor(WindowId window, bool captured)Hides the pointer over a window and holds it there, or lets go of it where it was taken.
Parameters
windowcaptured
What a camera the mouse turns wants: the pointer out of sight and going nowhere while the view turns, and back where it was when it stops. The mouse's motion still arrives, in InputState.MotionX and InputState.MotionY. Where the platform cannot hold the pointer still — X11 — it is kept inside the window, where it is hidden.
Saying what is already so changes nothing, so this can be said every frame: held twice, the pointer goes back to where it was taken first. False, rather than an exception, when there is no such window, as World.SetCursor.
ShowCursor
public bool ShowCursor(WindowId window, bool shown)Shows or hides the pointer over one of the engine's windows, held or not: what the editor does for a game that hides it, while the pointer is over the game's picture.
Parameters
windowshown
Returns false if there is no such window.
A pointer World.CaptureCursor holds stays hidden until it is let go. Saying what is already so changes nothing.
IsCursorCaptured
public bool? IsCursorCaptured(WindowId window)Whether the pointer over a window is held, or null if there is no such window; see World.CaptureCursor.
Parameters
window
HandleOf
public (WindowHandleKind Kind, ulong Handle)? HandleOf(WindowId window)The operating system's handle for a secondary window, or null until the platform has made it.
Parameters
window
See World.WindowHandle for the primary's.
Monitors
public DisplayMonitor[] Monitors()The monitors the platform reported, the primary first. Empty on a headless world.
PaintWindow
public uint PaintWindow(WindowId window, ReadOnlySpan<PaintVertex> vertices, ReadOnlySpan<uint> indices, ReadOnlySpan<PaintBatch> batches, float width, float height)Draws one frame of triangles into a secondary window, laid out across width by height.
Parameters
windowverticesindicesbatcheswidthheight
Returns How many triangles reached a mesh.
The size is the caller's, not the window's. Positions are mapped so that the frame's own width and height meet the window's edges, which is what lets an interface laid out in logical units fill a window whose size the engine only knows in physical ones. See Paint for everything else.
SetCameraWindow
public void SetCameraWindow(WindowId window)Moves the engine's camera into a window.
Parameters
window
Where in that window is still World.SetCameraViewport's, in that window's physical pixels. Moving it to the window it is already in changes nothing, so a caller can say where the scene is every frame.
The interface in the window the game leaves starts clearing that window, and the one in the window it arrives in stops, because clearing there would erase the scene.
SetCameraActive
public void SetCameraActive(bool active)Switches the engine's camera on or off.
Parameters
active
Off, nothing of the scene is drawn — Bevy does not even hand the camera to the renderer — and every window's interface clears what is under it, the one the camera was drawing into included. Where the camera points and the rectangle it is confined to are kept, so switching it back on puts the game back where it was.
For an editor whose Scene panel is closed or behind another tab: drawing a scene nobody can see is a frame's worth of work for nothing. Saying what it already is changes nothing.
ShowGameIn
public void ShowGameIn(uint texture, uint width, uint height, float scale)Draws the game's own cameras into a texture rather than into a window: an editor's Game view, which paints the texture like any other.
Parameters
texture: The paint texture id to draw into, asSetPaintTexturenames one.width: Its width in physical pixels.height: Its height in physical pixels.scale: Physical pixels to a logical one, as the window it is shown in has it.
Exceptions
AbyssException: Rendering is not enabled, or the size or scale is nothing.
Every camera that is not the engine's draws there from the next frame on — one a scene brought, one a game spawned while it plays — while the engine's own camera, which an editor draws its Scene view through, stays where it is. Only where each camera draws is changed, which a scene does not keep; its viewport, its order and whether it is active stay the game's.
Saying the same size again changes nothing, so a caller can say it at every frame. A new size keeps the texture id, so whatever paints it goes on painting it.
TakeScreenshot
public uint TakeScreenshot(uint width, uint height, uint supersample, string? path, bool copy)Asks for a screenshot of the game as the Game view draws it: width by height pixels, or the view's own size and scale where either is zero, drawn supersample times as wide and as high and scaled down; saved as a PNG at path where one is given, its folder made, and put on the clipboard where copy says. The editor's alone: a game's executable is built without it.
Parameters
widthheightsupersamplepathcopy
Returns The number World.FinishedScreenshot says it by.
Exceptions
AbyssException:AbyssStatus.InvalidScreenshot, saying why, where it cannot be taken: no Game view, no camera of the game's drawing, a supersample outside 1 to 4, nowhere to keep it, or a picture wider or higher than the GPU draws.
Taken a few frames on, at a size of its own once the game's interface is laid out for it, and kept on a thread of its own; World.FinishedScreenshot says when.
FinishedScreenshot
public (uint Id, bool Kept)? FinishedScreenshot()The oldest screenshot taken since this was last asked — its number and whether it was saved and copied as asked, the log saying why not — or null where none has been.
StartRecording
public uint StartRecording(string path, uint fps, RecordingQuality quality, bool steady, bool sound)Starts recording a video of the game as the Game view draws it, into the MP4 at path, its folder made: fps pictures a second of quality; its clock stepped a picture at a time where steady, so it is smooth however long a frame takes, and read as it plays where not; the game's sound kept beside where sound. The editor's alone: a game's executable is built without it.
Parameters
pathfpsqualitysteadysound
Returns The number World.FinishedRecording says it by.
Exceptions
AbyssException:AbyssStatus.InvalidRecording, saying why, where it cannot be recorded: one being recorded already, no Game view, a rate it cannot be made at, nowhere to write it, or no encoder on the platform.
What the Game view draws is kept at the size it is now: keep it so until the video stops (World.StopRecording), which World.FinishedRecording says when it is written.
StopRecording
public void StopRecording()Stops the video being recorded, which is written once its last pictures are in. Nothing where none is.
Recording
public (RecordingState State, double Seconds) Recording()Whether a video is being recorded, and how many seconds of it have been kept.
FinishedRecording
public (uint Id, ulong Pictures, bool Written)? FinishedRecording()The oldest video finished since this was last asked — its number, how many pictures it holds and whether it was written, the log saying why not — or null where none has been.
ShowPreviewIn
public void ShowPreviewIn(uint texture, uint width, uint height, float scale)Has the preview's camera draw into paint texture texture: an editor's picture of one model, with a camera and a light of its own on a render layer nothing else is on, made the first time. See World.AdoptPreview.
Parameters
texture: The paint texture id to draw into, asSetPaintTexturenames one.width: Its width in physical pixels.height: Its height in physical pixels.scale: Physical pixels to a logical one, as the window it is shown in has it.
Exceptions
AbyssException: Rendering is not enabled, or the size or scale is nothing.AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
Saying the same size again changes nothing, so a caller can say it at every frame.
HidePreview
public void HidePreview()Stops the preview's camera drawing, while nothing shows it. Nothing, if it was never shown.
Exceptions
AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
AdoptPreview
public void AdoptPreview(ulong root)Makes root and everything under it the model the preview shows — the engine's, so the hierarchy does not list it, Play's snapshot does not keep it and the Game view's routing leaves it alone, and on the preview's render layer, so only the preview's camera draws it and the Scene view does not pick it — or none for zero. The camera frames it afresh once its meshes are there.
Parameters
root: The model's root: an instance of its prefab in no scene; zero for none.
Exceptions
AbyssException: The entity is not there.AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
OrbitPreview
public void OrbitPreview(float yaw, float pitch, float zoom)Turns the preview's camera round its model: yaw degrees round from in front, pitch degrees above it, and zoom times as far as it takes to see all of it.
Parameters
yaw: Degrees round, from in front, towards its right.pitch: Degrees above it; from −89 to 89.zoom: How far, from 0.2 to 5 times as far as it takes to see it all.
Exceptions
AbyssException: A number outside those.AbyssException: In a game's executable, which is built without what only the editor does (AbyssStatus.NotInBuiltGame).
GameCameras
public int GameCameras()How many of the game's own cameras are drawing: active, and not the engine's. Zero in a world that does not render.
What a Game view warns by at zero: with no camera drawing, nothing of the game is seen.
UnseenSprites
public int UnseenSprites()How many of the game's sprites none of its cameras draws: every one shown, where no 2D camera of the game's is drawing, as only a 2D camera draws a sprite; none where one is. Zero in a world that does not render.
What a Game view says a 2D camera is wanted by.
Create
public static World Create(WorldSetup? setup = null)Creates a world with what setup names, and then the game's plugins.
Parameters
setup: Its window, assets and renderer, ornullfor none of them: a headless world. SeeWorldSetupfor why they are named here and nowhere later.
Exceptions
ArgumentException: The window has no title, or no size.AbyssException: The native core refused to create the world: a renderer with no window (AbyssStatus.NoWindow), or a window asked for off the main thread.InvalidOperationException: The native library's ABI does not match; or, on Windows, a window is asked for on a thread in a multithreaded apartment, a game's Main not marked[STAThread].
RegisterComponent<T>
public ComponentType<T> RegisterComponent<T>(string? name = null) where T : unmanagedRegisters T as a component type, deriving its size and alignment from the CLR layout.
Type parameters
T: A plain-data struct. Theunmanagedconstraint is what makes the shared-memory model sound: the native side never runs a destructor for a component, so a component that owned a heap allocation or an OS handle would leak it. Declare the struct[StructLayout(LayoutKind.Sequential)]so its field order is predictable.
Parameters
name: Display name; defaults to the type name.
RegisterAnimationEvent<T>
public ComponentType<T> RegisterAnimationEvent<T>(ReadOnlySpan<ComponentFieldSpec> fields, ReadOnlySpan<FieldHint> hints, string? name = null) where T : unmanagedRegisters an animation event's struct: as a component nothing carries, so its fields are described and shown as a component's are, and listed among the world's World.AnimationEvents rather than its World.AddableComponents. What the generator behind AnimationEventAttribute calls.
Type parameters
T: The struct.
Parameters
fields: Where its fields are, measured.hints: What its fields' attributes say of showing them.name: The name clips' events name it by; the type's own name for null.
Returns The struct, as a component of this world.
AnimationEventTypes
public IReadOnlyList<AnimationEventType> AnimationEventTypes()Each animation event registered, described for an editor: its fields as its layout has them, what its hints say of showing them, and the bytes it starts as, in the order of its name.
Component<T>
public ComponentType<T> Component<T>() where T : unmanagedThe component T, as this world registered it.
Type parameters
T: A component declared from C#.
Exceptions
InvalidOperationException: Nothing has registered it in this world.
For whatever needs a component and did not register it: a game's plugin, above all, which the editor builds long after it registered the game's components so a scene could name them — and registering again is not the same thing, since it declares a second component that nothing carries. The first registration is the one found.
The engine's own components are asked for by name instead: World.Transform and the rest.
RegisterComponent<T>
public ComponentType<T> RegisterComponent<T>(ReadOnlySpan<ComponentFieldSpec> fields, string? name = null) where T : unmanagedRegisters a component that can also tell the engine where its fields are.
Type parameters
T: The plain-data struct to store. SeeWorld.RegisterComponent.
Parameters
fields: Where the fields are. May be empty, which is the undescribed case.name: Display name; defaults to the type name.
Exceptions
AbyssException: The table does not fit the component it describes.
This is the difference between an inspector for the engine's components and one for a game's. Without a table, a component declared here is a size and an alignment: it is stored, read back and written whole perfectly well, but a panel showing it has nothing to call its fields and no offsets to edit at. With one it is inspected exactly like Transform, by code that has never heard of either.
The table is copied during the call, so the names need not outlive it. It is also checked: the engine cannot know where a field really is, but it can refuse a table whose fields run past the end of the component or cover the same bytes twice, which is what a generator bug looks like from this side.
Prefer AbyssComponentAttribute, which writes the table for you from the actual field addresses. Call this directly only when the struct cannot be made partial or the layout is genuinely dynamic.
RegisterComponent<T>
public ComponentType<T> RegisterComponent<T>(ReadOnlySpan<ComponentFieldSpec> fields, ReadOnlySpan<FieldHint> hints, string? name = null) where T : unmanagedRegisters a component that can tell the engine where its fields are, and an inspector how to show them.
Type parameters
T: The plain-data struct to store. SeeWorld.RegisterComponent.
Parameters
fields: Where the fields are. May be empty, which is the undescribed case.hints: How to show them. May be empty.name: Display name; defaults to the type name.
Exceptions
ArgumentException: A hint does not fit the fields.AbyssException: The table does not fit the component it describes.
What the generator behind AbyssComponentAttribute calls, with what RangeAttribute, TooltipAttribute and HideInInspectorAttribute said. The hints stay on this side — the engine has no use for them — and World.HintsOf gives them back by the id this returns.
Checked before anything is registered, as the table is: a hint that names no field, a range on something that is not a number, or a range with nothing in it is refused rather than kept, so a hand-written table fails where it is written and not in a panel.
RegisterComponent<T>
public ComponentType<T> RegisterComponent<T>(ReadOnlySpan<ComponentFieldSpec> fields, ReadOnlySpan<FieldHint> hints, string? name, in T start) where T : unmanagedRegisters T with a field table and hints, and what a new value of it starts as: start, which the generator behind AbyssComponentAttribute makes with the struct's constructor, so its field initializers — public float GravityScale = 1f; — are what Add Component, a scene load and a spawn give it, where it would otherwise start at zero.
Type parameters
T: The plain-data struct to store.
Parameters
fields: Where the fields are.hints: How to show them.name: Display name; defaults to the type name.start: A new value of it, as it starts.
Exceptions
ArgumentException: A hint does not fit the fields.AbyssException: The table does not fit the component it describes.
SetComponentStart<T>
public void SetComponentStart<T>(ComponentType<T> type, in T start) where T : unmanagedSays what a new value of a component declared from C# starts as: start, from then on; all zero is the same as saying nothing. See RegisterComponent<T>.
Type parameters
T
Parameters
typestart
Exceptions
AbyssException: The component is the engine's, whose start its own type makes.
CurveFields
public IReadOnlyList<string> CurveFields()The fields a clip's curve can write, each Component.Field: every number and flag of a component declared from C# with a field table — the newest registration of each name, an animation event's struct and a project's settings left out — in the order of their names.
HintsOf
public IReadOnlyList<FieldHint> HintsOf(ComponentId component)What a component's author said about its fields: how they are shown and what they were called before — C# attributes on a component declared here, and the same names as Bevy's custom attributes on one Bevy or a plugin declared (#[reflect(@Range(0.0, 1.0))]); empty for one that said nothing.
Parameters
component: Which component.
Exceptions
AbyssException: The id names no component.
Asked by an inspector, which has the component's id and not its type, and by a scene, which looks a file's field up by name. See FieldHint.
A Rust component's are the engine's to say, since they are on its type (see abyss_core::hint); they are asked once, as nothing about a component changes while the world lives.
EngineComponent<T>
public ComponentType<T> EngineComponent<T>(string name) where T : unmanagedBinds a component the engine declares in Rust, checking that this side's mirror agrees.
Type parameters
T: The mirror struct. Must match the engine's layout exactly.
Parameters
name: The name the engine registered it under.
Exceptions
InvalidOperationException: The mirror does not match.
Everywhere else C# declares the component and Rust stores it. These go the other way: the engine owns the declaration because subsystems written in Rust need it in a shape they agree on, and C# binds to it by name.
That only works if both sides really do agree, which is what the size and alignment check is for: a field added on one side and not the other would otherwise be a silent misread of every entity, which is exactly the class of bug shared memory makes easy.
Size and alignment are not sufficient on their own, and the engine's transforms are why. They are Bevy's types, #[repr(Rust)], and the compiler reorders them — a mirror can have the right size and still read the wrong field. Where the mirror is of a type this repository did not declare, the caller has to check the offsets too; World.Transform does, against World.LayoutOf.
LayoutOf
public ComponentLayout LayoutOf(string name)Finds a component by name and reads where its fields actually sit.
Parameters
name: The component's name: the engine's, a declared one, Bevy's short name, or the full Rust type path where two types share a short one.
Exceptions
AbyssException:AbyssStatus.ComponentNotFoundwhen nothing answers to the name.
The alternative to mirroring, and the only one available for a component whose layout C# cannot safely assume. Every offset was taken from the Rust compiler rather than written down, so a struct the compiler reordered reports reordered fields and C# follows them.
Any component answers to this, not only the engine's: one declared from C#, and every component Bevy's type registry knows — Bevy's own DirectionalLight, and a plugin's, found because it derives Reflect with #[reflect(Component)], which the ecosystem already asks of it. Nothing lists them. See World.ComponentByName for the order names are searched in.
Pair it with Chunk.GetFieldView to read and write the values, and with ComponentLayout.Write to build the query. Where a mirror is available — the #[repr(C)] components the engine declares for exactly this reason — World.EngineComponent and Chunk.GetSpan are faster and remain the better choice.
A component with nothing describable in it — a Rust enum, say — comes back with no fields rather than as an error: it exists and can be queried for, and there is nothing in it at an offset to read.
ReadInput
public InputState ReadInput()Reads the keyboard and mouse into one snapshot.
One crossing for every question a frame will ask. Call it once at the top of your frame and query the result — see InputState for why it is a snapshot rather than an API of its own.
Reading it twice in one frame gives the same answer: "pressed this frame" is Bevy's own per-frame bookkeeping rather than something the engine computes by differencing. Everything is zero on a world with no window.
RenderEntities
public (ulong Camera, ulong Light)? RenderEntities()The camera and light the renderer spawned, or null if rendering is not enabled.
They are ordinary entities with ordinary World.Transforms, which is the whole of the feature: to move the camera, write its transform the way you write any other. Nothing new crosses the boundary for it and nothing about a camera is a special case.
VisibleCount
public uint VisibleCount()How many entities the renderer decided to draw on the last frame.
The renderer's own answer rather than a proxy for it. Bevy sets ViewVisibility in its PostUpdate for every entity that passed frustum culling for some view, and only those are submitted to be drawn — so this is as close to "did you draw this" as anything short of reading back a pixel. A shadow-casting light is a view too, so an entity visible only to the light is counted.
Zero with meshes in the world is informative rather than ambiguous: the geometry is there and nothing is looking at it, which is a camera or a transform problem rather than an asset one. Zero without a renderer is simply the truth.
SetCameraProjection
public void SetCameraProjection(in SceneProjection projection)Has the engine's camera project as the Scene panel asks: in perspective, or orthographic for a field of view of zero. Writes nothing where it projects so already, so it may be asked every frame.
Parameters
projection
Exceptions
AbyssException:AbyssStatus.NoRendererwhere nothing renders, andAbyssStatus.InvalidProjectionfor a projection that projects nothing.
SetProjection
public void SetProjection(ulong camera, in SceneProjection projection)Has a camera of the game's — a scene's camera, an entity with a Camera3d or Camera2d — project as projection says: its field of view, where it stops drawing near and far, or orthographic for a field of view of zero. world.SetProjection(camera, SceneProjection.Perspective(70f, 0.05f, 600f)). Writes nothing where it projects so already, so it may be asked every frame.
Parameters
cameraprojection
Exceptions
AbyssException:AbyssStatus.InvalidProjectionfor an entity that is no camera, or a projection that projects nothing: a field of view not between 0 and 180 degrees, a perspective near plane at or behind the camera, a far plane no further than the near one.
ProjectionOf
public SceneProjection ProjectionOf(ulong camera)How a camera of the game's projects; see World.SetProjection.
Parameters
camera
Exceptions
AbyssException:AbyssStatus.InvalidProjectionfor an entity that is no camera.
SetCameraViewport
public void SetCameraViewport((uint X, uint Y, uint Width, uint Height)? rect)Confines the engine's camera to a rectangle of the window, or fills the window.
Parameters
rect: Where the game is drawn, or null to fill the window. A rectangle with no pixels in it is refused rather than passed to the driver.
What an editor uses to put the game in the space its panels left rather than behind them. Without it the scene is drawn across the whole window and the interface covers most of it, so framing a scene puts half of it behind the inspector.
The rectangle is in physical pixels, because that is what a window's surface is measured in. An interface lays out in logical ones, so the caller converts using the scale factor from World.WindowSize — it is the one that knows what it laid out with, and applying the scale in both places is the classic way to get a viewport that is only correct on one display.
Only the engine's camera moves. The interface draws over the whole window, which is what lets a panel sit outside the rectangle.
ReadText
public ReadOnlySpan<uint> ReadText()Everything typed since the last call to this method.
Returns The characters, over memory the engine owns. Valid until the next call to this method or until the world is disposed, so copy anything you need to keep.
Unicode scalar values in the order they were typed. This is not World.ReadInput and does not overlap with it. A shortcut asks the snapshot whether Control and S are down; a text field asks this what was typed. Neither can answer the other's question, which is why there are two of them.
Every character is reported exactly once. The engine keeps a position rather than a buffer, so calling this twice in a frame returns nothing the second time rather than everything twice — and a frame that skipped a call gets both frames' characters on the next one rather than losing any. Read it once a frame and hand the result to whoever needs it.
Enter, Tab and Backspace are not here: they move a cursor and delete things rather than inserting anything, and they arrive through World.ReadInput where a text field has to handle them anyway. A platform that reports Enter as a carriage return in the same place a letter arrives would otherwise put a newline in every name somebody confirmed.
ReadKeys
public ReadOnlySpan<KeyEvent> ReadKeys()Every key that went down or came up since the last call to this method, in the order it did.
Returns The events, over memory the engine owns. Valid until the next call to this method or until the world is disposed.
What World.ReadInput cannot say. The snapshot says which keys moved during a frame and not in what order, and a shortcut needs the order: Ctrl+A followed at once by a capital X moves Ctrl, A and Shift in one frame, which from the snapshot reads exactly like Ctrl+Shift+A.
Every event is reported once, as with World.ReadText; repeats and keys the engine does not name are left out.
ReadFileDrops
public IReadOnlyList<FileDrop> ReadFileDrops()Every file dragged over one of the world's windows, or dropped on one, since the last call to this method, in the order the platform said so.
A drag is a file FileDropKind.Hovered, then FileDropKind.Dropped or FileDropKind.Canceled: one entry for each file as it comes over, one for each as it is let go of, and one cancel when it goes away. What is dropped is named again, so a reader that only wants drops reads only those.
Not where it was let go of. The platform layer does not say, so a reader knows which files and not what they were dropped on; see abyss_core::input::FileDropStream.
Every entry is reported once, as with World.ReadText, and nothing is empty and costs nothing, which is every frame but the one a file arrives in. Empty on a world with no window.
WindowSize
public (float Width, float Height, float Scale)? WindowSize()How big the window is in logical pixels, and how many physical pixels one of those is.
Null until the window exists, which is after the first frame — the window is created when the event loop first runs, not when it is asked for.
Both halves are reported because an interface needs both. Layout happens in logical pixels: that is what a font size means, what a panel width means, and what the cursor position in World.ReadInput already is. The scale is what a rasterizer needs — text drawn at a logical size and then magnified by the display is soft, so a font atlas is built at the physical size and laid out as though it were not.
SetWindowIcon
public bool SetWindowIcon(string path)Puts an icon on the window, and says whether there was a window to put it on.
Parameters
path: The PNG to read.
Returns Whether the window existed and took it.
Exceptions
AbyssException: If the file cannot be read or decoded.
An executable's icon is not its window's icon. The one a file browser shows is a resource the shell reads out of the file; a window shows whatever it was last told to show, and unless something tells it, that is the platform's default. They are two facts that happen to be the same picture.
False means there is no window yet, which is every call before the first frame — the real window is created when the event loop first runs. A caller in a frame loop asks again next frame; it is not an error, because a status code could not tell "too early" apart from "that file is wrong".
PNG, and only PNG. A .ico holds several sizes and a directory over them, which is the shell's arrangement rather than a window's.
SetWindowIconFromExecutable
public bool SetWindowIconFromExecutable()Puts the executable's own icon on the window — the one a build writes into a built game — at the title bar's size and the taskbar's. Returns whether it was set: false before the window exists, so it is asked again on a later frame; elsewhere than Windows there is nothing to set, and it is true.
Exceptions
AbyssException: The executable carries no icon.
EnablePainting
public ulong EnablePainting()Installs the camera painted triangles are drawn by, and the white texture.
Returns The camera entity, which is an ordinary entity and can be moved like one.
Safe to call more than once. Needs assets and not a renderer: with no GPU the camera is inert and the meshes are geometry nobody looks at, and the clipping and vertex building all still happen — which is what makes this testable without a window.
The engine has no idea which library produced the triangles, which is the point of the whole path. Vertices, indices and draw commands carrying a texture and a scissor rectangle are what every immediate-mode library produces, so swapping one for another is not an engine change.
SetPaintTexture
public void SetPaintTexture(uint id, uint width, uint height, ReadOnlySpan<byte> pixels)Puts an RGBA image where batches naming id will find it.
Parameters
id: What batches will name. Any number exceptuint.MaxValue, which the engine reserves.width: Width in pixels.height: Height in pixels.pixels: Exactlywidth * height * 4bytes, red first. Anything else is refused rather than read past.
Replacing an id that already exists keeps the same underlying image, so nothing already drawn with it has to be rebuilt — which is what a font atlas remade at a different size needs.
SetPaintTexture
public void SetPaintTexture(uint id, uint width, uint height, ReadOnlySpan<byte> pixels, bool nearest)SetPaintTexture, its pixels drawn as squares however large it is drawn where nearest says so, rather than smoothed: an image whose Filter Mode is Point, as the Sprite Editor draws it.
Parameters
idwidthheightpixelsnearest
Paint
public uint Paint(ReadOnlySpan<PaintVertex> vertices, ReadOnlySpan<uint> indices, ReadOnlySpan<PaintBatch> batches)Draws one frame of triangles.
Parameters
vertices: Every vertex of the frame.indices: Triangle indices intovertices.batches: The draw commands, in the order they should be drawn. Order is the whole of an immediate-mode interface's z ordering.
Returns How many triangles reached a mesh, which is deliberately not how many were submitted: a clip rectangle removes some and cuts others into more. It is the interface's answer to the question World.VisibleCount answers for the scene, and it is what tells a frame that was clipped away apart from a frame that never arrived.
One crossing for a whole frame of interface, however many controls are in it. That is the same bargain every other bulk path here makes, and it is why a UI library drawing hundreds of controls a frame costs the boundary a constant rather than something that grows with the interface.
PaintDrawCalls
public uint PaintDrawCalls()How many draw calls the last painted frame needed.
One, for an interface using a single texture — which is what one that has not asked for images looks like. It moves when a second texture is used, which is the cheapest way to notice that something has started costing draw calls it does not need to.
Entities
public int Entities(int skip, Span<EntityRow> into, out int total)Fills into with a page of this world's entities.
Parameters
skip: How many entities to pass over before filling the buffer.into: Where the page goes. May be empty to ask only for the total.total: How many entities the world holds altogether.
Returns How many were written.
This walks and sorts every entity in the world. An editor listing a world is inherently doing that; what it must not do is call this every frame on a large one. There is no cheaper answer available — Bevy keeps no index of entities in id order, and the alternative is archetype order, which reshuffles the list whenever anything is retagged.
Everything is reported, including the renderer's camera and light, the editor's own drawing surface and whatever Bevy spawns for itself. That is the truth about what is in the world; an editor that wants to hide some of it needs a rule for which, and there is not one yet.
ComponentsOf
public ComponentId[] ComponentsOf(ulong entity)The components an entity carries, in a stable order.
Parameters
entity
Exceptions
AbyssException: The entity is gone or never existed.
ArchetypeComponents
public ComponentId[] ArchetypeComponents(uint archetype)The components every entity in one archetype carries, in the same order as World.ComponentsOf.
Parameters
archetype: A number fromEntityRow.Archetype.
Exceptions
AbyssException: The number names no archetype this world has built.
The question to ask instead of World.ComponentsOf when the question is about a list. Every EntityRow names its archetype, and every entity carrying the same components names the same one — so what a page of four thousand entities carries is a few dozen of these rather than four thousand of the other.
The answer can be kept for as long as this world lives. Bevy never removes an archetype and never changes what one holds: an entity that gains a component moves to a different archetype. The engine's notes on this call cite the upstream lines that say so.
Requires
public ComponentId[] Requires(ComponentId component)What Bevy puts on an entity along with a component: the components it requires, and what those require.
Parameters
component
Exceptions
AbyssException: The id names nothing.
Bevy's required components — a Transform brings GlobalTransform with it. An editor reads this to hide a marker that came along with something it shows, and to know what else may go when a component is taken off. Asked of a component rather than an entity: the answer is the type's, and every entity carrying it has the same one.
Given
public ComponentGiven[] Given(ulong entity, ReadOnlySpan<ComponentId> roots, ReadOnlySpan<ComponentId> asked)What a load would give each of asked by itself, field by field, were the entity built from roots the way a load builds it: what a scene need not write down.
Parameters
entity: The entity whose values are asked about.roots: What a load adds to it, in the order it adds them.asked: What to answer for: any component, a root or what might come with one.
Returns One answer for each of asked, in order.
Exceptions
AbyssException: The entity is gone, or an id names nothing.
Bevy is asked, not the types' defaults: a requirement can give a value of its own, and one can be registered at run time rather than on the type. So an empty entity is given the roots — one made from bytes as World.StartOf says a load spawns it, any other with its default, as World.AddComponent adds it — what arrives is compared with what the entity holds, one field and one enum at a time, and the entity is taken away again. Its hooks run as they would for a load; one that panics is said in the log, and nothing is given.
Of an enum that differs, what differs is answered too: its variant, with only the fields the load does not give as they are, which is what a scene writes of it and what World.SetChoice takes back. See ComponentGiven.Differences.
Structural, as spawning is: every chunk pointer resolved before this is stale.
StartOf
public byte[] StartOf(ComponentId component)What a new value of a component made from bytes starts as: its own default where the engine declares it with one — a transform is the identity — and for one declared from C# what its field initializers say, else zero.
Parameters
component: A component whose values are made from bytes, seeComponentTraits.PlainData; or a list, whose start is a new item's.
Exceptions
AbyssException:AbyssStatus.ComponentNotPlainDatafor one that is not, whose own type makes it.
What a scene load spawns it with, before it writes what the file says, so a field the file leaves out holds what Given compared it with. The same value World.AddComponent gives it.
SerializesAllFields
public bool SerializesAllFields(ComponentId component)Whether a scene writes every field of a component, even one a load would give the same value: it is marked SerializeAllFieldsAttribute, or its Rust type #[reflect(SerializeAllFields)].
Parameters
component: Which component.
EntityName
public string? EntityName(ulong entity)What an entity is called, or null if nothing named it.
Parameters
entity
Exceptions
AbyssException: The world does not hold that entity.
Bevy's Name, which the engine holds rather than the boundary carrying. See World.SetEntityName.
SetEntityName
public bool SetEntityName(ulong entity, string? name)Gives an entity a name, or takes its name away when name is null.
Parameters
entity: The entity to name.name: What to call it, or null to remove the name.
Returns Whether the entity was there to name.
A name is the one piece of per-entity data that cannot cross as bytes. Everything else here is a row, an offset into a row, or a span over a column; a name is a string that owns a heap allocation and has a destructor, so copying one into a component would produce two owners of one buffer. That is the same problem MeshId exists for, and it gets the same answer — the engine owns the value — with one difference: there is no id to hand back, because a name is the identifier.
Naming moves the entity between archetypes, so it stamps the world's version and any chunk outstanding is stale afterwards. It is not a command: naming is authoring rather than gameplay, and nothing does it from inside a chunk iteration.
ComponentByName
public ComponentId? ComponentByName(string name)Finds the component registered under a name, or null if nothing is.
Parameters
name
The lookup a file needs and a running program does not. Everything inside the process holds a ComponentId: it came back from a registration or off an entity, and it is the cheapest thing to pass around. A name is what survives being written down — a scene saved yesterday says Transform and Spin, and the ids those had in the world that saved them mean nothing in the world reading it.
Engine components are searched first, so a game that declares a Transform of its own does not quietly take over the name the renderer positions entities by. Then components declared from C#, so a name a game's files already use keeps meaning what it meant. Then every component Bevy's type registry knows — Bevy's own and a plugin's — by its short name, or by its full Rust type path where two types share one. A name nothing answers to comes back null rather than throwing: a file may well name a component this game does not have, and that is something to report to whoever is loading it.
ComponentsFormerlyNamed
public IReadOnlyList<ComponentId> ComponentsFormerlyNamed(string name)Every component that says it was called name before: empty for a name no component had.
Parameters
name: The name a file holds.
What a scene asks once nothing answers to a name it holds. A file names a component by its name, so one written before the component was renamed names it as it was. A component declared here says its old name with FormerlySerializedAsAttribute on its struct, and a Rust one with #[reflect(@FormerlySerializedAs("..."))] on its type (abyss_core::hint).
A name World.ComponentByName finds comes first: this is not asked for it, and it can answer a name some other component has now. More than one answer is the caller's to refuse, since nothing says which was meant. What an editor said of a rename comes first (World.SayRenamed), then those declared here, then the engine's, in the order of their type paths.
Only what the code declares now: a type let go of (World.ForgetTypesFrom) says nothing any more. A Rust type's answer is asked once a name, as nothing about a Rust type changes while the world lives.
SayRenamed
public void SayRenamed(string was, string now)Takes the component called was and the one called now as one component, as though its struct said [FormerlySerializedAs(was)]: for an editor that renamed a component in a game's code and in the files that name it, leaving nothing in the code to say what it was called.
Parameters
was: What the component was called.now: What it is called now.
Read where World.ComponentsFormerlyNamed is, once nothing answers to a name: the component by the other name answers it. Both ways, because the code is renamed before it is built again. Until the build declaring the new name has loaded, a file already rewritten to the new name is read into the component by the old one. Once it has, the values under the old name move onto the new one.
For the life of the world. A name renamed again is the same component still, so each name a component had before a build finds it. The names are joined through the old one only: a new name some other rename left behind is the new name of this component, not another name of that one, which an editor had better refuse anyway, as a scene naming it would mean either.
ParentOf
public ulong? ParentOf(ulong entity)Which entity this one is a child of, or null if it is a root.
Parameters
entity
Bevy's ChildOf holds an Entity, which is a niche-optimized integer where not every bit pattern is valid, so its one field is FieldKind.Entity: read, by a system in a chunk as by this, and never written. A parent is changed with CommandBuffer.SetParent, which Bevy keeps the tree whole through.
Place
public Placement Place(ulong entity, ulong parent, ulong before, bool keepWorld)Puts an entity somewhere else in the hierarchy: under parent, or among the entities with no parent for zero, before its sibling before, or last for zero — as the hierarchy does when something is dragged there.
Parameters
entity: What to move.parent: Where to put it, or zero for among the entities with no parent.before: The sibling it goes before there, or zero for last.keepWorld: Whether it keeps where it is in the world.
Returns Where it was, which is what puts it back.
Exceptions
AbyssException:AbyssStatus.InvalidPlacementfor a place it cannot go — under itself or anything under it, before itself or an entity that is not a sibling there, or the engine's own — andAbyssStatus.EntityNotFoundfor an entity that is not there. Nothing moves then.
Where it is in the world stays with keepWorld: its transform is worked out against its new parent's, so that it keeps the same position, rotation and scale in the world as before. Without it the transform is kept as it is, which is what putting an entity back, with the transform it had, wants.
A parent's children are in Bevy's own order, and the entities with no parent in one the engine keeps; see EntityRow.Order.
ReadTransform
public Transform? ReadTransform(ulong entity)An entity's transform, or null for one with none.
Parameters
entity
Exceptions
AbyssException: The entity is not there.
WriteTransform
public void WriteTransform(ulong entity, Transform transform)Writes a whole transform onto an entity, one field at a time, as the engine lets a transform be written: see WriteComponent. What puts an entity's transform back as it was, after a World.Place that did not keep it.
Parameters
entitytransform
Exceptions
AbyssException: The entity is not there, or has no transform.
OrderRoots
public void OrderRoots(ReadOnlySpan<ulong> entities)Puts entities, each with no parent, after every other entity with no parent, in the order given: what a load does with a scene's, in the order its file lists them.
Parameters
entities
Exceptions
AbyssException:AbyssStatus.InvalidPlacementfor one with a parent, or the engine's own, andAbyssStatus.EntityNotFoundfor one that is not there. Nothing is ordered then.
SortAsHierarchy
public void SortAsHierarchy(Span<ulong> entities)Sorts entities into the order a hierarchy lists them: depth first, each entity's children after it in their order, from the entities with no parent in theirs.
Parameters
entities
NameOf
public string NameOf(ComponentId component)What a component is called: the shortest name that finds it again.
Parameters
component
Transform rather than bevy_transform::components::transform::Transform: the full path is right for a log line and wrong for a label. It is the full path only when the short one finds something else — a game declared a component of the same name, or two Rust types share it — because this is also what a scene file writes, and a name that came back as a different component would restore the wrong thing. Empty when the id names nothing.
SizeOf
public int? SizeOf(ComponentId component)How big one value of a component is, or null if the id names nothing.
Parameters
component
LayoutOf
public ComponentLayout? LayoutOf(ComponentId component)Where a component's fields sit, found by id, or null if the engine cannot describe it.
Parameters
component
The counterpart of World.LayoutOf, for a caller that found a component on an entity rather than one it went looking for by name. An inspector is exactly that caller.
null is the ordinary answer for most of what an entity carries — everything Bevy declared and the engine has not adopted describes nothing. That is a fact to show rather than an error: an inspector that names a component and says it cannot read it is right, where one that refused to list it would be hiding what is there.
ReadComponent
public int ReadComponent(ulong entity, ComponentId component, Span<byte> into)Copies one entity's component into into.
Parameters
entitycomponentinto
Returns How many bytes were written.
Exceptions
AbyssException: The entity is gone, does not carry the component, or the buffer is too small.
One crossing for the whole component, after which the caller decodes whatever fields it was told about. Safe for anything, because what comes across is bytes and nothing on either side turns them back into a value.
WriteComponent
public void WriteComponent(ulong entity, ComponentId component, int offset, ReadOnlySpan<byte> bytes)Writes bytes into one entity's component at offset.
Parameters
entitycomponentoffsetbytes
Refused unless the engine can vouch for the bytes. The component must either have been registered through World.RegisterComponent, whose contract is already plain data, or the write must lie entirely inside a field the engine described — where every bit pattern is a valid value. Anything else reports AbyssStatus.ComponentNotWritable.
The rule is narrower than "the component has no destructor", deliberately. An Entity is a niche-optimized integer and a Handle is reference-counted; neither has every bit pattern available, and writing over one from a text box is undefined behavior with a user interface in front of it.
The change is published through Bevy's change detection, so a transform edited here propagates exactly as one written by a system does.
LoadImage
public ImageId LoadImage(string path)Starts loading an image from a file, relative to the asset root.
Parameters
path: Relative to the asset root, with/or\separators.
Exceptions
AbyssException: Assets are not enabled, or the path would escape the asset root.
This returns before the file is read. The id is usable immediately — a material can reference it, an entity can be spawned with it — and World.StateOf says whether anything is in it yet. Bevy draws a fallback texture until the bytes arrive, so a scene built on the first frame becomes correct on the frame the file lands rather than having to wait for it.
Asking for the same path twice gives the same id and loads once. Two ids for one file would be two of everything downstream: two rows in a panel, two textures on the GPU, and an equality test that says a thing is not itself.
A path that would leave the asset root is refused. The root is the only thing standing between a path and the rest of the disk, and a game that loads a name a player typed — a mod, a save slot, a level from a server — would otherwise be handing the filesystem out.
LoadImage
public ImageId LoadImage(ImageAddress image)Starts loading an image by its key — Addresses.Icons.Coin — found by its identity wherever it is, then by its address, and read as its file says: a sprite's pixels per unit and filtering, as a scene that names it has them.
Parameters
image: The key the build wrote for an addressable image.
LoadImage
public ImageId LoadImage(string path, ImportSettings settings)Starts loading an image, read the way its own file says it should be read.
Parameters
path: Relative to the asset root.settings: How the file says it should be read.
Exceptions
AbyssException: Assets are not enabled, the path would escape the asset root, or a setting is one this build does not name.
Everything World.LoadImage says holds. What is added is the color rule, the filtering and the wrap mode — facts about the file rather than about this call, which is what makes passing them here safe: Bevy deduplicates a load by path, so two callers passing two answers for one file would silently get whichever ran first. There is only ever one answer because the answer lives beside the file. See ImportSettings and AssetDatabase.SettingsOf.
ImportSettings.NothingSaid reaches no loader at all, so a file nobody has configured loads exactly as it did before any of this existed.
LoadMesh
public MeshId LoadMesh(string path)Starts loading a mesh from a file and returns the id that will name it.
Parameters
path: A path under the asset root, with a sub-asset label.
Exceptions
AbyssException: Assets are not enabled, or the path would leave the asset root.
The path names a primitive, not a file. glTF is a container — one file holds scenes, nodes, meshes, materials and textures — so a path carries a label saying which piece to take: models/pyramid.gltf#Mesh0/Primitive0. A glTF mesh may have several primitives, one per material, and an entity is drawn with exactly one, so the label goes down to the primitive rather than stopping at the mesh.
What comes back is an ordinary mesh. Same id range as one built with World.CreateMesh, same CommandBuffer.SetMesh to attach it, and nothing downstream asks where the geometry came from. Only the meshes are taken: the file's node graph does not become entities, because what a scene graph is in this engine is a scene file's business rather than glTF's.
Returns before the mesh is read, exactly as World.LoadImage does — the id is usable at once, an entity can be drawn with it, and nothing appears until it has been read out of its model's import. A model is never read from its source, so one asked for before its import is told of (World.UseImportedModel) waits for it. World.StateOf is how anything that cares finds out.
LoadMesh
public MeshId LoadMesh(MeshAddress mesh)Starts loading a part of a model's mesh by its key — Addresses.Models.Door.Meshes.Frame — its model found by its identity wherever it is, then by its address; see World.LoadMesh.
Parameters
mesh: The key the build wrote for a mesh of an addressable model.
LoadMesh
public MeshId LoadMesh(string path, ImportSettings settings)Starts loading a mesh, out of a file read the way that file says it should be read.
Parameters
path: A path under the asset root, with a sub-asset label.settings: How the file says it should be read.
Exceptions
AbyssException: Assets are not enabled, the path would leave the asset root, or a setting is one this build does not name.
Everything World.LoadMesh says holds. A model's settings are its import's, which was made as they say (ModelImporter.Import), so they change nothing here and are only checked.
LoadMaterial
public MaterialId LoadMaterial(string path)Starts loading a material from a file, relative to the asset root.
Parameters
path: Where the material is, relative to the asset root, with its label.
Returns The id the material will be known by.
The path names a material inside a container — models/pyramid.gltf#Material0 — for the same reason a mesh's path names a primitive: a glTF file does not hold a material.
A loaded material is an ordinary material. Its id comes from the same range as one you create, it is attached by the same command, and World.SpecOf describes it in exactly the terms a created one is described in — the engine reads what the file says and builds the material from that description, so what it can say about a surface and what it draws are the same thing. The description is the model's import's, as its prefab draws it.
Returns before the model's import has landed. The id is usable at once and the surface is Bevy's default white until it lands; World.StateOf says which of those you are looking at, and World.SpecOf refuses to describe one that has not arrived rather than describing the placeholder.
LoadMaterial
public MaterialId LoadMaterial(MaterialAddress material)Starts loading a material by its key — a material file's, Addresses.Materials.Stone, or a model's, Addresses.Models.Door.Materials.Wood — found by its identity wherever it is, then by its address. A model's is what its prefab draws it as: the material file its Materials section gives it, where it gives one, which a built game's pack holds in its place.
Parameters
material: The key the build wrote for an addressable material, or a material of an addressable model.
LoadMaterial
public MaterialId LoadMaterial(string path, ImportSettings settings)Starts loading a material, out of a file read the way that file says it should be read.
Parameters
path: Where the material is, relative to the asset root, with its label.settings: How the file says it should be read.
Returns The id the material will be known by.
Everything World.LoadMaterial says holds. No setting a file carries changes a material, and they are passed anyway, as a mesh of the same model is asked for.
StateOf
public AssetState StateOf(ImageId image)How far along an image's load is.
Parameters
image
StateOf
public AssetState StateOf(MeshId mesh)How far along a mesh's load is, or AssetState.NotLoaded for one that was built rather than loaded.
Parameters
mesh
StateOf
public AssetState StateOf(MaterialId material)How far along a material's load is, or AssetState.NotLoaded for one created from a MaterialSpec.
Parameters
material
What is in flight is the description rather than the material: the material exists from the moment it was asked for, and an entity can already be drawn with it.
PathOf
public string PathOf(ImageId image)What file an image id was loaded from.
Parameters
image
PathOf
public string PathOf(MeshId mesh)What file a mesh was loaded from, or empty for one built from vertex data.
Parameters
mesh
The empty string is a fact rather than a failure, and it is the distinction a scene file turns on: a mesh with a path can be written down in a way anything can resolve, and a mesh without one can only be named and supplied again by whoever generated it.
PathOf
public string PathOf(MaterialId material)What file a material was loaded from, or empty for one created from a MaterialSpec.
Parameters
material
The same distinction a mesh's path draws, and a scene file turns on it the same way: a material with a path is written down as that path and stays tied to the model it came from, and one without is written down as its numbers.
CreateMesh
public MeshId CreateMesh(in MeshData data)Creates a mesh from vertex data and returns the id that names it.
Parameters
data
Exceptions
AbyssException: Assets are not enabled, or the vertex data cannot describe a mesh.
The geometry crosses as spans, in one call — no per-vertex marshalling, the same shape as a command buffer's payload. What comes back is a MeshId rather than a handle, because a handle is reference-counted and cannot survive crossing a C ABI as bytes; see MeshId for what that costs.
The data is checked here rather than on the GPU: a mismatched attribute length or an index past the end of the vertex list would otherwise surface frames later, inside wgpu, with nothing in it naming the caller.
UpdateMesh
public void UpdateMesh(MeshId mesh, in MeshData data)Replaces a mesh made by code with other vertex data, whole — as many corners and triangles as it now has — under the same MeshId: every entity drawing it draws the new data from the next frame, its bounds worked out again, and a Mesh Collider 3D of it is made again of it at the next physics step. What a block world does as a chunk changes. Any thread, as World.CreateMesh.
Parameters
meshdata
Exceptions
ArgumentException: The vertex data is not whole triples or pairs.AbyssException: The vertex data cannot describe a mesh,meshnames none, or it is read from a file or is one of the engine's own shapes, which only a mesh of one's own replaces.
The data is checked as World.CreateMesh checks it, and sent whole: a chunk's few thousand corners are cheap to send again. World.MeshRevision says how many times a mesh has been replaced.
MeshRevision
public uint MeshRevision(MeshId mesh)How many times mesh's data has been replaced (World.UpdateMesh) since it was made: 0 for one never replaced, and for an id that names no mesh. Something made of a mesh at one revision — a collider's shape — is of another mesh at the next. Any thread.
Parameters
mesh
CreateMaterial
public MaterialId CreateMaterial(MaterialSpec spec)Creates a material and returns the id that names it.
Parameters
spec
Start from MaterialSpec.Default, not default: a zeroed material is black and fully transparent.
MeshOf
public (MeshId Mesh, MaterialId Material)? MeshOf(ulong entity)What mesh and material an entity is drawn with, or null if it has none.
Parameters
entity
Null is also the answer for an entity carrying a mesh the engine did not create — a plugin's, say. That is a fact rather than a failure: the ids are this world's own naming of its own assets, and a handle that never came through it has no number here.
SpecOf
public MaterialSpec SpecOf(MaterialId material)What a material was created from, as it was described.
Parameters
material
Exceptions
AbyssException: No material has that id.
The engine keeps the spec rather than reading the renderer's copy back, so this is the caller's own intent — what a file should record — rather than whatever a system may have changed the material to since.
UpdateMaterial
public void UpdateMaterial(MaterialId material, MaterialSpec spec)Changes a material that already exists, for everything drawn with it at once.
Parameters
material: Which material.spec: What it should be from now on.
Exceptions
AbyssException: No material has that id, the spec names a texture that does not exist, or itsMaterialSpec.Transparencyis not a rule this build names.
This is the only write in the asset boundary, and the only call in this engine that reaches more than one entity. Everything drawn with the material changes together, because they share the engine's handle rather than each holding a copy of the surface — nothing has to find them, because nothing ever had them.
The whole spec goes across rather than one field, because a MaterialSpec is fifteen numbers and a struct: crossing it whole is one call where a field at a time would be fifteen. Start from World.SpecOf and change what you mean to change.
A material read out of a file stops being that file's the moment this is called. Its path is dropped, so World.PathOf answers empty and a scene records the numbers rather than a path that would discard the edit on the next open; anything still waiting on the file is canceled, so a slow disk cannot undo an edit a frame later.
CopyMaterial
public MaterialId CopyMaterial(MaterialId material)Makes a material that starts as another is, for one entity to look different.
Parameters
material: The material to start from.
Returns The copy's id.
Exceptions
AbyssException: No material has that id, or it was released and has gone.
Every entity drawn with a material shares it, which is why World.UpdateMaterial changes them all. A copy is how one of them gets a surface of its own: copy, put the copy on that entity with CommandBuffer.SetMaterial, and change the copy. Nothing is copied unless somebody asks.
MaterialId shared = context.Assets.MaterialOf(cube)!.Value;MaterialId mine = context.Assets.CopyMaterial(shared);context.Assets.UpdateMaterial(mine, context.Assets.SpecOf(mine) with { Red = 1, Green = 0.2f, Blue = 0.2f });context.Commands.SetMaterial(cube, mine);context.Assets.Release(mine); // the cube keeps it, and it goes when the cube doesWhat is copied is what the material is now, textures and all — the same images, so a copy costs a material and not a texture. A copy of a file's material is that file's material too until somebody changes it: it has the same path, and waits for the file as the original does if the file has not arrived.
MeshCarried
public MeshId? MeshCarried(ulong entity)What mesh an entity carries, material or no material, or null if it carries no Mesh3d: default, 0, for one holding a mesh the engine did not make, or none — as one added from Add Component holds.
Parameters
entity
MeshGeometry
public MeshGeometry? MeshGeometry(MeshId mesh)A mesh's corners and its triangles, three indices into them each, as the engine holds it, imported or made: what a collider of it is made of. null for a mesh not loaded yet, not drawn as a list of triangles, or whose data went to the renderer alone.
Parameters
mesh
Exceptions
AbyssException: The id names no mesh.
MaterialOf
public MaterialId? MaterialOf(ulong entity)What material an entity is drawn with, mesh or no mesh, or null if it has none.
Parameters
entity
Null too for a material the engine did not make — a plugin's, say — which is a fact rather than a failure: see World.MeshOf.
CreateImage
public ImageId CreateImage(int width, int height, ReadOnlySpan<byte> rgba, ImageColor color = Srgb)Makes an image from 8-bit RGBA pixels, row by row from the top left.
Parameters
width: Pixels across, 1 toAssets.LargestImage.height: Pixels down, 1 toAssets.LargestImage.rgba: Four bytes a pixel: red, green, blue, alpha.color: Whether the numbers are colors somebody sees or data.
Exceptions
AbyssException: The pixels are not four bytes for each ofwidthbyheight, or a side is zero or larger thanAssets.LargestImage.
A picture a game draws itself — a minimap, a noise texture, a color ramp — rather than one it reads off a disk. It is an ordinary image: a material's texture slot takes its id, and UpdateImage changes it in place for every material using it.
The pixels are copied, so the span is the caller's again when this returns.
UpdateImage
public void UpdateImage(ImageId image, int width, int height, ReadOnlySpan<byte> rgba)Gives an image new 8-bit RGBA pixels, in place, for every material using it.
Parameters
imagewidthheightrgba
Exceptions
AbyssException: The pixels are not a whole image of that size, no image has that id, or it is a file still being read, whose bytes would land on top of these a frame later.
The size may change. What the numbers are stays what the image was — sRGB stays sRGB and linear stays linear — because the materials using it already treat it as one or the other. So does how it is drawn: a file's point filter, or what World.SetImageSampling said, its mipmaps made of the new pixels.
An image read out of a file stops being that file's, as a material does when it is changed: World.PathOf answers empty from then on.
SetImageSampling
public void SetImageSampling(ImageId image, ImageSampling sampling)Tells an image made from pixels how to be drawn: its filter and wrap, and mipmaps made of its pixels — each the average of the two by two above it, in light, weighted by how much shows, so a cut-out's clear texels do not darken its edges. Kept for every pixels UpdateImage gives it after, its mipmaps made of them again; an image made from pixels starts blended, tiled and with no mipmaps.
Parameters
imagesampling
Exceptions
AbyssException: No image has that id, it is a file still being read, it was read from a file (whose import settings say how it is drawn), or the filter, wrap or anisotropy is none there is.
PixelsOf
public ImagePixels PixelsOf(ImageId image)An image's pixels, its first level, four bytes a texel: a texture a game composes into another, or reads a map out of. A compressed import is decoded from its blocks, so what is read is what is drawn, in the editor and in a built game alike — import a texture Uncompressed to read the very pixels it was painted with. One channel reads as its red.
Parameters
image
Exceptions
AbyssException: No image has that id, or it is still being read — awaitGameCode.Loadedfirst.
Release
public void Release(MeshId mesh)Lets go of a mesh: it stays while anything is drawn with it, and its id with it.
Parameters
mesh
Exceptions
AbyssException: It was let go of already, or the world never gave out that id.
The world keeps what it gave an id to, so the number goes on meaning something. This says the caller no longer needs it: the world stops keeping it, and whatever else holds it still does. When the last of those goes — the entities drawn with it despawned, or given another — the asset goes too, as the frame ends, and from then on the id is refused with an error saying it was released, and World.StateOf answers AssetState.Unloaded.
So a level can let go of everything it loaded, and what another level still draws with stays; and letting go of what a game made while it played, which Stop does for it, takes nothing a scene is drawn with.
Release
public void Release(MaterialId material)Lets go of a material: it stays while anything is drawn with it. See World.Release.
Parameters
material
Exceptions
AbyssException: It was let go of already, or the world never gave out that id.
The ordinary use: copy a material, put the copy on an entity and let go of it at once — the entity keeps it, and it goes when the entity does. See World.CopyMaterial.
Release
public void Release(ImageId image)Lets go of an image: it stays while a material uses it. See World.Release.
Parameters
image
Exceptions
AbyssException: It was let go of already, or the world never gave out that id.
NameMesh
public void NameMesh(string name, MeshId mesh)Gives a mesh a name, so something outside this process can refer to it.
Parameters
namemesh
Exceptions
AbyssException: No mesh has that id, or the name is empty, or it is one of the engine's own primitives' names —Cube,Sphere,Capsule,Cylinder,Plane,Quad— which a scene finds the engine's by (World.MeshByName).
Meshes, and only meshes, because a mesh is the one asset kind that can be neither described nor found again. An image has a path, which names a file that will still be there tomorrow; a material is six numbers and a texture, so it can be written down in full. A mesh is vertex data somebody generated — an id naming it means nothing in another process, and the bytes are in no file. So anything that refers to one from outside refers to it by name, and whoever assembles the world supplies it.
Naming is per-kind rather than general, and that is forced: mesh ids and material ids are both indices from zero into lists of their own, so the number 4 names one of each.
MeshByName
public MeshId? MeshByName(string name)The mesh a name refers to, or null if nothing named one.
Parameters
name
Null rather than an exception: a scene naming a mesh this world was never given is a thing to report to whoever is loading it, not a reason to fail.
The engine's primitives are always given, in a world with assets: Cube, Sphere, Capsule, Cylinder, Plane and Quad, each made the first time it is asked for and the same one after that. So a scene naming one opens in any world, a built game's included.
NameOfMesh
public string? NameOfMesh(MeshId mesh)What a mesh is called, or null if nothing named it.
Parameters
mesh
ImageByName
public ImageId? ImageByName(string name)The image of one of the engine's shapes — Square, Circle, Capsule, Triangle or Hexagon — or null for any other name.
Parameters
name
White, 128 pixels across, made the first time a world with assets is asked for it and the same one after that, as the engine's meshes are (World.MeshByName); so a scene naming one opens in any world, a built game's included.
NameOfImage
public string? NameOfImage(ImageId image)What an image is called — the name of the engine's shape it is — or null.
Parameters
image
SpriteImage
public ImageId? SpriteImage(ulong entity)What image an entity's sprite draws, or null if it carries no Sprite: default, 0, for none, and for one the engine did not make or read.
Parameters
entity
SpriteSize
public Vector2? SpriteSize(ulong entity)The size an entity's sprite takes from its image, in world units, whatever size it is given — the pixels of its rectangle of the image, its cell of an atlas, or the whole image, over the image's Pixels Per Unit; zero for an image not read yet — or null if it carries no Sprite.
Parameters
entity
SetSpriteImage
public bool SetSpriteImage(ulong entity, ImageId image)Has an entity's sprite draw image — default for none — giving it a Sprite if it carries none; false where the entity is gone.
Parameters
entityimage
The image alone: the sprite's color, size and the rest stay. A scene keeps the image as one of the sprite's choices, image, which World.SetChoice writes by the file it names.
IsEngineComponent
public bool IsEngineComponent(ComponentId component)Whether the component is one the engine declares itself.
Parameters
component
What makes World.EngineComponent willing to bind a mirror to it. Whether writes have to be published is a wider question — Bevy's and a plugin's components are watched too — and World.TraitsOf answers it.
TraitsOf
public ComponentTraits TraitsOf(ComponentId component)What a component is; ComponentTraits.None if the id names nothing.
Parameters
component
One crossing for the three things a caller has to know before touching a component: whether Rust code might be watching it, so writes must be published through Bevy's change ticks; whether a value of it can be made from bytes; and whether it is the engine's own. See ComponentTraits.
AddComponent
public bool AddComponent(ulong entity, ComponentId component)Puts a component on an entity with a starting value, and reports whether it did.
Parameters
entitycomponent
Exceptions
AbyssException:AbyssStatus.ComponentHasNoDefaultfor a Rust type without#[reflect(Component, Default)], or the entity is gone.
What Add Component does: the component, as its author said a new one should be. For a component with a Rust type — Bevy's, a plugin's — that is the type's own default, reached through Bevy's type registry, and whatever the type requires comes with it: a light brings the transform it cannot be drawn without. For one declared from C#, whose values are plain data with no constructor to call, it is zeroes.
This is how a Bevy or plugin component gets onto an entity from C#. A spawn or an add through a command buffer carries values as bytes, and bytes are not a value of a type that holds a handle, an enum or a string — so those refuse with AbyssStatus.ComponentNotPlainData. Add it here, then write the fields the engine describes.
An entity that already carries the component is left as it is and this returns false: a default replacing something somebody set is a loss nobody asked for. A structural change either way it went, so chunks resolved before it are stale.
RemoveComponent
public bool RemoveComponent(ulong entity, ComponentId component)Takes a component off an entity, and reports whether it was there to take.
Parameters
entitycomponent
Exceptions
AbyssException: The entity is gone, or the id names a resource or nothing.
Only that component. What it required stays — Bevy put it there alongside, and something else on the entity may need it too — so taking Transform off leaves its GlobalTransform. A structural change when it removed something, so chunks resolved before it are stale.
AddableComponents
public IReadOnlyList<AddableComponent> AddableComponents()Every component that could be put on an entity with World.AddComponent, by the name that finds it again — what the Add Component list offers.
Bevy's and every plugin's components that Bevy's type registry can make a value of, whether or not anything carries one yet, and every component declared from C#. Not what Bevy works out for itself, which nobody adds. Sorted by name; a component with a C# type, from any crate, is listed as coming from game.
About
public EngineAbout About()What the editor's Help ▸ About says of the engine this world runs: the Bevy it is built on, and the graphics adapter its renderer chose and the API it draws through, none for a world that draws nothing.
ChoicesOf
public IReadOnlyList<ComponentChoice> ChoicesOf(ComponentId component)The enums a component holds, which its layout cannot describe.
Parameters
component: Which component.
Exceptions
AbyssException: The id names no component.
Empty for a component declared from C#, which holds no enum, and for one Bevy's registry cannot reach. What a component holds cannot change while the world lives, so a caller asking often can keep the answer. See ComponentChoice.
ComputedFieldsOf
public IReadOnlyList<string> ComputedFieldsOf(ComponentId component)The paths of the fields inside a component that Bevy works out for itself, each covering everything under it — computed for a camera, which is also computed.clip_from_view.x_axis.x — and none for most. One inside an enum is named as a scene writes it, the enum's path, the variant, then the field: a projection's Perspective.aspect_ratio, Bevy's while the projection is a perspective one.
Parameters
component: Which component.
Exceptions
AbyssException: The id names no component.
The same question ComponentTraits.Computed answers for a whole component, one level down: a camera's is_active and order are somebody's to set, and beside them is what Bevy recomputes from them at every frame. A scene leaves those out, and an inspector shows them and does not let them be edited. See World.IsComputedField.
What a component holds cannot change while the world lives, so the answer is kept.
IsComputedField
public bool IsComputedField(ComponentId component, string path)Whether a field of a component — a path its layout or its enums name, or one inside an enum's variant — is one Bevy works out for itself; see World.ComputedFieldsOf.
Parameters
component: Which component.path: The field's path, dotted through any nesting.
ChoicesIn
public IReadOnlyDictionary<string, string> ChoicesIn(ulong entity, ComponentId component)The value of every enum an entity's component holds, by path, as JSON as Bevy's reflection writes it.
Parameters
entity: The entity.component: Which of its components.
Exceptions
AbyssException: The entity is gone (AbyssStatus.EntityNotFound) or does not carry the component.
A value the engine cannot write out — one holding an asset handle — is left out. Each value is the text as the engine wrote it, so a color's fields stay in the order its type declares them.
SetChoice
public void SetChoice(ulong entity, ComponentId component, string path, string value)Sets the enum at path in an entity's component to a value written as JSON, as Bevy's reflection writes one: another variant, or the same holding other values.
Parameters
entity: The entity.component: Which of its components.path: Where the enum is, asComponentChoice.Pathsays.value: The value, as JSON.
Exceptions
AbyssException:AbyssStatus.ChoiceNotFoundfor a path that names no enum,AbyssStatus.InvalidChoicefor a value that is not one of it, or the entity errors.
The component is marked changed the way any write through Bevy marks it, so whatever watches it sees it — a Visibility set to "Hidden" hides the entity and what is under it.
The value may leave fields out, as a scene writes one: the variant the enum holds keeps what it held of them, and another starts as choosing it starts it, from its fields' defaults (ChoiceVariant.Value). A variant with no such value has to be given whole.
TakeComponents
public int TakeComponents(ulong entity, ReadOnlySpan<ComponentId> components, ulong token)Takes components off an entity and keeps them under token, so that World.PutBackComponents can put them back as they were.
Parameters
entitycomponentstoken
Returns How many it took.
Exceptions
AbyssException: The entity is gone.
What an undo of Remove Component needs: a component is not only numbers — a Mesh3d is an asset handle — so the engine keeps each value whole, through reflection or as its bytes. Components the entity does not carry are passed over; taking again under the same token replaces what was kept. A structural change when it took anything.
PutBackComponents
public int PutBackComponents(ulong entity, ulong token)Puts back on an entity what TakeComponents kept under token, as it was — and keeps it, so an undo can be redone and undone again.
Parameters
entitytoken
Returns How many it put back: none for a token nothing is kept under.
Exceptions
AbyssException: The entity is gone.
TakeEntities
public TakenEntities TakeEntities(ulong entity, ulong token)Takes an entity and everything under it out of the world, kept under token so that World.PutBackEntities can put them back as they were: what the hierarchy's Delete does.
Parameters
entitytoken
Returns Where it was, and how many entities went.
Exceptions
AbyssException:AbyssStatus.InvalidPlacementfor the engine's own, which nobody takes out of the world, andAbyssStatus.EntityNotFoundfor an entity that is not there. Nothing is taken then.
Every value each held is kept whole, as Stop keeps a world's (Snapshot), and how they hang together, and then they are despawned. Taking again under the same token replaces what was kept. A structural change.
KeepEntities
public TakenEntities KeepEntities(ulong entity, ulong token)Keeps an entity and everything under it under token, as World.TakeEntities does, and leaves them in the world: what World.PutBackEntities then spawns is a copy of them, which is what the hierarchy's Duplicate makes.
Parameters
entitytoken
Returns Where it is, and how many entities were kept.
Exceptions
AbyssException: AsWorld.TakeEntities; nothing is kept then.
An entity inside a value that points at one of them points, in the copy, at its copy; one that points elsewhere points where it did. Keeping again under the same token replaces what was kept; World.ForgetEntities lets go of it. Not a structural change.
ForgetEntities
public bool ForgetEntities(ulong token)Lets go of what World.TakeEntities or World.KeepEntities kept under token, and of the assets its values held with it.
Parameters
token
Returns Whether anything was kept under it.
PutBackEntities
public IReadOnlyList<(ulong Was, ulong Is)> PutBackEntities(ulong token)Puts back what World.TakeEntities kept under token, each as a new entity, and keeps it, so what is put back and taken again can be put back again.
Parameters
token
Returns Each as its old id and its new one, the one taken first first; none for a token nothing is kept under.
Bevy gives an id out once, so each comes back as another entity, as one a game despawned comes back on Stop; an entity inside a value that went with it is the one it is now, an EntityRef of a C# component's among them. What names one of them from outside still names what it did: an original a duplicate copied, or, where they were taken away, what is gone, which Repoint points at them. The one taken first has no parent until World.Place gives it one. A structural change.
ReportTaken
public TakenReport ReportTaken(ulong token)What World.TakeEntities keeps under token; nothing for a token nothing is kept under.
Parameters
token
SetActive
public bool SetActive(ulong entity, bool active)Switches an entity on or off, and everything under it with it.
Parameters
entity: The entity to switch.active: On, or off.
Returns Whether that changed anything: false when it was already so.
Exceptions
AbyssException: The entity is gone.
Off is Bevy's Disabled on the entity: no query that does not ask for it sees it, a C# system's included, so nothing updates it and nothing draws it. And what is under it goes with it — the engine keeps DisabledByParent on every descendant, which queries leave out the same way — and comes back with it, except what was switched off itself.
A structural change either way, so chunks resolved before it are stale.
IsActiveSelf
public bool IsActiveSelf(ulong entity)Whether the entity itself is switched on, whatever is above it. What its checkbox shows.
Parameters
entity
Exceptions
AbyssException: The entity is gone.
IsActiveInHierarchy
public bool IsActiveInHierarchy(ulong entity)Whether the entity is switched on and so is everything above it. Whether it is updated and drawn.
Parameters
entity
Exceptions
AbyssException: The entity is gone.
VisibilityOf
public EntityVisibility? VisibilityOf(ulong entity)Whether an entity is drawn, as Bevy's Visibility on it says: Inherited, Hidden or Visible; null for one that carries none, which Bevy draws as Inherited.
Parameters
entity
Exceptions
AbyssException: The entity is gone.
SetVisibility
public bool SetVisibility(ulong entity, EntityVisibility? visibility)Sets whether an entity is drawn: Bevy's Visibility, given it where it has none, or taken off for null.
Parameters
entity: The entity.visibility: Whether it is drawn, or null to take itsVisibilityoff.
Returns Whether that changed anything: false when it was already so.
Exceptions
AbyssException: The entity is gone.
Hidden hides it and everything under it set to Inherited; Visible draws it even under a hidden parent. Hidden only stops it being drawn: its systems still see it and update it, as they do not one switched off (World.SetActive).
HiddenBy
public ulong? HiddenBy(ulong entity)What above an entity hides it: the nearest set Hidden, unless one set Visible comes first; null where nothing above it does. Whatever the entity itself is set to.
Parameters
entity
Exceptions
AbyssException: The entity is gone.
Transform
public ComponentType<Transform> Transform()The local transform, bound to this world.
Exceptions
InvalidOperationException: The managed mirror and the engine disagree about where a field is. That is a build to stop, not a condition to handle: reading through the mirror would misread every entity.
Bevy's Transform. The mirror's every offset is checked against the table the engine recovered from the Rust compiler the first time this is called, because the Rust type is #[repr(Rust)] and the compiler does not keep the declared order — see Transform for what it actually chose.
Remember that a spawned transform is zeroed, not the identity.
GlobalTransform
public ComponentType<GlobalTransform> GlobalTransform()The world-space transform, bound to this world.
Bevy's GlobalTransform, which is an affine matrix rather than a second Transform. Written by Bevy's propagation during World.RunBevyFrame; read it, do not write it. Checked the same way as World.Transform.
Spawn
public void Spawn(int count, params ReadOnlySpan<ComponentId> components)Spawns count zero-initialized entities, each carrying every listed component.
Parameters
countcomponents
Values start at zero because a component declared from C# has no native constructor to call. Fill them by writing through the chunk spans afterwards.
CreateQuery
public Query CreateQuery(params ReadOnlySpan<QueryTerm> terms)Creates a query over the given terms. Column order follows term order.
Parameters
terms
CreateQuery
public Query CreateQuery(ReadOnlySpan<QueryTerm> terms, ReadOnlySpan<QueryFilter> filters)Creates a query over the given terms, narrowed by presence filters.
Parameters
termsfilters
Filters do not produce columns, so column indices still follow terms. Stating disjointness through filters is what lets two writers of the same component be recognized as compatible rather than serialized — see QueryFilter.
CreateArchetype
public Archetype CreateArchetype(params ReadOnlySpan<ComponentId> components)Registers a component set that entities can be created with, given, or stripped of at runtime.
Parameters
components
Registered up front rather than named per command, so the components are validated once at setup instead of on every frame that changes something.
CreateCommandBuffer
public CommandBuffer CreateCommandBuffer()Creates a command buffer that records against this world.
Unrestricted, because there is no system here whose declaration it could be held to. This is the ad-hoc path — the same standing the raw query API has against the conflict analysis. A buffer handed to a system by the schedule is held to what that system declared.
Apply
public CommandOutcome Apply(CommandBuffer commands)Applies a command buffer recorded outside a schedule.
Parameters
commands
Systems get this for free — the schedule applies each system's buffer after the frame. This is the equivalent of the ad-hoc query API, for setup code and tests.
RegisterResource<T>
public ResourceType<T> RegisterResource<T>(string? name = null) where T : unmanagedRegisters T as a resource type — singleton data with no entity.
Type parameters
T
Parameters
name: What it is called; defaults to the type's name.
This does not supply a value; call World.InsertResource for that. The same plain-data rule as components applies, enforced by the unmanaged constraint: the engine never runs a destructor for a resource.
Once a type and a name. Registering a type registered already under that name gives back the resource it was registered as, so a plugin built at every Play — the editor builds one each time — can register what it keeps as it is built, and keep one resource rather than one a Play: Bevy gives a new id to every registration (bevy_ecs 0.19.1, src/component/register.rs:291) and never takes one back. A game's scripts built again are other types, so a resource whose fields changed is registered afresh; and one type under two names is two resources, as two counters of one shape are.
Resource<T>
public ResourceType<T> Resource<T>(string? name = null) where T : unmanagedThe resource T was registered as under a name; see World.RegisterResource.
Type parameters
T
Parameters
name: What it was called; defaults to the type's name.
Exceptions
InvalidOperationException:Tis not registered as a resource under that name in this world.
InsertResource<T>
public void InsertResource<T>(ResourceType<T> resource) where T : unmanagedGives the resource a zero-initialized value, replacing any existing one.
Type parameters
T
Parameters
resource
Invalidates outstanding chunk pointers: the first insertion spawns the entity that holds the value, which is a structural change like any other.
RemoveResource<T>
public bool RemoveResource<T>(ResourceType<T> resource) where T : unmanagedRemoves the resource's value. Returns whether there was one.
Type parameters
T
Parameters
resource
HasResource<T>
public bool HasResource<T>(ResourceType<T> resource) where T : unmanagedWhether the resource currently holds a value.
Type parameters
T
Parameters
resource
ResourceValue<T>
public ref T ResourceValue<T>(ResourceType<T> resource) where T : unmanagedReads and writes a resource outside a system.
Type parameters
T
Parameters
resource
Exceptions
AbyssException: Borrow checking is on and something else holds the resource.
Returns a reference into native memory, so the value is written in place. Valid until the world changes shape. Systems should declare resource access and take Res<T>/ResMut<T> instead, so the scheduler can reason about who touches what; this is the equivalent of the ad-hoc query API.
When World.BorrowChecking is on this takes an exclusive borrow and gives it back before returning, which makes the check a point in time rather than a scope: it refuses the call while a system holding the resource is running, and says nothing about what happens to the returned reference afterwards. That limit is forced by the return type — a ref T can outlive any scope this method could impose. Use World.BorrowResource where the borrow needs to last as long as the reference.
BorrowResource<T>
public ResourceBorrow<T> BorrowResource<T>(ResourceType<T> resource) where T : unmanagedTakes an exclusive borrow of a resource and holds it until the borrow is disposed.
Type parameters
T
Parameters
resource
Exceptions
AbyssException: Borrow checking is on and something else holds the resource.
The resource counterpart of using var chunks = query.Resolve();, and it exists for the same reason: a borrow has to end somewhere, and the end of the scope holding the reference is the only place that is both correct and obvious. Prefer this to World.ResourceValue whenever the reference is kept for more than one statement.
RegisterSystem
public SystemId RegisterSystem(string name, ReadOnlySpan<QueryTerm> terms, ReadOnlySpan<QueryFilter> filters = null, ReadOnlySpan<ResourceTerm> resources = null)Declares a system by the access it will take, so the engine can reason about it before it ever runs.
Parameters
name: Display name, used in conflict diagnostics.terms: The components the system reads and writes.filters: Presence constraints narrowing which entities it applies to.resources: The resources the system reads and writes.
The terms and filters are validated exactly as a query's would be, so a system whose shape a query would reject is refused here rather than mid-frame.
ClearSystems
public void ClearSystems()Removes every registered system. Ids are not stable across this call.
ClearSystemsAfter
public void ClearSystemsAfter(int count)Removes every system registered after the first count, and keeps those with their ids.
Parameters
count
Exceptions
ArgumentOutOfRangeException:countis negative.
What an editor does at Stop: the systems the game registered at Play go, and the ones from before — the engine's own and what always runs — stay, so a schedule built over them still names them. Take the count from World.SystemCount before registering what is to go. The engine's own systems stay whatever the count.
AreCompatible
public bool AreCompatible(SystemId first, SystemId second)Whether two systems may be in flight at the same time.
Parameters
firstsecond
ComputeSystemConflicts
public IReadOnlyList<SystemConflict> ComputeSystemConflicts()Computes the conflict graph over every registered system.
Systems not joined by a returned conflict may run concurrently. The result is a graph rather than a set of stages on purpose: an executor working from a graph can start any system whose neighbors are idle, where stage barriers force everything to wait on the slowest member of each stage.
This allocates and is meant to be called when the schedule is built or reloaded, not per frame.
Tick
public void Tick()Advances the world's change tick, delimiting one frame.
RunBevyFrame
public bool RunBevyFrame()Runs one frame of Bevy's schedule — everything Bevy's own plugins install.
Returns false if a plugin is still starting up and no frame ran. That is a fact to act on, not a failure: try again next frame. Nothing reaches this state until a plugin with asynchronous initialization is installed, which in practice means the renderer.
This does not run the managed Schedule, and the managed schedule does not run this. A frame that wants both calls both, in whichever order the game wants them — the engine takes no view, because what a frame is belongs to the host.
Every outstanding chunk is stale afterwards. A plugin's systems may spawn, despawn or move entities between tables, and asking which would be guessing, so the world's version is stamped unconditionally.
WindowHandle
public (WindowHandleKind Kind, ulong Handle)? WindowHandle()The operating system's handle for this world's window, and which kind it is.
Returns The handle and its kind, or null if there is no window yet.
So an editor can put the game inside itself. A docked viewport is the engine's own window reparented into one of the editor's controls — which keeps the platform compositing it: no texture upload per frame, no input path to rebuild, and the editor's toolkit keeps its own text entry, scrolling and accessibility.
There is no window until the loop has run a frame. Bevy creates the real window when its runner first runs, not when the plugin is added, so ask from inside the frame callback rather than before RunFrameLoop.
RendererDescription
public string RendererDescription()Describes the GPU the renderer is running on, or an empty string until its device is built.
Worth asking, and worth printing. A cleared window is weak evidence: a renderer that failed to get a device, one that fell back to software, and one on the machine's real GPU all look alike from outside. This is also the first question anyone asks when a game runs well on one machine and badly on another.
SetClearColor
public void SetClearColor(float r, float g, float b, float a = 1)Changes the color the window is cleared to each frame: red, green, blue and alpha in sRGB, zero to one, as a person picks a color. The sky behind a scene; a camera's fog of the same color (World.SetFog) makes the two one.
Parameters
rgba
Callable from inside the frame callback, which is what makes it useful: it is the smallest thing a game can change per frame and watch happen on screen, so it is what says the render path is live rather than merely started.
RunFrameLoop
public int RunFrameLoop(Func<float, bool> frame, Action<float>? fixedStep = null)Hands the frame loop to Bevy, calling frame once per frame until it returns true or Bevy exits.
Parameters
frame: The game's frame, receiving the seconds that really passed since the previous one; the game's own — paused, scaled — areGameTime.DeltaTimeofWorld.Time, read as the frame starts. Everything a host-driven loop did per frame goes in here —Schedule.Run, command application, the lot. Returntrueto ask the loop to stop.fixedStep: The game's fixed systems, if it has any: called once for each step of the game's fixed clock, from Bevy'sFixedUpdate, before the frame'sframe, with the step —Schedule.RunFixed. An exception thrown by it stops the loop as one thrown byframedoes.
Returns The process exit code Bevy settled on; 0 for a clean exit.
Why give up the loop. A window is not optional about owning it: Bevy's windowing and rendering live inside an event loop that takes the thread. So the frame stops being a call the host makes and becomes one it receives. Nothing else changes — this world is fully usable from inside frame, the same as from a loop of your own.
It does not return until the loop ends, and then the world is gone. Bevy's App::run moves the app into its runner and never gives it back, so afterwards every call on this world fails with AbyssStatus.AppExited and World.Dispose is all that is left. That is Bevy's contract for a windowed app, not a choice made here.
Exceptions stop the loop. An exception must not unwind into Rust, so one thrown by frame is caught, the loop is asked to end, and it is rethrown from here once the loop has unwound. A frame that throws every frame therefore stops the game rather than spinning — the opposite of how a system that throws is treated, because there is no other frame to carry on with.
So does a panic. A call made from frame that panics inside the engine poisons the world, and the engine ends the loop after that frame whatever the frame returns. This then throws an AbyssException with AbyssStatus.Poisoned, whose message says what the panic was and where.
In a browser it returns as the loop starts, with 0: the page draws the frames, and calls the game for each between giving its thread to everything else on it. The world is alive and running then (World.LoopOnPage), and so is everything the frames use; an exception thrown by a frame ends the loop and is written to the log, there being no caller left to throw it to.
RefreshVersion
public void RefreshVersion()Re-reads the structural version from the native core.
Only needed if the world was changed other than through this class, by Rust. Ordinary gameplay code never calls this.
Dispose
public void Dispose()Destroys the world. Every chunk pointer taken from it becomes dangling.
RecordProfile
public void RecordProfile(bool recording)Starts recording the engine's side of each frame's time, what was kept before forgotten, or stops it. Nothing is timed until the frame loop runs.
Parameters
recording
ProfileFrame
public ulong? ProfileFrame()The number of the frame being timed, which TakeProfiledFrames gives later; null while none is.
TakeProfiledFrames
public int TakeProfiledFrames(Span<ProfiledFrame> into)Takes the frames timed and not taken yet, oldest first, as many as into holds.
Parameters
into
Returns How many it took.
TakeProfiledRenders
public int TakeProfiledRenders(Span<ProfiledRender> into)Takes the render thread's drawings timed and not taken yet, oldest first, as many as into holds.
Parameters
into
Returns How many it took.
ProfilePartName
public string ProfilePartName(ProfilePart kind, int index)What part index of a profile is called; empty for one past them.
Parameters
kindindex
CreateScene
public SceneId CreateScene()Makes a scene with nothing in it, called Untitled, from no file.
CreateScene
public SceneId CreateScene(string name, string path)Makes a scene with nothing in it.
Parameters
name: What it is called: its file's name, as the hierarchy shows it.path: The file it is read from or will be written to; empty for none.
SceneOf
public SceneId SceneOf(ulong entity)The scene an entity is in: SceneId.None for one in none, and for one that has gone, since the caller did not choose when it died.
Parameters
entity
Scenes
public SceneId[] Scenes()Every scene there is, in the order they were made.
EntitiesIn
public ulong[] EntitiesIn(SceneId scene)Everything in a scene, children included, in the order each joined it, or in tree order once World.SortSceneByTree has put it so.
Parameters
scene
Exceptions
AbyssException: The entity is not a scene.
SceneName
public string SceneName(SceneId scene)What a scene is called: its file's name, or Untitled for one never saved.
Parameters
scene
Exceptions
AbyssException: The entity is not a scene.
ScenePath
public string ScenePath(SceneId scene)The file a scene was read from or last written to; empty for one never saved.
Parameters
scene
Exceptions
AbyssException: The entity is not a scene.
SceneSavedAs
public void SceneSavedAs(SceneId scene, string name, string path)Says a scene was written to path, and calls it name from now on.
Parameters
scenenamepath
Exceptions
AbyssException: The entity is not a scene.
UnloadScene
public int UnloadScene(SceneId scene)Unloads a scene: despawns it, and with it everything in it, children included.
Parameters
scene
Returns How many entities were in it.
Exceptions
AbyssException: The entity is not a scene.
IsSceneLoading
public bool IsSceneLoading(SceneId scene)Whether a scene is loading: everything in it left out of every query until it is shown.
Parameters
scene
Exceptions
AbyssException: The entity is not a scene.
SceneLoader loads a scene this way, a slice at a time, and shows it all at once when it is built; see World.SetSceneLoading.
SetSceneLoading
public int SetSceneLoading(SceneId scene, bool loading)Switches a scene to loading, or shows it: everything in it at once.
Parameters
sceneloading
Returns How many entities are in the scene.
Exceptions
AbyssException: The entity is not a scene.
Loading, everything in the scene is left out of every query — a game's systems, Bevy's and the renderer's — as an entity switched off is, and so is whatever is put in it after: spawned into it, moved into it or put under something in it. Shown, the loader's marker comes off everything in it, and only that: what the scene switched off itself stays off.
The loader's to call (SceneLoader), which builds a scene loading and shows it when it is built, and switches one back before it despawns it a slice at a time.
Constants
LinePoints
public const string LinePoints = "points"Where a Line keeps its points among its choices.
MaxPlayers
public const int MaxPlayers = 8How many players a game can have.
