Scripting API
Scripting API
UiElement
Class in Abyss.Core, from Abyss.Core.
An element of a shown UI document: the entity its document's element became, found by the identity the document gave it. What a document's class names each of its elements as.
public sealed class UiElementRemarks
One for each element of each document shown, made as it is shown, so a class's Title.Text = "Paused"; is the element's own text set.
Properties
Entity
public ulong Entity { get; }The entity it is; zero for none — an element its document no longer has.
Exists
public bool Exists { get; }Whether it is there.
Material
public MaterialId? Material { get; set; }The material it is drawn with — above its background and its image, below its text — or null for none. Set, it is drawn with that one: a material running a UI shader, which one shared by several elements draws for all of them; World.CopyMaterial gives one element values of its own.
Exceptions
InvalidOperationException: The element is not there.ArgumentException: The material runs Bevy's own surface, which draws no UI element.
Text
public string Text { get; set; }What it says; empty for one with no text. Set, it says that, and an element with no text is given some.
Exceptions
InvalidOperationException: It is not there.
Read, it is a string made for the asking; to set text that changes every frame, see UiElement.SetText.
Items
public IReadOnlyList<UiView> Items { get; }The template instances made under this element, in the order they were made; see UiElement.Add.
WasClicked
public bool WasClicked { get; }Whether it was clicked since the frame before: asked from a system as a key is.
WasPressed
public bool WasPressed { get; }Whether it was pressed down by the mouse since the frame before, let go of or not: asked from a system as a key is.
Focused
public bool Focused { get; }Whether it has the interface's focus: what the keyboard and the gamepad press.
Checked
public bool Checked { get; set; }Whether it is on, for a toggle: set, it is turned on or off, and its class is not told — the code setting it knows. False for what is no toggle, which setting leaves as it is.
Exceptions
InvalidOperationException: It is not there, as it is set.
Value
public float Value { get; set; }A slider's value: set, it is moved there, kept in its range, and its class is not told — the code setting it knows. Zero for what is no slider, which setting leaves as it is.
Exceptions
InvalidOperationException: It is not there, as it is set.
Picked
public int Picked { get; set; }A dropdown's picked option, by its place among its options from zero: set, that option is picked — the first for a place below zero, the last where it has fewer — and its class is not told, the code setting it knows. Zero for what is no dropdown, which setting leaves as it is.
Exceptions
InvalidOperationException: It is not there, as it is set.
PickedText
public string PickedText { get; }The words of a dropdown's picked option, as its label says them; empty for what is no dropdown, or has no options.
Options
public IReadOnlyList<string> Options { get; }The words of each of a dropdown's options, in order; none for what is no dropdown.
IsOpen
public bool IsOpen { get; }Whether a dropdown's list is open; false for what is no dropdown.
Methods
SetText
public void SetText(ref UiTextHandler text)Gives it text written as an interpolated string, and makes no string to do it: Score.SetText($"Score: {score}"), Timer.SetText($"{seconds:F1} s").
Parameters
text
Exceptions
InvalidOperationException: It is not there.
The compiler hands each piece to UiTextHandler, which writes it into a buffer it borrows and gives back — a number formatted where it goes, as ISpanFormattable formats one, with its format and alignment — and the engine is given the buffer's text once. A text that changes every frame costs no garbage.
Text the element already says is no change: the engine leaves it, and lays nothing out again.
SetText
public void SetText(scoped ReadOnlySpan<char> text)Gives it the text in text, from a buffer of the caller's: no string is made.
Parameters
text
Exceptions
InvalidOperationException: It is not there.
Localize
public void Localize(StringKey key, params ReadOnlySpan<LocalizedArgument> arguments)Makes what it says a string of the game's, in the player's language: Title.Localize(Strings.Menu.Play), Coins.Localize(Strings.Hud.Coins, ("count", coins)). The engine fills it now, and again as the language changes, with no code of the game's; given other arguments, it is filled with them. Text given it after, by UiElement.Text or SetText, is its own again; in a game that is not localized it keeps what it said. See Localization.
Parameters
keyarguments
Exceptions
InvalidOperationException: It is not there.
Unlocalize
public void Unlocalize()Stops filling it from the game's strings (Localize): it says its own words again, what it was written as.
Exceptions
InvalidOperationException: It is not there.
SetText
public void SetText(scoped ReadOnlySpan<byte> utf8)Gives it the text utf8 says, as UTF-8 — what Utf8.TryWrite writes.
Parameters
utf8
Exceptions
InvalidOperationException: It is not there.AbyssException: It is not UTF-8.
SetImage
public void SetImage(ImageId image, ImageRegion? region = null)Draws image in it — one the game made (CreateImage) or loaded — or the rectangle region of it in the image's pixels: a block's icon from a sheet of them, a cell of an atlas. An element with no image is given one, drawn as its sheet draws an image, stretched to its size unless it says otherwise. What it draws already is no change. Drawn over its stylesheets, as a style a browser's script sets is: a card given its icon as it is shown keeps it, rather than the image its document gave it.
Parameters
imageregion
Exceptions
InvalidOperationException: It is not there.AbyssException:AbyssStatus.InvalidUiRequestfor a region that is no rectangle — a number that is not one, a corner left of or above the image, or one past the other — and the image's own for an id that names none.
ClearImage
public void ClearImage()Draws no image in it: Bevy's transparent one, as an element given none draws.
Exceptions
InvalidOperationException: It is not there.
MoveTo
public void MoveTo(Vector2 at)Puts it at at from its parent's top-left, in its document's units — the reference resolution's, as GameUi.Pointer gives a place — as its left and top: where its sheet places it absolutely, as a stack carried under the pointer or a tooltip by what it tells of is placed. Where it is already is no change. Set over its stylesheets, as UiElement.SetImage's image is: a rule that places it gives way.
Parameters
at
Exceptions
InvalidOperationException: It is not there.AbyssException:AbyssStatus.InvalidUiRequestfor a place that is no number.
AddClass
public void AddClass(string name)Gives it the class name, which a stylesheet's .name selects, as an HTML element is given one: Health.AddClass("low"). A class it has already is no change.
Parameters
name
Exceptions
InvalidOperationException: It is not there.AbyssException: The name is no class: empty, or holding a space.
Its other classes stay. The engine restyles it in the frame, with the sheet's transitions.
RemoveClass
public void RemoveClass(string name)Takes the class name away from it; one it has not is no change.
Parameters
name
Exceptions
InvalidOperationException: It is not there.AbyssException: The name is no class: empty, or holding a space.
ToggleClass
public bool ToggleClass(string name)Gives it the class name where it has it not, takes it away where it has, and says whether it has it now.
Parameters
name
Exceptions
InvalidOperationException: It is not there.AbyssException: The name is no class: empty, or holding a space.
ToggleClass
public void ToggleClass(string name, bool on)Gives it the class name where on, and takes it away where not: Door.ToggleClass("open", isOpen).
Parameters
nameon
Exceptions
InvalidOperationException: It is not there.AbyssException: The name is no class: empty, or holding a space.
HasClass
public bool HasClass(string name)Whether it has the class name, its own or one the engine gives it as its state is — rtl and touch on a document's top, open on an open dropdown; an element that is not there has none.
Parameters
name
Exceptions
AbyssException: The name is no class: empty, or holding a space.
Add<T>
public T Add<T>() where T : UiViewMakes an instance of the UI document whose class is T under this element, after what is in it: a template — a card in a panel of cards — that is part of this element's document from then on, styled by its sheets and then its own, and its own class, given back, hearing what its elements do. Shown at once where its document has loaded, as one loaded with the game has; otherwise once it has, its class told it is shown.
Type parameters
T: The template's class, which the build makes of its document.
Exceptions
InvalidOperationException: This element is not there, nor part of a document shown; orTis no UI document's class.
Clear
public void Clear()Takes every template instance made under this element away, each class told it is hidden.
Bind
public void Bind(Func<float> read, Action<float>? write = null)Binds a slider to what the game holds: moved to what read says, between frames, where it says otherwise; and, given write, each value the player moves it to written — Volume.Bind(() => audio.Volume, value => audio.Volume = value). A setting Preferences.Use gave is saved as the slider is let go of.
Parameters
readwrite
Exceptions
InvalidOperationException: It is not there, is part of no document shown, or is no slider.
One binding an element: binding it again lets go of the one before. A binding goes with its document, or with UiElement.Unbind.
Bind
public void Bind(Func<int> read, Action<int>? write = null)Binds a dropdown to what the game holds: its option at the place read says picked where it says otherwise, and, given write, the place of each option the player picks written — Quality.Bind(() => settings.Quality, picked => settings.Quality = picked), saved as it is picked where it is a setting Preferences.Use gave. A slider is bound to a whole number as to any number, its value rounded as it is written.
Parameters
readwrite
Exceptions
InvalidOperationException: It is not there, is part of no document shown, or is neither a dropdown nor a slider.
As Bind.
Bind
public void Bind(Func<bool> read, Action<bool>? write = null)Binds a toggle to what the game holds: turned to what read says where it says otherwise, and, given write, what the player turns it to written — saved as it is turned, where it is a setting Preferences.Use gave.
Parameters
readwrite
Exceptions
InvalidOperationException: It is not there, is part of no document shown, or is no toggle.
As Bind.
Bind
public void Bind(Func<string> read, Action<string>? write = null)Binds its text to what the game holds: a label's — Score.Bind(() => $"Score: {score}") — or a text field's, which, given write, writes what the player types, a letter at a time, saved as it is typed where it is a setting Preferences.Use gave.
Parameters
readwrite
Exceptions
InvalidOperationException: It is not there, or is part of no document shown.
As Bind. What read gives is a string made each frame; text that changes every frame is UiElement.SetText's, which makes none.
Bind<TView, TItem>
public void Bind<TView, TItem>(IReadOnlyList<TItem> items, Action<TView, TItem> show) where TView : UiViewBinds this element to a list: one instance of TView's document under it for each item, in the list's order, each shown its item by show once it is shown — Cards.Bind(items, (ItemCard card, Item item) => card.Show(item)). An item added to the list has a card made for it, one taken out has its card taken away, and the cards follow its order, the list compared between frames.
Type parameters
TView: The template's class, which the build makes of its document.TItem: What the list holds.
Parameters
itemsshow
Exceptions
InvalidOperationException: It is not there, or is part of no document shown; orTViewis no UI document's class.
An item is told apart as its type tells two apart — a class by which it is, a record by what it holds — and two alike by their order. A card taken away from code while its item is still in the list is made again: the list says what is shown.
As Bind; unbound, the cards stay as they are.
Unbind
public bool Unbind()Lets go of its binding, leaving it as it is; whether it had one.
SetOptions
public void SetOptions(IEnumerable<string> options)Gives a dropdown these options, in this order — Language.SetOptions(languages.Select(each => each.NativeName)): each it has says its word, one more is made for each word past them, a copy of its first option, and the rest are taken away. Each says what it is given, its localized text, where it had one, let go of. The option picked stays where it still is, else the last is picked.
Parameters
options
Exceptions
InvalidOperationException: It is not there, or is no dropdown.ArgumentException: An option holds U+001E, which ends each option's words as they cross to the engine.
Open
public void Open()Opens a dropdown's list, where it opens, focus on the picked option, as a click on it would.
Exceptions
InvalidOperationException: It is not there, or is no dropdown.
Close
public void Close()Closes a dropdown's list as it is, nothing picked, focus back on the dropdown.
Exceptions
InvalidOperationException: It is not there, or is no dropdown.
SimulateClick
public void SimulateClick()Presses it as a click on it would — a button clicked, a toggle turned — heard on the next step: for a test of a game's interface.
Exceptions
InvalidOperationException: It is not there.
Focus
public void Focus()Gives it the interface's focus, so Enter presses it where it is a button.
Exceptions
InvalidOperationException: It is not there.
