Scripting API

Scripting API

Preferences

Class in Abyss.Core, from Abyss.Core.

A player's own data — the settings a game keeps for whoever plays it, the keys they rebound, later their saves — in a folder of theirs: World.Preferences.

public sealed class Preferences

Remarks

Where it is is the engine's to say, the same for every game on a platform: on Windows %LOCALAPPDATA%\Company\Product, from Project Settings' Player, which a game on its own is given as it starts. The editor keeps a game it plays apart, in the project's cache/preferences, so trying it changes nothing a player of the built game has.

A file is never half written: it is written beside itself and moved over the old one once it is whole, so a game that stops while it saves leaves what was there before.

Typed settings, a class of the game's marked PreferencesAttribute, are Preferences.Loaded and Preferences.Saved whole, no key typed anywhere; anything else is a file of a name of the game's choosing, read and written as bytes or text.

Properties

Folder

public string? Folder { get; }

The folder the player's data is kept in, or null where none was said.

Methods

InProject

public static string InProject(string project)

Where the editor keeps the player's data of the game in project: its cache's Preferences.CacheFolder.

Parameters

  • project

UseFolder

public void UseFolder(string? folder)

Keeps the player's data in folder, or nowhere: what the editor says of a game it plays. The keys each player rebound there are read back at once.

Parameters

  • folder

UseGame

public void UseGame(string company, string product)

Keeps the player's data where a game called product, made by company, keeps it on this platform: what a game on its own says as it starts. The keys each player rebound there are read back at once.

Parameters

  • company
  • product

Exceptions

  • AbyssException: The platform says nowhere.

Read

public byte[]? Read(string name)

The player's file name, or null where there is none.

Parameters

  • name

Exceptions

  • AbyssException: No folder was said, the name is no file under it, or the platform will not read it.
  • ArgumentException: The name has a null character in it, where the engine would read it as ending.

ReadText

public string? ReadText(string name)

The player's file name as UTF-8 text, or null where there is none.

Parameters

  • name

Exceptions

Write

public void Write(string name, ReadOnlySpan<byte> bytes)

Writes bytes as the player's file name, whole or not at all, making the folders it is in.

Parameters

  • name
  • bytes

Exceptions

  • AbyssException: No folder was said, the name is no file under it, or the platform will not write it.
  • ArgumentException: The name has a null character in it, where the engine would read it as ending.

WriteText

public void WriteText(string name, string text)

Writes text as UTF-8 as the player's file name.

Parameters

  • name
  • text

Exceptions

  • AbyssException: As Write.

Delete

public bool Delete(string name)

Deletes the player's file name.

Parameters

  • name

Returns Whether there was one.

Exceptions

  • AbyssException: No folder was said, the name is no file under it, or the platform will not delete it.
  • ArgumentException: The name has a null character in it, where the engine would read it as ending.

Load<T>

public T Load<T>() where T : class, IPreferences, new()

The player's T as last saved, what the class starts with where it has never been, or a file that cannot be read says so in the log.

Type parameters

  • T

Exceptions

  • AbyssException: No folder was said, or the platform will not read it.

Save<T>

public void Save<T>(T preferences) where T : class, IPreferences

Keeps preferences as the player's T, whole or not at all.

Type parameters

  • T

Parameters

  • preferences

Exceptions

  • AbyssException: No folder was said, or the platform will not write it.

Forget<T>

public bool Forget<T>() where T : class, IPreferences

Forgets the player's T, so the next Preferences.Load has what the class starts with.

Type parameters

  • T

Returns Whether there was one saved.

Use<T>

public T Use<T>() where T : class, IPreferences, new()

The one T the game shares as it plays, read from the player's file the first time it is asked for: what every element bound to it is bound to. It is saved where it says otherwise than its file — as an element bound to it is let go of (a slider let go, a toggle turned, a name typed), by Preferences.SaveUsed, and as the game stops — and let go of then, so the next game reads it afresh.

Type parameters

  • T

Exceptions

SaveUsed

public int SaveUsed()

Saves each of what Preferences.Use gave that says otherwise than its file now: how many it saved.

Exceptions

ToJson

public static string ToJson(IPreferencesData preferences)

What preferences is kept as.

Parameters

  • preferences

Constants

InputBindingsName

public const string InputBindingsName = "input-bindings"

The engine's own file of each player's rebound keys; no class of a game's may be called it.

CurrentVersion

public const int CurrentVersion = 1

The version of a typed file this build writes, and the newest it reads.

CacheFolder

public const string CacheFolder = "preferences"

The folder of a project's cache the editor keeps a game's player's data in, apart from the built game's.