Project Build Settings

Build-time properties for an app are defined using a optional build.settings file written in Lua syntax. It should be placed in the project's base directory.

Note

This guide outlines the most common build settings for apps across the various platforms that Corona supports. For those developers who require more advanced settings, please consult the Advanced Build Settings guide for which options are available.

Important

Basic Structure

At the minimum, the build.settings file should contain a settings table which will contain various child tables to dictate build-time options.

settings =
{
    -- Child tables here
}

App Orientation

The build.settings file can be used to set app orientation in relation to the device's physical orientation in space — this includes auto-orientation triggered by the accelerometer if the device is rotated or flipped during runtime.

Important

Please note that there are three different things which are subject to orientation:

  1. The splash screen (see Splash Screen below).
  2. Native UI elements such as alerts and the visual keyboard.
  3. The Corona display stage itself.

All orientation settings must be contained in the orientation table within settings:

settings =
{
    orientation =
    {
        -- Parameters
    },
}

Within the orientation table, there are two optional key values: default and supported:

settings =
{
    orientation =
    {
        default = "",    -- Initial launch orientation
        supported = {},  -- Table of allowed options for auto-orientation
    },
}

Each of these accepts the following orientation conventions:

Name Orientation
"portrait" Device in the vertical position with the home button at the bottom
"portraitUpsideDown" Device in the vertical position with the home button at the top
"landscapeLeft" Device in the horizontal position with the home button at the left
"landscapeRight" Device in the horizontal position with the home button at the right

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" },
Important
  1. When the device orientation changes, the coordinate position (0,0) on the Corona display stage will correspond to the top-left corner of the current orientation.

  2. The iPad ignores the default setting and attempts to launch in the current physical orientation of the device, assuming that orientation is specified in the supported list.

  3. If you ever need to detect the current device orientation, it can be read from the system.orientation property. This will provide a value from the four standard conventions listed above. In addition, iOS devices may report either the "faceUp" or "faceDown" orientation.

iOS Build Settings

Within the settings table, you can include a plist table nested within an iphone table. This plist table is used to set values for the compiled app's Info.plist file.

settings =
{
    iphone =
    {
        plist =
        {
            CFBundleIconFiles = {},  -- Required!
            UILaunchStoryboardName = "LaunchScreen",  -- Required!
            UIStatusBarHidden = true,
            CFBundleDisplayName = "Corona App",
            CFBundleName = "Corona App",
        },
    },
}
Important
  • The iphone table encompasses all iOS devices, not just iPhone devices.

  • For boolean values in plist keys, use Lua-style booleans (true or false ) rather than Objective-C booleans (YES or NO).

In the example above, a few common plist keys are shown:

Please see Apple's documentation for more information on supported values and what you can do with them.

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.",
        },
    },
}

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).

Important

In Corona, the following APIs are affected by iOS permissions, so you should include the permission key(s) noted in the associated API documentation if you're using any of these commands:

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:

Setting/Feature Purpose
Device Capabilities Used to restrict your app to installation on devices with specific capabilities.
PNG Processing Used to circumvent PNG file processing (pngcrush) at build time.

Android Build Settings

Within the settings table, you can include an android table to control build settings for Android devices.

settings =
{
    android =
    {

    },
}

Version Code

You can override the version code entered into the Corona 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",
    },
}
Note

The version code must be specified as an integer — it cannot contain any decimal points. One possible scheme is to set versionCode to "10" for version 1.0. The next update would be "11" for version 1.1, and so forth.

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 a Corona app 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 },
        },
    },
}
Important

If you grant permission to a feature using the usesPermissions table outlined in the section above, Android assumes that this feature is also required. For example, if you grant permission to the CAMERA, the Android app store will assume that a camera is required for the app to function. Thus, devices lacking a camera will not be able to download or purchase the app. As a precaution, if your app uses the camera for some features but does not require it for "basic functionality," you should include the feature within the usesFeatures table and set its required key to false:

{ name="android.hardware.camera", 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 Corona 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",
        },
    },
}

Using expansion files requires setup of Google licensing. Please see here for details.

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:

Setting/Feature Purpose
Minimum SDK Version Allows you to exclude your app from being installed on devices with older versions of Android.
Android TV Required if you are deploying an app to Android TV.
Screen Support Specifies/limits which screens an Android app supports.
Disabling File Access Used to block all access to your app's files.
Large Heap Requests that the Android OS provides your app with more heap memory.
Android Directives Used to fine-tune the AndroidManifest.xml in your application.

Desktop Build Settings

For macOS desktop or Win32 desktop apps, the Corona build.settings file supports a window table for customizing the app's desktop window:

settings =
{
    window =
    {

    },
}

Please see the example within Creating macOS Desktop Apps or Creating Win32 Desktop Apps for details and a complete list of acceptable window parameters.

Plugins

Corona offers several plugins which can be used in your projects. These plugins can be included via the plugins table nested within the settings table:

settings =
{
    plugins =
    {

    }, 
}

For example, the Google Play Games Services plugin may be included as follows:

settings =
{
    plugins =
    {
        ["plugin.gpgs"] =
        {
            publisherId = "com.coronalabs"
        },
    }, 
}
Important

