Project Build Settings

Auto-Orientation

On most devices, auto-orientation is triggered by the accelerometer if the device is rotated or flipped during runtime. If you want to limit an app to either landscape orientation, specify both "landscapeLeft" and "landscapeRight" in the supported table.

supported = { "landscapeLeft", "landscapeRight" },

Similarly, to limit an app to either portrait orientation, specify both "portrait" and "portraitUpsideDown":

supported = { "portrait", "portraitUpsideDown" },

Permissions

On iOS, when accessing certain hardware or OS-level functionality, you must notify the user why you’re doing so. This is accomplished by including specific keys/descriptions in the plist table of build.settings. For example:

settings =
{
    iphone =
    {
        plist =
        {
            NSCameraUsageDescription = "This app would like to access the camera.",
            NSPhotoLibraryUsageDescription = "This app would like to access the photo library.",
            NSPhotoLibraryAddUsageDescription = "This app would like to add the photo library.",
        },
    },
}

When the system prompts the user to allow access, the associated description is displayed as part of the alert. Note that the descriptions can be customized to your preference and they can even be localized (guide).

Advanced Build Settings

In addition to the iOS settings mentioned above, the following build options are available as outlined in the Advanced Build Settings guide:

Version Code

You can override the version code entered into the Simulator Build for Android box with an optional versionCode key-value pair in the build.settings file. This is an internal number used to distinguish application releases for the Android app store, corresponding to the versionCode item detailed here. This setting is invisible to users.

settings
{
    android =
    {
        versionCode = "11",
    },
}

Permissions

The usesPermissions table creates <uses-permission> tags in the AndroidManifest.xml file:

settings
{
    android =
    {
        usesPermissions =
        {
            "android.permission.INTERNET",
            "android.permission.WRITE_EXTERNAL_STORAGE",
            "android.permission.ACCESS_FINE_LOCATION",
            "android.permission.ACCESS_COARSE_LOCATION",
        },
    },
}

In the example above, a few useful android.permission keys are exhibited:

• "android.permission.INTERNET" — permits an application to access the Internet.
• "android.permission.WRITE_EXTERNAL_STORAGE" — allows media.save() and camera support.
• "android.permission.ACCESS_FINE_LOCATION" — allows access to GPS.
• "android.permission.ACCESS_COARSE_LOCATION" — allows getting the location from WiFi/cellular.

See the Android documentation for more information on supported values and what you can do with them.

App Features

The usesFeatures table creates <uses-feature> tags in the AndroidManifest.xml file. These parameters tell the Android app store which hardware/software capabilities the app does or doesn’t require. See the Android features reference for a list of supported values.

settings
{
    android =
    {
        usesFeatures =
        {
            { name="android.hardware.camera", required=true },
            { name="android.hardware.location", required=false },
            { name="android.hardware.location.gps", required=false },
        },
    },
}

Expansion Files

The usesExpansionFile boolean indicates if the app should be built with expansion files. If it’s set to true and the build target is Google Play, everything in the project directory except the Lua scripts are put into the expansion file. See the Android documentation for more information.

settings =
{
    android =
    {
        -- This tells the Simulator to create an expansion file
        usesExpansionFile = true,

        -- The following permissions are required to download expansion files
        usesPermissions =
        {
            "android.permission.INTERNET",
            "com.android.vending.CHECK_LICENSE",
            "android.permission.WRITE_EXTERNAL_STORAGE",
        },
    },
}

Advanced Build Settings

In addition to the Android settings mentioned above, the following build options are available as outlined in the Advanced Build Settings guide:

iOS

For iOS, several icon files are required. Please see the Managing Xcode Assets guide for a reference on the Images.xcassets folder and how to include/reference it within your app.

Android

For Android, icon files will be copied into the .apk during the build, assuming they are available in your root project folder (alongside main.lua). These icons should adhere to the standard Android icon names and sizes listed below. For detailed information on creating icons, please refer to the Android Icon Design Guidelines.

Desktop

Desktop apps — applications built for macOS or Windows — require additional icons as follows:

• For macOS desktop apps, you must add a Icon-osx.icns file to your project folder before performing a macOS build via the Simulator. This file should contain multiple images at different resolutions, bundled into a single .icns file (details). See the Creating macOS Desktop Apps guide for more information.

• For Windows desktop apps, you must add a Icon-win32.ico file to your project folder before performing a Win32 build via the Simulator. This file should contain multiple images at different resolutions, bundled into a single .ico file (details). See the Creating Win32 Desktop Apps guide for more information.

tvOS / Android TV

Apps designed for TV systems require additional icons:

• For Apple’s tvOS, several unique icons and assets are required. Please see the Managing Xcode Assets guide for a reference on the Images.xcassets folder and how to include/reference it within your app.

• For Android TV, you should include a Banner-xhdpi.png image inside your project folder. This image should be 320×180 pixels in size.

Customization

If you’d like to display your own custom splash screen, include the splashScreen table within build.settings as above, but set the enable key to true and add an image key defining the image name. For instance:

settings =
{
    splashScreen = 
    {
        enable = true,
        image = "mySplashScreen.png"
    },
}

Alternatively, you can customize the splash screen on a per-platform basis as follows:

settings =
{
    splashScreen =
    {
        ios = {
            enable = true,
            image = "mySplashScreen_iOS.png"
        },
        android = {
            enable = true,
            image = "mySplashScreen_Android.png"
        }
    },
}

For customized implementation, image indicates the path to any image file in the project. The image will be displayed on a black background and it will match the default orientation of the app, scaled to fit the screen of the current device. You may need to experiment to arrive at the ideal image for your splash screen, but if it’s large enough for the largest device your app is intended to run on, you only need one image.

Removal

To remove default splash screen, add the splashScreen table to the project’s build.settings with the enable key set to false:

settings =
{
    splashScreen = 
    {
        enable = false
    },
}

Alternatively, you can remove the splash screen on a per-platform basis as follows:

settings =
{
    splashScreen =
    {
        ios = {
            enable = false
        },
        android = {
            enable = true
        }
    },
}