Scripting API
Scripting API
AssetAccess
Struct in Abyss.Core, from Abyss.Core.
What a running system can do with the world's assets: load, make, copy, change and let go of them. Reached through SystemContext.Assets. A file is loaded by its key, which the build writes for each addressable asset and each shader, Addresses.Pyramid, or by its identity.
public readonly struct AssetAccessRemarks
The asset half of a world, and only that half. A system body is never handed the world — spawning in the middle of a frame would move the tables its chunks point into — and an asset is in no table, so this is the part that is safe to reach while systems run. Each call is the world's own, under the lock the world holds round every asset call, so two systems running in parallel may both use it.
Giving an asset to an entity is not here: that changes the entity, and is CommandBuffer.SetMesh or CommandBuffer.SetMaterial.
Methods
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.
Parameters
image: The key the build wrote for an addressable image.
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.
Parameters
mesh: The key the build wrote for a mesh of an addressable model.
LoadMaterial
public MaterialId LoadMaterial(MaterialAddress material)Starts loading a material by its key — Addresses.Materials.Test — found by its identity wherever it is, then by its address.
Parameters
material: The key the build wrote for an addressable material.
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.
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.
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
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.
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.
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
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.
LoadShader
public ShaderId LoadShader(ShaderAddress shader)Reads a shader by its key — Shaders.Glow — found by its identity wherever it is, then by its path in the shaders folder; see World.LoadShader.
Parameters
shader: The key the build wrote for one of the game's shaders, or a package's.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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)Parameters
widthheightrgbacolor
UpdateImage
public void UpdateImage(ImageId image, int width, int height, ReadOnlySpan<byte> rgba)Parameters
imagewidthheightrgba
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.
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.
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.
Parameters
prefab: The key the build wrote for an addressable prefab or model.
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.
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.
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
LoadPrefabs
public IReadOnlyList<PrefabId> LoadPrefabs(LabelName label)Starts loading every addressable prefab and model carrying a label, by the label's name the build wrote — Labels.Animals; see World.LoadPrefabs.
Parameters
label: The label.
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.
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.
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
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
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
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