Plugin key names often include punctuation, for example plugin.gpgs. In these cases, you must use the "brackets and quotes" method of defining the key (["plugin.gpgs"]).

Custom App Icons

Before deploying an app, you should design the proper app icons for the targeted platforms. These icons must be designed at the sizes specified below, exported in .png format, and then you should place them inside the project's root folder. To avoid potential incompatibilities, these images should also be non-interlaced and they shouldn't contain an embedded ICC profile.

Important

Icon image files must be placed in the project's root folder, not inside a subfolder.

iOS

For iOS, all icons should adhere to the names and sizes listed below. For detailed information on creating icons, please refer to the iOS Human Interface Guidelines.

File Size (w×h)
Icon-40.png 40 × 40
Icon-58.png 58 × 58
Icon-76.png 76 × 76
Icon-80.png 80 × 80
Icon-87.png 87 × 87
Icon-120.png 120 × 120
Icon-152.png 152 × 152
Icon-167.png 167 × 167
Icon-180.png 180 × 180

Additionally, you must specify these file names in the CFBundleIconFiles table as follows:

settings =
{
    iphone =
    {
        plist =
        {
            CFBundleIconFiles = {
                "Icon-40.png",
                "Icon-58.png",
                "Icon-76.png",
                "Icon-80.png",
                "Icon-87.png",
                "Icon-120.png",
                "Icon-152.png",
                "Icon-167.png",
                "Icon-180.png",
            },
        },
    },
}

Android

For Android, icon files will be copied into the .apk during the build, assuming they are available in your project folder. 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.

File Size (w×h)
Icon-xxxhdpi.png 192 × 192
Icon-xxhdpi.png 144 × 144
Icon-xhdpi.png 96 × 96
Icon-hdpi.png 72 × 72
Icon-mdpi.png 48 × 48
Icon-ldpi.png 36 × 36

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 Corona 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 Corona 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 here for details.

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

Splash/Launch Screen

Corona Splash Screen

By default, a Corona-branded splash screen will appear when the app opens. This splash screen can be customized or disabled with purchase of the Splash Screen Control plugin. Please see the documentation for details on configuring the splash screen via build.settings, assuming you've purchased the plugin.

iOS Launch Screen

For iOS, you must include some form of launch screen support. Apple recommends that you utilize an Xcode-generated storyboard for this, since a single storyboard is flexible and adaptable for all launch screens across all devices.

For your convenience, a default (blank) LaunchScreen.storyboardc document is automatically added to all new project templates. The same file is also bundled with the Corona application itself, in case you need to copy it over to existing projects. It can be found within the Corona SDK application folder here:

/Resource Library/iOS/LaunchScreen.storyboardc

The Xcode storyboard document can be customized with your own images/layout — see our guide for instructions.

Important

If you use the default LaunchScreen.storyboardc file in an existing project, you must include the UILaunchStoryboardName key within the plist table so that iOS recognizes the existence of the file. Notice that the key's value ("LaunchScreen") matches the name of the file itself, minus the file extension:

settings =
{
    iphone =
    {
        plist =
        {
            UILaunchStoryboardName = "LaunchScreen",  -- Required!
        },
    },
}

Excluding Files

More sophisticated apps may have files which are needed on one platform but not another. For example, the icon files for each platform are different and you might want to include only the appropriate files on each platform. This is not something Corona SDK handles automatically, since file naming may vary and unique situations can't be predicted. Most developers will not need to specify files which should be excluded from builds, but the option is available if necessary.

Files to be excluded are specified per-platform — ios, android, macos, win32, tvos, or all using simple pattern matching where * means any string of characters, sometimes including /. In other words, these patterns match the path names of files in the app bundle as strings. This generally only matters if you have an elaborate directory structure with multiple instances of directories with the same name at different levels, for example a/music, a/b/music, a/b/c/music, etc. Note that the directory separator character is always a forward slash /, even if building on Windows.

File exclusion is a powerful facility and it's possible to corrupt your app bundle if you use this procedure unwisely and accidentally exclude files critical to its operation. After making any changes to the excludeFiles setup, monitor the console carefully during the next build and watch for any issues. You should also examine the contents of your app bundle carefully and check exactly which files are included.

settings =
{
    excludeFiles =
    {
        -- Exclude all files at paths which end with "secret.txt"
        all = { "*secret.txt" },
        
        -- Exclude all Android icon files and .ogg files in the "music" directory
        ios = { "Icon-*dpi.png", "music/*.ogg" },

        -- Exclude iOS "retina" image files and .m4a files in the "music" directory
        android = { "Icon.png", "*@2x.png", "music/*.m4a" },
        
        -- Exclude unnecessary assets from macOS desktop apps
        macos = { "Default*.png", "Icon*.png", "Icon*.ico", "Icon*.icns" },
        
        -- Exclude unnecessary assets from Win32 desktop apps
        win32 = { "Default*.png", "Icon*.png", "Icon*.ico", "Icon*.icns" },
        
        -- Exclude all Android icon files and .ogg files in the "music" directory
        tvos = { "Icon-*dpi.png", "music/*.ogg" },
    },
}

Excluding files is a feature of Corona SDK — it does not work for Corona Enterprise builds.