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 Localization

Remarks

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

  • text
  • arguments

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

  • key
  • arguments
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

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

  • language
  • packed

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

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

  • value
  • style

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

  • value
  • style

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

  • value
  • style

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

  • value
  • length

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

  • value
  • seconds

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

  • value
  • style

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

  • fromNow
  • style

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

  • moment
  • style

Events

Changed

public Action<Language>? Changed

Raised 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.