Scripting API

Scripting API

PlayerSettings

Class in Abyss.Core, from Abyss.Core.

What a built game is, to a player and to the platform: Player in Project Settings — settings/player.json beside the game's assets.

public sealed class PlayerSettings

Remarks

Who made it and what it is: the company, the product's name and its version, and the executable's details on Windows — its description and copyright, which follow the product's name and the company until somebody writes their own (null here). Its icon: a PNG from the assets, made into every size an executable carries, and on Windows each size given an image of its own if Override for Windows says so. Its window: windowed or borderless across the screen, its size, and whether it can be resized. What each platform knows it by: a Mac app's bundle identifier, an Android app's package name, and how a phone holds it.

Moved out of settings/build.json, which said the product's name and the window before there was a Player: a game with no player.json takes them from there, and writing Player takes them out of it.

Properties

WindowsIconSizes

public static IReadOnlyList<int> WindowsIconSizes { get; }

The sizes a Windows executable carries its icon at, the largest first: what Explorer, the taskbar and the title bar ask for.

Company

public string Company { get; set; }

Who makes the game.

Product

public string Product { get; set; }

What the game is called: its window's title and its executable's name; empty for the game's folder's.

Version

public string Version { get; set; }

Its version, major.minor.patch.

Icon

public SettingsImage? Icon { get; set; }

Its icon, a PNG from the assets; null for the platform's own.

Fullscreen

public FullscreenMode Fullscreen { get; set; }

How its window fills the screen.

Width

public int Width { get; set; }

How wide its window opens, in logical pixels.

Height

public int Height { get; set; }

How tall its window opens, in logical pixels.

Resizable

public bool Resizable { get; set; }

Whether a player can resize its window.

Description

public string? Description { get; set; }

The executable's description on Windows; null to follow PlayerSettings.Product.

public string? Copyright { get; set; }

The executable's copyright on Windows; null for "© year" and PlayerSettings.Company.

OverrideWindowsIcons

public bool OverrideWindowsIcons { get; set; }

Whether the Windows executable's icon sizes may each be given an image of their own: Override for Windows.

Identifier

public string? Identifier { get; set; }

What every platform that knows an app by a name of its own knows the game by, unless its own section gives it another: a domain its maker owns, reversed, and the game, net.example.game. macOS's bundle identifier and Android's package name, where neither is typed. Null until one is typed: none is made up, as one made of the company's name would name a domain nobody may own.

MacBundleIdentifier

public string? MacBundleIdentifier { get; set; }

The Mac app's bundle identifier, which macOS knows it by — its settings, its place in the Dock, its permissions: a domain its maker owns, reversed, and the game, net.example.game, letters, digits and hyphens between dots. Null to follow PlayerSettings.Identifier, and a macOS build asks for one where neither is typed.

AndroidPackage

public string? AndroidPackage { get; set; }

The Android app's package name, which Android and Google Play know it by — its data, its updates, its page in the store: as a bundle identifier is, a domain its maker owns reversed and the game, net.example.game, each part a letter and then letters, digits and underscores. Null to follow PlayerSettings.Identifier, and an Android build asks for one where neither is typed. Google Play never lets an app change it.

EffectiveMacBundleIdentifier

public string? EffectiveMacBundleIdentifier { get; }

The bundle identifier a Mac app is built with: PlayerSettings.MacBundleIdentifier, or PlayerSettings.Identifier; null for neither.

EffectiveAndroidPackage

public string? EffectiveAndroidPackage { get; }

The package name an Android app is built with: PlayerSettings.AndroidPackage, or PlayerSettings.Identifier; null for neither.

AndroidOrientation

public ScreenOrientation AndroidOrientation { get; set; }

Which way the game is held on an Android phone or tablet; on its side unless a game says otherwise.

AndroidFullscreen

public bool AndroidFullscreen { get; set; }

Whether the game has the whole of an Android device's screen, its status and navigation bars hidden until a swipe from an edge shows them for a moment; on unless a game says otherwise.

AndroidMsaa

public int AndroidMsaa { get; set; }

How many samples a camera draws with on Android where it says none of its own: 1 for no MSAA, unless a game says otherwise, or 2, 4 or 8. A phone's GPU pays for MSAA in every pass Bevy draws a picture in; see RenderSetup.CameraMsaa.

ThirdPartyNotices

public bool ThirdPartyNotices { get; set; }

Whether a build writes THIRD-PARTY-NOTICES.txt beside the executable: the licenses of the code it carries, which most of them ask to go with it. On unless a game says otherwise.

Optimize

public BuildOptimization Optimize { get; set; }

