Manual

Manual

The window and display

Your built game is an application with a window of its own. This page covers the window it opens, as its Player settings say, what your code knows of the game as an application, how a settings screen changes the way it is shown while it plays, the frame rate, and how the game ends itself.

The window a game opens

A built game opens its window as Edit ▸ Project Settings… ▸ Player says, in its Resolution section:

SettingWhat it does
Fullscreen ModeWindowed, a window with the system's frame, or Borderless Fullscreen, a window without a border the size of the screen it is on, the desktop's resolution kept.
Default Window SizeThe window's width and height in pixels, 1280 × 720 to start. Grayed while the mode is Borderless Fullscreen, since that window is the screen's size.
Resizable WindowWhether the player can drag the window's edges to resize it. On to start; grayed while borderless.

The window's title is the Product Name from the same page, or your project's name while that is empty. Its icon is the Default Icon: on Windows the executable's own icon, which the window takes; on Linux carried inside the executable and given to the window as it opens; on macOS the app's icon, shown in the Dock, as a Mac's windows have none. See Player settings for the rest of the page.

The settings are saved in settings/player.json, under window:

{
  "abyssPlayer": 1,
  "product": "Orbit",
  "window": {
    "fullscreen": "windowed",
    "width": 1280,
    "height": 720,
    "resizable": true
  }
}

A built game waits for the display to refresh before it shows each frame, VSync, unless your code says otherwise or it is started with --no-vsync, which draws as fast as it can, for measuring how fast your game runs. --pack and a path play from that pack instead of the one beside the executable:

SpaceRace.exe --no-vsync
SpaceRace.exe --pack path/to/game.abypack

On Windows, a game goes on running while its window is dragged by its title bar: its time, physics and sound carry on, and it draws again once the window is let go of.

The game as an application

world.Application says what the game is, and ends it:

MemberWhat it is
ProductWhat the game is called: Player's Product Name, or the game's own name where that is empty.
CompanyPlayer's Company Name; empty where it names none.
VersionPlayer's Version, as major.minor.patch.
InEditorWhether the game is playing in the editor rather than on its own.
Quit()Ends the game after this frame.
QuittingWhether its end has been asked for, by Quit or by its window's close button.
CanQuitWhether Quit ends anything a player sees: false in a browser, where a game cannot close the tab it plays in.
IsWebWhether the game plays in a browser.
OpenLink(url)Opens a web page, an https:// or http:// address, in the system's browser, or in a new tab in a browser.
string title = $"{world.Application.Product} {world.Application.Version}";   // "Space Race 1.2.0"
bool showExit = world.Application.CanQuit;   // a menu leaves its Exit out in a browserif (exitClicked)                             // your menu's Exit button{    world.Application.Quit();}

OpenLink refuses what is not a web page's address, such as another scheme or a link with a space in it, so a game cannot start another program through one. In a browser, which allows a new tab only for a click or a key, the page opens at the player's next click or key.

How a game ends

Quit() ends a game on its own after the frame it is called in. First every plugin's Stopping runs, with the world still there, so what it saves is saved; then the window closes. The window's close button, and Alt+F4 on Windows, end the game the same way. In the editor, Quit() stops Play, as the Stop button does. See Code that is not a system for Stopping.

How the game is shown as it plays

world.Display is what a settings screen changes. Each setting applies from the next frame:

