Manual
Manual
Player preferences
A game keeps what belongs to whoever plays it, such as their settings, the keys they rebound and files of their own, through world.Preferences, in a folder the engine picks for the platform. This page covers where that folder is, settings kept as a class of your own, one copy of them shared as the game plays, and files your game names itself.
These are the player's, kept on their machine. What belongs to the project, the same for every player, is project settings declared in code.
Where a player's data is kept
| Where the game runs | The folder |
|---|---|
| Windows | %LOCALAPPDATA%\Company\Product |
| macOS | ~/Library/Application Support/Company/Product |
| Linux | $XDG_DATA_HOME/Company/Product, or ~/.local/share/Company/Product where XDG_DATA_HOME is not set |
| A browser | The browser's own storage for the game's page |
The editor, or dotnet run from the game's folders | The project's cache/preferences |
Company and Product are the Company Name and Product Name of Edit ▸ Project Settings ▸ Player (see Player settings). With no Company Name there is no company folder, and with no Product Name the product is the game's own name. A character that a folder's name cannot have is written as _. world.Preferences.Folder says where the folder is.
Because the editor keeps a game's players' data in the project's cache, trying a Controls screen in the editor changes nothing a player of the built game has, yourself included.
A file is never half written: it is written beside itself, as name.writing, and moved over the old one once it is whole, so a game stopped while it saves keeps what was there before.
Settings as a class
A partial class marked [Preferences("name")] is kept whole, as name.json in the player's folder. No key is typed anywhere: the build writes how the class is saved and read, as code, since a built game has no reflection to find its members.
[Preferences("graphics")] // kept as graphics.jsonpublic sealed partial class GraphicsSettings{ public float Brightness = 1f; public Quality Quality = Quality.High; // an enum, kept by its name public bool Vsync = true;
[FormerlySerializedAs("vol")] public float Volume = 0.8f; // a file that still says vol is read here}
public enum Quality { Low, Medium, High }GraphicsSettings graphics = world.Preferences.Load<GraphicsSettings>(); // as the class starts if never savedgraphics.Brightness = 1.2f;world.Preferences.Save(graphics);
world.Preferences.Forget<GraphicsSettings>(); // deletes it: the next Load has the class's own valuesThe file is JSON, each member under its name:
{
"abyssPreferences": 1,
"Brightness": 1.2,
"Quality": "High",
"Vsync": true,
"Volume": 0.8
}What a class can hold
The class's public fields, and its public properties with a getter and a setter, are kept when they are:
- a number (
sbyte,byte,short,ushort,int,uint,long,ulong,float,double), aboolor astring; - an enum, kept by its name;
- a
Vector2,Vector3,Vector4orQuaternion; - an array or a
List<T>of those; - a class marked
[Preferences]with no name, kept inside this one.
[Preferences("controls")]public sealed partial class ControlsSettings{ public float LookSpeed = 1f; public bool InvertY; public List<string> RecentServers = []; public WindowPlace Window = new();}
[Preferences] // no name: kept inside another classpublic sealed partial class WindowPlace{ public int X = 100; public int Y = 100;}The build tells you, at the declaration, what does not fit:
| Code | What it says |
|---|---|
ABYSS019 | An error: the class is not one the engine can make. It must be a partial class, not abstract, static or generic, inside partial types if it is nested, with a constructor that takes nothing. |
ABYSS020 | A warning: a public member of a type it cannot keep. It is left out of the file. |
ABYSS021 | An error: the name cannot be a player's file. |
A property worked out from the others, with no setter, is left out without a warning.
The name is a path under the player's folder, its parts joined by /, as in [Preferences("profiles/main")]. No part may be empty, . or .., end with a dot or a space, or have a character a Windows file name cannot have; the same rules hold on every platform, so a game that saves on one saves on all. input-bindings is the engine's own.
A file from an older version of the class
Players keep their files while the game is updated, so a file written before the class changed still loads:
- A member the file does not have, or has as something it cannot be, keeps the value the class starts it with.
- A member the file has and the class does not is passed over.
- A member you renamed keeps its value when you add
[FormerlySerializedAs("Old")]with its old name. - A file that is not JSON at all gives the class as it starts, and says so in the Logs panel.
The file's name stays the one the attribute gives, whatever you rename the class to.
One copy the game shares
Load gives a new copy each time. world.Preferences.Use<T>() gives the one copy the whole game shares as it plays, read from the file the first time it is asked for. That is the copy to bind a settings screen to: an element bound to it saves it as the player lets go of it, such as a slider released, a toggle turned or a name typed.
[Preferences("settings")]public sealed partial class GameSettings{ public float Volume = 0.8f;}
// The class of a settings screen's UI document, which has a slider called Volume.partial class Settings{ partial void OnShown() { GameSettings settings = World.Preferences.Use<GameSettings>(); Volume.Bind(() => settings.Volume, value => settings.Volume = value); }}What you change in it from code is saved by world.Preferences.SaveUsed(), which saves each shared copy that differs from its file and says how many it saved, and as the game stops. Then the copies are let go of, so the next run reads them afresh. A game in a browser does not get to stop as its page closes, so call SaveUsed after changing a shared copy from code. Settings kept between runs covers binding elements to them.
Files of your own
For anything that is not settings, such as a save game or a replay, name a file yourself:
world.Preferences.Write("saves/slot1.bin", bytes); // whole, or not at allbyte[]? saved = world.Preferences.Read("saves/slot1.bin"); // null where there is none
world.Preferences.WriteText("notes.txt", "Remember the blue door.");string? notes = world.Preferences.ReadText("notes.txt"); // UTF-8
bool was = world.Preferences.Delete("saves/slot1.bin"); // whether there was oneThe folders a name needs are made as it is written. Names follow the same rules as a class's.
Keys the player rebinds
What a player rebinds of the game's input actions is kept by the engine itself, as input-bindings.json in the same folder, each player's apart, and read back as the game starts. Forget Players' Bindings, at the top of Edit ▸ Project Settings ▸ Input, deletes what was rebound while trying the game in the editor. See Rebinding.
When it cannot read or write
The calls are on the engine thread and read or write the disk at once, so make them where the player changes something, in a hook or a flow, rather than every frame. They throw an AbyssException when the platform gives no folder, or will not read or write the file, and an ArgumentException for a name with a null character in it. A file that is there but is not JSON is not an exception: Load and Use give the class as it starts, and say so in the Logs panel.
In the Scripting API
- Preferences: the player's folder, their settings and their files.
- PreferencesAttribute: a class kept as a player's settings.
- FormerlySerializedAsAttribute: a member's old name, read from older files.