What its executable is compiled for; Speed unless a game says otherwise.

CultureData

public bool CultureData { get; set; }

Whether its executable carries .NET's culture data: dates, numbers and text compared and cased as each language has them, which on Linux .NET reads from ICU, a library not every machine has. Off unless a game says otherwise: every culture the invariant one, and the game starts wherever it is copied.

WebPage

public WebPage WebPage { get; set; }

The page a web build plays the game on; Branded unless a game says otherwise.

WebBackground

public string WebBackground { get; set; }

The page's background, #rrggbb, behind its icon and name and round the game's box.

WebAccent

public string WebAccent { get; set; }

The page's accent, #rrggbb: its bar and its buttons.

WebBadge

public bool WebBadge { get; set; }

Whether the Branded and Framed pages say the game was made with the engine; on unless a game says otherwise.

WindowsIcons

public Dictionary<int, SettingsImage> WindowsIcons { get; }

The images given to the Windows executable's sizes, by size: each used as it is in place of one made from PlayerSettings.Icon.

FileVersion

public IReadOnlyList<int> FileVersion { get; }

The version as Windows' four numbers, 0.1.0 as 0, 1, 0, 0; what is not a number counts as nothing.

Methods

NameOf

public static string NameOf(WebPage page)

What a page is called in the file and by the build: minimal, branded, framed, click, own.

Parameters

  • page

NameOf

public static string NameOf(ScreenOrientation orientation)

What an orientation is called in the file: landscape, portrait, auto.

Parameters

  • orientation

IsMsaa

public static bool IsMsaa(int samples)

Whether samples is a number of samples a camera draws with: 1 for none, 2, 4 or 8.

Parameters

  • samples

IsAndroidPackage

public static bool IsAndroidPackage(string? name)

Whether name is a package name Android takes: two parts or more between dots, each a letter and then letters, digits and underscores.

Parameters

  • name

IsBundleIdentifier

public static bool IsBundleIdentifier(string? name)

Whether name is a bundle identifier Apple takes: parts between dots, each of letters, digits and hyphens.

Parameters

  • name

IsWebColor

public static bool IsWebColor(string? color)

Whether color is one a page takes: #rrggbb.

Parameters

  • color

ProductOr

public string ProductOr(string fallback)

What the game is called, its folder's name where Player does not say.

Parameters

  • fallback: What to call it otherwise: the game's folder's name, or its assembly's.

DescriptionOr

public string DescriptionOr(string fallback)

The description the executable is given: PlayerSettings.Description, or the product's name.

Parameters

  • fallback

CopyrightFor

public string CopyrightFor(int year)

The copyright the executable is given: PlayerSettings.Copyright, or "© year" and the company; empty with no company.

Parameters

  • year: The year it says, the build's.

WindowsIconFor

public SettingsImage? WindowsIconFor(int size)

The image a Windows icon size is made from: its own where Override for Windows gives it one, the default icon otherwise; null for none.

Parameters

  • size

FileIn

public static string FileIn(string game)

Where a game keeps it: settings/player.json in its folder.

Parameters

  • game

Read

public static PlayerSettings Read(string game)

A game's Player; for one with no player.json, what its build.json said of its name and its window, from before there was a Player.

Parameters

  • game

Exceptions

  • FormatException: A file is not settings this build reads.
  • IOException: A file is there and cannot be read.

Parse

public static PlayerSettings Parse(string json)

Settings from their text.

Parameters

  • json

Exceptions

  • FormatException: It is not settings this build reads, saying why.

ToJson

public string ToJson()

The settings as their file holds them: only what differs from what a game starts with.

Write

public void Write(string game)

Writes Player into a game's folder, and takes the name and the window out of its build.json, which said them before there was a Player.

Parameters

  • game

Resolved

public PlayerSettings Resolved(AssetDatabase database)

The settings with each image named by the path it is at now — found by its identity where it was moved — and given the identity of the file at its path where it had none.

Parameters

  • database

Copy

public PlayerSettings Copy()

A copy, to change without changing this.

Constants

FileName

public const string FileName = "player.json"

The file, under the game's settings folder.

PathName

public const string PathName = "settings/player.json"

What it is called in a game's folder and in its pack: settings/player.json.

CurrentVersion

public const int CurrentVersion = 1

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

DefaultVersion

public const string DefaultVersion = "0.1.0"

The version a game starts at.

DefaultWebBackground

public const string DefaultWebBackground = "#14121a"

The background of a new game's page for the web, a dark plum.

DefaultWebAccent

public const string DefaultWebAccent = "#8b6cf0"

The accent of a new game's page for the web, its bar and buttons, a violet.