Manual

Manual

Build and run your game

Build your game into something players run: an executable for Windows, Linux or macOS, an app for Android, or a page for the web. This page covers Build Settings, what a build writes, how a built game starts, the Player settings a build uses, building from the command line, and the engine's SDK that every game's project names.

Before you build

A build compiles your game's C# ahead of time with .NET's NativeAOT and links it with the engine and any Rust your game has. Players need no .NET runtime, and nothing is compiled while the game plays. To build, your computer needs Rust and your platform's build tools; see The tools games are built with.

Each desktop platform is built on itself. The editor builds for the system it runs on: Windows on Windows, Linux on Linux, macOS on a Mac. The web is built from the editor on Windows or Linux, and Android from the editor on any of the three.

The first build on a computer compiles the engine for your game's executable, which takes minutes; the status line says how long so far. Later builds reuse that work and are much quicker. Closing the editor stops a build.

Build with Build Settings

  1. Choose File ▸ Build Settings… (Ctrl+Shift+B).
  2. Under Scenes In Build, list the scenes your game has. Drag them in from the Project panel, or click Add Open Scenes.
  3. Tick the scenes to build, and drag the rows into order. The first ticked scene is the one the game opens with. Delete, or Remove From Build on a row's right-click menu, takes a scene out.
  4. Pick a platform on the left.
  5. Click Build, or Build And Run to start the game once it is built.

The list is saved in settings/build.json. The window says where the build goes, such as Builds to builds/win64, with a button that shows the folder in your file manager. A bar beside the buttons shows how far along a build is, and if it fails, the Logs panel says why.

Last Build lists each pack the build wrote, its size and what it holds, and names any assets it left out because nothing reaches them.

Platforms

PlatformBuilt in the editor onWhat the build is
Windows (x64)Windowsbuilds/win64/<Name>.exe
Linux (x64)Linuxbuilds/linux64/<Name>, an executable with no extension
macOS (Apple Silicon)a Macbuilds/macos/<Name>.app
Android (ARM64)Windows, Linux or a Macbuilds/android/<Name>.apk
WebWindows or Linuxbuilds/web/index.html

<Name> is the Product Name in Player settings, or the project folder's name if that is empty. iOS is listed but grayed: it cannot be built yet. Picking a desktop platform other than your own says where it is built.

What a build writes

Beside the executable, a desktop build writes:

  • game.abypack, the main pack: the ticked scenes and everything they reach, such as models, materials, images and prefabs, plus the assets in the default group of Window ▸ Addressables and every UI document.
  • A pack for each other Addressables group that ships with the game.
  • THIRD-PARTY-NOTICES.txt: the licenses of the code your game carries, such as the engine, Bevy and the .NET runtime, which most of them ask to go with it. A .txt or .md file in your assets whose Import As is License is added too, such as a font's license.
  • The native libraries of your packages, for that platform.

An Addressables group marked Add-on is built into a folder beside the build's, such as builds/win64-addons, with a list of what is in it, named by the game's Version (catalog_1.23.1.json) or catalog.json: upload that folder, and ship the other. See Add-ons. To try the downloads before you upload anything, tick Serve Add-ons in Project Settings ▸ Add-ons, and Build And Run starts the game downloading its add-ons from your computer (see Trying add-ons on your computer).

What nothing reaches and is not addressable is left out. To load an asset by name rather than through a scene, mark it addressable (see Assets, identities and addresses). Build Packs in the Addressables window writes the packs again without building the executable.

A macOS build is an app: the executable and the packages' libraries in Contents/MacOS, and the packs, the notices and the icon in Contents/Resources. It is signed ad hoc so a Mac runs it. Notarizing, which a downloaded game needs to open without macOS asking first, is not done yet. A macOS build needs an Identifier in Player's Identity, or a Bundle Identifier of its own under macOS, and asks for one before it starts.

A build makes the packs first, then the executable. Before packing, it waits for every image and model to finish importing, since each asset goes in as the engine keeps it. Each pack is written beside where it goes and then put in place whole, so a pack that fails to build leaves the one from before, and stops the build there. A scene or prefab the pack would hold that cannot be read, such as one whose file is no longer valid JSON, fails it, and the build names the file. The status line says how far along it is, and the Logs panel and Last Build say what each pack holds.

How a built game starts

A built game reads nothing from your project's folders. Its executable reads game.abypack beside it (inside Contents/Resources in a Mac app), which also holds the project's settings: the scenes in the build, Player, input, layers and the rest. It opens its window as Player says, mounts every other pack beside it that your game's build made, attaches the add-ons it finds in addons beside it or in the player's folder, and opens the first scene ticked in Build Settings.

Each entry in a pack is compressed where that makes it smaller, and is checked as it is read. See Packs for what each pack holds.

A built game has none of what only the editor does. It cannot import a glTF, FBX or OBJ file, compress a texture, encode a sound or decode a JPEG, BMP or TGA image, since everything it reads was imported before it was packed, and it has none of the Scene panel's grid, outlines and draw modes. What your C# calls of these throws an AbyssException whose Status is AbyssStatus.NotInBuiltGame, saying which it was.

