Skip to main content

Android App Settings

When the Android card is selected in Project > Export Project..., the dialog shows an Android app tab between Content and Runtime. It holds everything that makes the export an Android app: its identity, icon and launch splash, the package format, signing, how the data is packed and delivered, and the device to deploy to.

Every change is saved immediately to Editor/AndroidApp.ddl in the project, so the settings are under source control with the project. Keystore passwords are never stored there.

Android app tab: App Identity (application ID, display name, version name and code, orientation) and Icon with the Circle, Squircle, Rounded square and Themed launcher previews

App Identity​

SettingDefaultDescription
Application IDcom.plasmagames.<project name>The package name, in lowercase reverse-domain form with at least two parts, each starting with a letter (com.studio.game). It cannot change once the app is on Google Play.
Display nameThe project nameShown under the icon on the home screen.
Version1.0.0 · 1The version name players see, and the version code. Google Play requires every upload to have a higher code.
raise the code after each Shipping exportonIncreases the version code by one after every successful Shipping export.
OrientationSensor landscapeSensor landscape, Landscape, Portrait, Sensor portrait or Any. Sensor follows the phone between the two sides.

Icon​

Android draws an adaptive icon: a foreground image over a background colour, masked to the shape of the launcher. The Preview row shows the icon in the Circle, Squircle and Rounded square masks and as a Themed icon.

SettingImageWithout it
Foreground imagePNG 432 × 432, with the art in the middle 264 × 264The engine's icon
Background colourThe colour behind the foreground#18324D
Monochrome iconPNG 432 × 432 with alpha. Android 13+ tints it for themed icons, and only its alpha counts.The foreground image
Legacy iconSquare PNG, 512 × 512 or 192 × 192, for launchers without adaptive iconsNone

Launch Splash​

Android shows the launch splash from the tap on the icon while the game starts. It stays up until the game has drawn its first frame, so players never see a black screen between the splash and the game. If the project's Startup.ddl has a boot image, that is the first frame after the splash.

SettingDescription
Splash iconPNG 1152 × 1152, with the art in the middle 768 × 768. Android 12+ shows it at 288 dp inside a 192 dp circle. Without one, the foreground image is used.
Background colourThe colour behind the splash icon. same as the icon uses the icon background. Match Boot Image takes the background colour of the first boot image in Startup.ddl, so the splash and the boot image look like one screen.

Store Listing​

Google Play also needs a Store icon (PNG 512 × 512, up to 1 MB) and a Feature graphic (JPEG or PNG 1024 × 500, no alpha). You upload them in Play Console; they are not part of the build. Setting them here only lets the preflight check their sizes and remind you about them.

Build Output​

SettingDescription
FormatAPK · install on devices or App Bundle · Google Play. The hint shows the estimated APK size or Google Play download size.
ABIsarm64-v8a. x86_64 (for emulators) is not available yet.
TexturesASTC 6×6, normal maps 4×4 (default), ASTC 8×8, normal maps 6×6 (smaller, softer) or Uncompressed (RGBA8). Sets the texture compression of the Android asset profile.
Render pathMobile (default): the mobile forward pipeline and the Mobile quality preset. Desktop: MainRenderPipeline, as on PC. Sets the render pipeline of the Android asset profile; a custom pipeline set in the profile is kept.

Textures and render path are stored in the asset profile, so changing them re-transforms the affected assets on the next export. See Mobile render path.

Signing​

SettingDescription
Debug keyThe engine's debug keystore. For testing only: Google Play rejects it.
Release keystoreYour upload key. Needed for App Bundles and Shipping builds.
KeystoreA .jks or .keystore file. Keep it outside the project.
Key aliasThe alias of the key in the keystore. Default upload.
Create Keystore...Creates a new upload key (RSA 4096, valid for 30 years). Asks for the file, alias, owner name and a password of at least 6 characters.
Set Password...Stores the keystore password in Windows Credential Manager, after checking that it opens the keystore.

On Windows the password is kept in Windows Credential Manager. On hosts without a credential store, and on build machines, set the environment variable PL_ANDROID_KEYSTORE_PASS before starting the editor.

warning

Every update of the game on Google Play must be signed with the same upload key. Keep a copy of the keystore and its password somewhere safe, outside the project.

Advanced​

Pack data into archives (on by default) packs each staged data directory into .plArchive files that the game reads straight from the APK and its asset packs, without unpacking. Large directories are split into several archives. Turn it off only to debug with loose files. A package with more than 65535 files then fails to build.

Data Delivery​

By default all data installs with the app. Add Asset Pack puts project folders into an asset pack of their own:

FieldDescription
nameLetters, digits and _, starting with a letter. gamedata is reserved for the packs the build creates itself.
DeliveryInstall-time (with the app), Fast-follow (right after the install, while the game may already run) or On-demand (when the game asks for it).
foldersProject folders separated by ;, for example Levels/Forest; Levels/Cave. Their transformed assets go into the pack.

