Manual
Manual
Texts
A SharedText field holds a string of any length in a component or a list's item: a sign's caption, a character's line, a quest's description. This page covers declaring one, making and reading texts, how long a text lives, and how the editor and scenes keep them.
Declaring a text field
Give a component a SharedText field:
using Abyss.Core;
[AbyssComponent]public partial struct Sign{ public float Size; public SharedText Caption;}A component is plain data, copied as bytes, so it cannot hold a C# string. A SharedText is eight bytes, a handle to a string the engine keeps. A new component's text is empty. A list's item can hold one as a component can.
For a short text that never runs past a known length, a FixedText32 up to FixedText256 field holds its bytes in the component itself, and reading it needs nothing else. Use a SharedText for text of any length, or for text many entities share: equal strings share one copy.
Making and reading a text
world.Text("Exit") makes a text, and world.TextOf(sign.Caption) reads it. A system does the same through its context:
public static partial class Labels{ [AbyssSystem] [MethodImpl(MethodImplOptions.AggressiveInlining)] private static void Label(ref Sign sign, in Health health, in SystemContext context) { sign.Caption = context.Text($"{health.Points} HP"); }}A text never changes. To change what a component says, make another text and put it there. Making a string that is held already gives the same handle, so a hundred signs saying Exit hold one copy. A component copied, by a plain assignment in C# or by Duplicate, shares its text with the copy, and both read it.
A system with Parallel = true cannot make or read a text in its slices: the build refuses context.Text and context.TextOf there (ABYSS018). Make the texts in a system of its own that runs next.
An empty string is SharedText.Empty, which needs no making and reads as empty.
How long a text lives
A text lives while a component or a list's item holds it. At a frame's edge, every so often, the engine lets go of the texts nothing holds. A text is never let go of in the frame it was made in, so one made and given to an entity by a command in the same frame is held by then.
The editor holds what it keeps too: Play's snapshot holds the texts the scene had, so Stop puts them back, and so does what an undo puts back.
A handle kept anywhere else, in a field of a class, a static or a resource, is not held. Once its text is let go of, world.TextOf throws an AbyssException saying it is gone, and world.TryTextOf returns null. Keep the string there, and make the text when it goes into a component. The build refuses a SharedText in a resource, an animation event, a project's settings, a data asset or a window's state (ABYSS041), none of which holds a text.
In the editor and scenes
The Inspector shows a text as a box to type in, as it shows a fixed text, with room for 16,384 bytes. What you type is given when you leave the box, as one change, and Ctrl+Z gives back what it said. With several entities picked, each is given the text.
A scene's file writes a text as its string, and leaves out an empty one:
"Sign": { "Size": 2, "Caption": "Mind the gap" }A fixed text is written the same way. A list's item writes its text under the item's place, "[0].Said": "Hi". A plain string in a scene is also how an enum's value is written, "Hidden"; a load reads it by the field it is given to, so a text field takes it as its text. A prefab's instance writes a text only where it says something other than the prefab, marked in the Inspector to revert or apply as any field is. A scene's image, in a built game, keeps each string once, and makes the texts as the scene is built.
When the game's code is built again, a text field keeps its text by its name. A field changed from a FixedText64 to a SharedText keeps what it says, and one changed back keeps as much as fits. A component no code declares any more, its script broken or gone, keeps its texts until the code is back. A text is not a curve an animation clip can key, nor a value a condition reads.
In the Scripting API
- SharedText: a text a component holds.
- World:
Text,TextOfandTryTextOf. - SystemContext:
TextandTextOf, for a system.