A built game takes these on its command line:

OptionWhat it does
--pack <file>Plays from another main pack in place of the game.abypack beside it
--no-vsyncDraws as fast as it can, without waiting for the display, as you would to measure its speed

Started from a terminal, a built game writes its log there.

Player settings

Edit ▸ Project Settings… ▸ Player, or Player Settings… in Build Settings, says what a build is called and how it starts. It is saved in settings/player.json.

SectionSettings
IdentityCompany Name; Product Name, the window's title and the executable's name; Identifier, what macOS and Android know the app by: a domain you own reversed, then the game, as net.example.game; Version, as major.minor.patch; Copyright, which follows the year and the Company Name until you type your own
IconDefault Icon, an image from your assets. Each size an executable needs is made from it.
ResolutionFullscreen Mode (Windowed or Borderless Fullscreen), Default Window Size and Resizable Window
LicensesThird-Party Notices: untick it to leave the notices file out
WindowsFile Description, and Override for Windows to give each icon size an image of its own
macOSBundle Identifier, which follows the Identifier until you type your own: letters, digits and hyphens between dots
AndroidPackage Name, which follows the Identifier until you type your own, Orientation and Hide System Bars (see Build for Android)
WebWeb Page, Background Color, Accent Color and Engine Badge (see below)
ExecutableOptimize For and Culture Data

On Windows, the company, description, version, copyright and product name are written into the executable, and File Explorer shows them in its Details tab.

Optimize For builds for Speed, or for Size: about a third smaller and about 8% slower in the engine's own work, with your C# compiled the same either way. Each is built separately, so the first build after switching takes longer.

Culture Data, off at first, makes dates, numbers and text follow each language's rules. A Linux player then needs the ICU library installed; off, the game starts on any Linux machine.

Build for the web

  1. In Build Settings, pick Web.
  2. The first time, click Install Web Build Support. It installs the WASI SDK, wasm-bindgen, Binaryen and Rust's WebAssembly target, once for the computer.
  3. Click Build, or Build And Run.

A web build writes index.html, with your C# compiled to WebAssembly and linked with the engine twice, once for WebGPU and once for WebGL2. The page plays the WebGPU build where the browser has it. The packs go beside it. Any web server can serve the folder, but opening index.html straight from disk does not work, as a page loads its modules and packs from a server. Let the browser keep the files between visits, as most servers do by sending each file's ETag or date: a server that tells it not to (Cache-Control: no-store) makes every visit download the whole game again. Build And Run serves the builds folder on your own computer, from the editor's Test Server, and opens the page in your default browser.

Your project's web/ folder is copied over what the build writes, so its files land beside index.html. Its own web/index.html is used only as the Own Page below. See Calling JavaScript for the scripts a game's page runs, how C# and the page call each other, and making a page of your own.

Player ▸ Web ▸ Web Page picks the page the game plays on:

PageWhat it shows
MinimalThe game on black, its name and a thin loading bar
Branded (the default)The game's icon and name on its Background Color, and a rounded bar in its Accent Color
FramedThe game in a 16:9 frame, its name above and a Fullscreen button
Click to PlayEverything loaded, then a Play button, so the game's sound starts with its first frame
Own PageYour game's own web/index.html, once it has one

Engine Badge adds a line saying Made with Abyss Engine to the Branded and Framed pages.

Build for Android

  1. Install Android Studio. It brings the Android SDK, and the Java that Android's build tools run on.
  2. In Android Studio's SDK Manager, on the SDK Tools tab, tick NDK (Side by side) and apply. The engine needs NDK 27 or newer.
  3. In Build Settings, pick Android. The first time, click Install Android Build Support: it downloads Gradle, which makes the app, and adds Rust's Android target, once for the computer. Until everything is there, the window lists what is missing.
  4. In Player ▸ Identity, give the game an Identifier: a domain you own reversed, then the game, as net.example.game. Android's Package Name follows it, and Android and Google Play know the app by it. Google Play never lets it change. Android takes letters, digits and underscores, each part starting with a letter, so an Identifier with a hyphen needs a Package Name of its own under Player ▸ Android, which the Identifier field says. A build asks for one before it starts.
  5. Click Build, or plug in your phone with USB debugging on (in its Developer options) and click Build And Run.

An Android build is an APK, builds/android/<Name>.apk: your C# compiled ahead of time for Android and linked with the engine into one library, Google's GameActivity that starts it, and the packs, which the game reads where they lie inside the APK. It runs on 64-bit ARM phones and tablets with Android 8.0 or later, which is nearly all of them. It is signed with your computer's debug key, which Android's build tools make once for each computer: any phone of yours installs it, but Google Play takes only an app signed with a key of your own, which comes later.