Fast-follow and on-demand delivery need an App Bundle from Google Play. In an APK every pack installs with the app. Asset packs need Pack data into archives. How a game waits for and requests packs is described in Asset packs at runtime. For Google Play's size limits, see Publishing on Google Play.

Device & Deployment​

SettingDescription
DeviceThe adb device to deploy to. Refresh looks again.
Install after buildInstalls the package on the device. An App Bundle is turned into an APK set and installed with bundletool, including its asset packs.
Run after installStarts the game. With this ticked, the export button becomes Build, Install & Run and opens the Device Run window.
Run testsNot implemented yet; the stage is skipped.
Capture logcatReads the engine's lines from the device log after the run.
Device Run...Opens the Device Run window.

The export button reads Build APK, Build & Install, Build, Install & Run, Build App Bundle or Build Bundle & Install, depending on these settings and the format. The package is written to the destination folder as <DisplayName>-<version name>(<version code>).apk or .aab, with spaces removed from the name.

Preflight Checks​

With the Android card selected, the Preflight column checks the export before you start it. Errors block the export; warnings do not.

Toolchain​

CheckSeverityWhat to do
No Android SDK / The Android SDK is incompleteErrorSet ANDROID_HOME or install the SDK with Android Studio. Install platform-tools and build-tools.
Android build-tools X are too oldErrorInstall build-tools 35 or newer. Their zipalign aligns native libraries for 16 KB pages.
No Android NDK / NDK X is too oldErrorInstall NDK 28 or newer. It links native libraries for 16 KB memory pages.
No JDK found / JDK X is too oldErrorSet JAVA_HOME to a JDK 17 or newer.
Platform android-36 is not installedErrorInstall it, or a newer platform, with the SDK Manager. Google Play requires target API 36.
Android SDK, NDK · JDK, Platform android-36 installedOKThe toolchain is ready.

App and signing​

CheckSeverityWhat to do
Application ID isn't validErrorUse lowercase reverse-domain form, for example com.studio.game.
No display name / No version nameErrorSet it under App identity.
Google Play needs a release keyErrorApp Bundles and Shipping builds must be signed with a release keystore. Set Signing to Release keystore.
Signed with the debug keyOKFor testing only. Google Play rejects it.
No keystore chosen / The keystore does not exist / No key alias / No keystore passwordErrorChoose or create a keystore, enter the alias, and Set Password... (or set PL_ANDROID_KEYSTORE_PASS).
Signed with <keystore>OKShows the alias and where the password comes from.
N packages block AndroidErrorBuild the named packages for Android, or exclude them from Android exports in the Package Manager.

Images​

CheckSeverity
An image file does not exist, is not a PNG (feature graphic: PNG or JPEG), or has the wrong sizeError for images that go into the build, warning for store images
Monochrome icon has no alpha / has no transparent pixelsError: themed icons use only its alpha
Store icon is over 1 MB, Feature graphic has alphaWarning
Splash and boot image colours differWarning: Match Boot Image fixes it
Store listing imagesWarning until both store images are set, for App Bundle and Shipping builds
Icon and launch splashOK: summarises which icons and splash colour the build uses

Device​

CheckSeverityWhat to do
No device connected / Pick a deviceWarningConnect a phone with USB debugging on and Refresh, or pick one when several are connected.
<device> did not answerWarningUnlock the phone and allow USB debugging.
<device> can't run this buildErrorThe phone has no Vulkan 1.3. Google Play will not offer the game to it either.
Not run on a device yetWarningA device run finds missing shader permutations.
N shader permutations missingWarningFound in the last device run. Add them in the Device Run window.
Shader permutationsOKNone missing in the last device run.

Package​

CheckSeverityMeaning
Google Play takes App BundlesWarningA Shipping build with Format set to APK.
This App Bundle is debuggableWarningA Development App Bundle. It can be installed for testing, but Google Play rejects debuggable uploads. Export Shipping for the store.
Uncompressed texturesWarningSeveral times the data of ASTC, and far more GPU memory.
Desktop render pipelineWarningExpect well under 30 fps on most phones.
Data packaged as loose filesWarningPack data into archives is off.
Data in N install-time asset packsOKThe data is over the base download limit, so the build moves it into install-time asset packs.
Over the 4000 MB install-time download, Asset pack 'X' is over 1500 MB, Over 30000 MB of fast-follow and on-demand packs, Over the 34000 MB Google Play allows an app, More than 100 asset packsWarningSee Size limits.
Asset packs need data archivesErrorTurn on Pack data into archives.
Asset pack name 'X'ErrorThe name is invalid or used twice.
Asset pack 'X' is emptyWarningName the folders it delivers.
Asset packs install with the APKOKFast-follow and on-demand delivery comes with App Bundles.

See Also​