Scripting API
Scripting API
Localization
Class in Abyss.Core, from Abyss.Core.
A game's languages and strings, and the language the player uses: world.Localization. A game asks for a string by its key, Strings.Menu.Play, which the build writes for each entry of each string table, and is given it in the player's language.
public sealed class LocalizationRemarks
The strings are the engine's, kept in Rust, so a string is the same text however it is asked for. One missing from the player's language is looked for in its shorter code's language (pt-BR to pt) where the game has it, then in the default; where none has it, its name shows, Menu.Play, so a gap is seen rather than hidden.
A game starts in the language the player last chose, else the system's where the game has it or one of the same language, else its default, as its Localization settings say. Setting Localization.Language keeps the player's choice for the next time.
A built game's strings are in its packs. The main pack holds every language's strings of the tables that ship; a string table in an Addressables group that is an add-on is built into a pack for each language, dialogs-ru.abypack, an add-on of its own (Localization.AddOnsFor). Its strings are there as the add-on is attached and gone as it is detached, Localization.Changed raised where the language in use shows them; until then that language shows what it falls back to, or the strings' names, as the settings say.
Safe from systems running in parallel (context.Localization): it holds a lock round what it asks the engine and what it keeps.
Properties
Enabled
public bool Enabled { get; }Whether the game is localized, with a language to be shown in.
Languages
public IReadOnlyList<Language> Languages { get; }The game's languages, in the order a language menu lists them; none where it is not localized.
Default
public Language Default { get; }The language the game is written in, which every other falls back to.
Exceptions
InvalidOperationException: The game is not localized.
Language
public Language Language { get; set; }The language the player uses. Setting it to one of Localization.Languages shows every string in it from then on, keeps the choice for the next time the game starts, and raises Localization.Changed.
Exceptions
InvalidOperationException: The game is not localized.ArgumentException: Set to a language that is not one of the game's.
RightToLeft
public bool RightToLeft { get; }Whether the game is shown right to left: its language in use is written so — Arabic, Hebrew, Persian, Urdu — or Localization.PseudoRightToLeft is on. Every UI document is mirrored while it is, its top given the class rtl.
PseudoRightToLeft
public bool PseudoRightToLeft { get; set; }Shows the game right to left whatever its language, its UI documents mirrored, as the editor's Pseudo RTL does to try a layout before there is a translation; off as a game starts.
Methods
PackedName
public static string PackedName(string language)What a language's strings are called in a pack: strings/ru.
Parameters
language
Preview
public void Preview(Language language)Shows every string in a language of the game's from now on, as Localization.Language does, but keeps no choice of the player's: what the editor shows a language in, and a test.
Parameters
language
Exceptions
InvalidOperationException: The game is not localized.ArgumentException: A language that is not one of the game's.
AddOnsFor
public IReadOnlyList<AddOn> AddOnsFor(Language language)The add-ons holding a language's strings that are not attached as the game's list names them: what to download for the game to show it whole, its size by SizeToDownload. Of a group with a pack of its own besides its strings, its strings are listed once that pack is attached, as they are downloaded with it; none where every one is there.
Parameters
language
IReadOnlyList<AddOn> needed = flow.Localization.AddOnsFor(russian);long size = flow.Packs.SizeToDownload(needed); // "Download 5 MB?"foreach (AddOn addOn in needed){ await flow.Packs.Download(addOn);}Text
public string Text(StringKey key)A string in the player's language, its arguments' places left as written; its name where no language it is looked for in has it.
Parameters
key
Text
public string Text(LocalizedString text)The string a component names in the player's language, its arguments' places left as written; empty for none, or where no language it is looked for in has it.
Parameters
text
Format
public string Format(LocalizedString text, params ReadOnlySpan<LocalizedArgument> arguments)The string a component names in the player's language, filled in with its arguments; see Format. Empty for none.
Parameters
textarguments
Format
public string Format(StringKey key, params ReadOnlySpan<LocalizedArgument> arguments)A string in the player's language filled in with its arguments: {count} in it gives way to the argument named count, and a string with plural forms is given the form the language takes for the number its argument holds. Its name where no language it is looked for in has it.
Parameters
keyarguments
Coins.Text = world.Localization.Format(Strings.Hud.Coins, ("count", coins));Use
public void Use(LocalizationSettings settings)Uses a game's Localization settings: its languages, its default and what a missing string shows, keeping the language in use where the game still has it. Not localized, the game has no languages and every string shows its name.
Parameters
settings
Exceptions
ArgumentException: The settings name languages no game can have (LocalizationSettings.WhyNot).
UseStrings
public void UseStrings(string language, ReadOnlySpan<byte> packed)Puts one language's strings in, packed as Pack packs them, in place of what it had; raises Localization.Changed where the language in use shows them.
Parameters
languagepacked
Exceptions
AbyssException: The game has no such language, or the bytes are not strings.
UseTables
public void UseTables(IReadOnlyList<(AssetGuid Table, StringTable Strings)> tables)Puts every language's strings in from string tables, each with its asset identity: what the editor does as a game plays. As the editor plays the game as a new player, a table's strings in a language whose add-on is not attached are left out until it is.
Parameters
tables
Exceptions
AbyssException: AsUseStrings.
Start
public void Start()Picks the language the game starts in, as its settings say: the player's last choice, else the system's language or one of the same language the game has, else the default. What a game does as it starts, once the player's folder is known.
System
public static string? System()The language the system is set to, as BCP 47 writes it; null where it does not say.
FormatNumber
public string FormatNumber(double value, string? style = null)A number as the language in use writes it, in the game's digits: grouped, as many places as it has, or as style says — 0.00, percent, compact.
Parameters
valuestyle
Exceptions
ArgumentException: A style a number has not.
FormatNumber
public string FormatNumber(long value, string? style = null)A number as the language in use writes it; see Localization.FormatNumber.
Parameters
valuestyle
Exceptions
ArgumentException: A style a number has not.
FormatNumber
public string FormatNumber(decimal value, string? style = null)A number as the language in use writes it, its places as it has them; see Localization.FormatNumber.
Parameters
valuestyle
Exceptions
ArgumentException: A style a number has not.
FormatDate
public string FormatDate(DateTime value, DateLength length = Medium)A date as the language in use writes it, in the player's time, at length: 12/31/26, Dec 31, 2026, December 31, 2026, Thursday, December 31, 2026.
Parameters
valuelength
FormatTime
public string FormatTime(DateTime value, bool seconds = false)A time of day as the language in use writes it, in the player's time: 3:45 PM, 15:45, with its seconds where seconds.
Parameters
valueseconds
FormatDuration
public string FormatDuration(TimeSpan value, DurationStyle style = Units)A length of time as the language in use writes it: its two largest units, 2 hr, 5 min, or a timer, 2:05:30.
Parameters
valuestyle
FormatRelative
public string FormatRelative(TimeSpan fromNow, RelativeStyle style = Long)A length of time from now as the language in use writes it, a negative one before now: in the largest unit it is one or more of, rounded, 5 minutes ago, in 3 hours; and where it is the last, this or the next of its unit, the word the language has for it, yesterday, now, next month. Written once: it says what it said until it is written again.
Parameters
fromNowstyle
FormatRelative
public string FormatRelative(DateTime moment, RelativeStyle style = Long)A moment as far from now as the language in use writes it, 5 minutes ago; see FormatRelative. A moment in UTC is measured from now in UTC, any other from the player's.
Parameters
momentstyle
Events
Changed
public Action<Language>? ChangedRaised as what the strings say changes, with the language in use: as it changes, and as strings it is shown in arrive or go — an add-on of them attached or detached, a table edited as the editor plays the game. On the engine thread, or on a system's where a system set Localization.Language.
Constants
ChoiceName
public const string ChoiceName = "language"The engine's own file of each player's language; no class of a game's may be called it.
