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 PreferencesRemarks
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
companyproduct
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
AbyssException: AsPreferences.Read.
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
namebytes
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
nametext
Exceptions
AbyssException: AsWrite.
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, IPreferencesKeeps 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, IPreferencesForgets 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
AbyssException: AsPreferences.Load.
SaveUsed
public int SaveUsed()Saves each of what Preferences.Use gave that says otherwise than its file now: how many it saved.
Exceptions
AbyssException: AsPreferences.Save.
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 = 1The 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.