Build And Run installs the app on the first phone adb sees, keeping its data from the last time, starts it, and shows in the Logs panel what it says as it plays: the engine's log, what your C# writes with Log or Console, and its errors, an exception nothing caught among them. The game goes on playing after the next Build And Run, or after the editor closes; the editor just stops showing its log.

The editor finds the Android SDK where ANDROID_HOME says or where Android Studio installs it, the NDK where ANDROID_NDK_HOME says or in the SDK's ndk folder, and Java where JAVA_HOME says or in Android Studio.

Player ▸ Android also says how the game is held and drawn:

SettingWhat it does
OrientationLandscape (the default), on its side either way round; Portrait, upright either way up; or Auto Rotation, any way, unless the phone's owner has locked it. The game turns as the phone does.
Hide System BarsOn at first: the game has the whole screen, and a swipe from an edge shows the status and navigation bars for a moment
Anti-AliasingThe MSAA a camera draws with on a phone where its own MSAA in the Inspector is left as it is: Off at first, or 2x, 4x or 8x

On a desktop a camera draws with 4x MSAA unless you choose otherwise. A phone's GPU pays for MSAA in every pass a picture is drawn in, writing all its samples out to the phone's memory and reading them back: on a mid-range phone a menu that drew 44 frames a second with 4x drew the screen's full 90 without. So on Android cameras draw without it, unless Anti-Aliasing says otherwise or a camera's own MSAA was set to something other than 4x. Interface and sprites have smooth edges of their own; it is the edges of 3D models that MSAA smooths.

On a phone, the first finger on the screen is the mouse: it moves the pointer, and touching is the left button, so buttons and sliders work as they do on a desktop. Every finger reaches your C# as a touch.

Build from the command line

The editor builds a game and quits when you start it with --build, which suits scripts and build machines:

AbyssEditor --project path/to/SpaceRace --build
AbyssEditor --project path/to/SpaceRace --build path/to/out
AbyssEditor --project path/to/SpaceRace --build --platform web
  • --project is the game's folder.
  • --build with no folder builds into the game's own builds folder, as Build Settings does; with one, it builds there.
  • --platform says what to build for: web, android, or the desktop the editor runs on.

The exit code says whether the game built. The editor's executable is AbyssEditor.exe on Windows and AbyssEditor on Linux and macOS; the Hub installs each version in %LOCALAPPDATA%\AbyssEngine\Editors\<version> on Windows. A command-line build of a project last opened by another engine version says so, rather than asking.

To build only the executable, without its packs, publish the game's project with .NET:

dotnet publish SpaceRace.csproj -c Release -p:AbyssPlayer=true -p:AbyssPlayerOutput=path/to/out
PropertyWhat it does
-p:AbyssPlayer=trueBuilds the game's executable
-p:AbyssPlayerOutput=<folder>Where the executable goes
-p:AbyssPlayerName=<name>What the executable is called, the project's name unless you say
-p:AbyssPlayerOptimize=sizeBuilds for size or for speed, in place of what Optimize For says
-p:InvariantGlobalization=falseBuilds with each language's culture data, or with none for true, in place of what Culture Data says

It needs Rust, and on Windows Visual Studio's C++ tools, which NativeAOT links with.

The engine's SDK

A game's project names the engine as an MSBuild SDK, at a version, and needs no nuget.config:

<Project Sdk="AbyssEngine.Sdk/0.4.0" />

Every editor carries its version of the SDK in the sdk folder beside its executable: the package AbyssEngine.Sdk, and the engine's native library for the editor's computer as a package of its own, AbyssEngine.Sdk.Native.<runtime>. As it starts, the editor copies them into a folder of your own, %LOCALAPPDATA%\AbyssEngine\Sdk on Windows and ~/.local/share/AbyssEngine/Sdk on Linux, and adds that folder to your NuGet sources once, as AbyssEngine. So dotnet build, Visual Studio and any code editor find the SDK anywhere on the computer, offline. Every editor leaves its own version there, so a game is built with the version its project names, as long as that editor has run on the computer.

The engine's native library is published for Windows (win-x64), Linux (linux-x64) and macOS on Apple Silicon (osx-arm64), and a game's build takes the one for its own computer. Macs with Intel processors are not supported. On any other computer, the game's build compiles the engine's library from the Rust the SDK carries, once for each version.

What Cargo builds of the engine for a game goes into %LOCALAPPDATA%\AbyssEngine\cargo\<version>, shared by every game built with that version, which is why the first build on a computer takes minutes and the next ones do not.

A computer that has never run an editor, such as a build server, needs the SDK's packages in a folder that NuGet knows. Copy the editor's sdk folder there, and name it in a nuget.config beside the game's project:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="AbyssEngine" value="path/to/sdk" />
  </packageSources>
</configuration>

A build server also has no sign-in to download your packages with: give it an access token as ABYSS_REGISTRY_TOKEN; see Every build puts the packages back.

A project made with another version of the engine is asked about as the editor opens it. Opened, its project file names the editor's version of the SDK from then on.