MemberWhat it does
ModeFullscreenMode.Windowed, or FullscreenMode.Borderless, across the screen the window is on. It starts as Player's Fullscreen Mode opened the window.
VSyncWhether each frame waits for the display to refresh: no tearing, and no more frames than the display shows. On to start.
FrameRateCapThe most frames a second the game draws, up to 1,000; 0 for as many as it can. A game starts at 0 on a desktop and at 60 on a phone (GameDisplay.PhoneFrameRateCap).
FrameRateHow many frames a second are drawn, counted over the last half second: for a debug screen.
RefreshRatesThe rates the display the game is on refreshes at, at the resolution it shows, highest first: the caps a settings screen offers. Empty where there is no display to read, as in a browser.
RefreshRateThe rate the display refreshes at now; 0 where it is not known.
AppliesWhether what is set is applied: true in a game on its own, false in the editor.
world.Display.Mode = fullscreen ? FullscreenMode.Borderless : FullscreenMode.Windowed;world.Display.VSync = vsync;world.Display.FrameRateCap = 144;string fps = $"{world.Display.FrameRate:F0} fps";   // for a debug screen

A frame-rate cap holds the end of each frame until its share of a second has passed. A frame that comes late is not made up for, so a stall is not followed by a burst of frames. With VSync on and a cap above the display's rate, the display's rate wins; with a cap at the display's rate, the display paces the frames, so none is shown twice. A mode there is none of, and a cap below 0 or above 1,000, throw an ArgumentOutOfRangeException.

A settings screen can offer the display's own rates, and 30, which a phone shows at 60, each frame for two refreshes:

int[] caps = [.. world.Display.RefreshRates.Select(rate => (int)MathF.Round(rate)).Append(30).Distinct()];FrameRateMenu.SetOptions(caps.Select(cap => $"{cap} fps"));FrameRateMenu.Bind(    () => Math.Max(Array.IndexOf(caps, world.Display.FrameRateCap), 0),    picked => world.Display.FrameRateCap = caps[picked]);

On a phone

A phone's display can refresh at more than one rate, 60 and 90 or 120 a second, and picks one itself. Its RefreshRates hold 60 whether it lists it or not, as some phones list a game only their highest rate. A cap at one of its RefreshRates asks the display to refresh at that rate while the game is shown, so a game capped at 60 on a display of 90 shows each frame once, rather than every second frame twice. A cap that is none of its rates asks for the lowest rate it divides, 60 for a cap of 30, and a cap of 0 leaves the rate to the phone.

A game on a phone starts capped at 60. Its frames are steady, and the phone stays cooler and lasts longer on its battery. At the most a display refreshes at, 90 or 120, a phone lowers its GPU's clock as soon as the game's frames get lighter, then drops frames before raising it again. To let a player pick a faster rate, offer the phone's RefreshRates. To leave the rate to the phone, set FrameRateCap to 0. A desktop's display is the player's to set, and is never changed.

Keep the player's choices

world.Display holds what is set for as long as the game runs. To start with the player's choices next time, keep them as the player's preferences and set them again as the game starts (see Player preferences):

[Preferences("video")]public sealed partial class VideoSettings{    public bool Fullscreen;    public bool VSync = true;    public int FrameRateCap;}
public sealed class VideoPlugin : IPlugin{    public void Build(Schedule schedule)    {    }
    public void Started(World world)    {        VideoSettings video = world.Preferences.Load<VideoSettings>();        world.Display.Mode = video.Fullscreen ? FullscreenMode.Borderless : FullscreenMode.Windowed;        world.Display.VSync = video.VSync;        world.Display.FrameRateCap = video.FrameRateCap;    }}

When the player changes a setting, set it on world.Display and Save the class again with world.Preferences.Save(video).

In the editor

When you press Play, the game is drawn in the Game panel, whose window and pace are the editor's. So world.Display keeps what your code sets and reads it back, but applies none of it: Applies is false, and a settings screen works the same without changing the editor. FrameRate is counted in the editor too. To see the game at the size of a screen or a phone, pick a size in the Game panel's top row (see The Game view).

world.Application.InEditor is true while the game plays in the editor, and Product, Company and Version are read from Player settings as Play starts.

In a browser

A web build plays in a page; see Build for the web for the pages it can play on. There, FrameRateCap has no effect, as the page is drawn as often as the browser draws it, and CanQuit is false. To talk to the page your game plays on, see JavaScript.

In the Scripting API