Managing Xcode Assets

This guide outlines how to customize app icons and related assets for Apple-based apps (iOS and tvOS) built with Corona.

Xcode Assets Folder

For iOS apps targeting iOS 11 or later, you must include and reference the Images.xcassets folder as outlined in this section, otherwise your app will be rejected upon submission to the App Store.

For your convenience, a default Images.xcassets folder is automatically added to all new Corona project templates. The same folder 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 Solar2D application folder here:

/Applications/Corona/Resources/Resource Library/iOS/Images.xcassets

To include and reference the Images.xcassets folder within your Corona project, proceed as follows:

  1. In the Finder, locate (or copy in) the Images.xcassets folder. Copy the entire folder to your project.

  2. Open the folder and locate the AppIcon.appiconset folder. This contains the full set of iOS app icons as follows:

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
Icon-1024.png 1024 × 1024
  1. Using these exact names and sizes as a guideline, create your own custom icon files and replace the default files in the AppIcon.appiconset folder. To avoid potential incompatibilities, your images should be non-interlaced and they shouldn't contain an embedded ICC profile.

If you're updating an older Corona project or template to use the Images.xcassets folder, you can simply move the similarly-named icon files from the root project folder (alongside main.lua) to the Images.xcassets/AppIcon.appiconset folder. However, note that you must also add the 1024×1024 Icon-1024.png file to be used for the App Store banner icon.

Note

Instead of replacing files manually, you may alternatively edit the Asset Catalog directly via Xcode by dragging and dropping it onto the Xcode dock icon. This will open a detailed UI with ability to add supplemental icons, see warnings about improperly sized or formatted icons, etc.

  1. If no tvOS release is planned, you can delete both the AppIconTV.brandassets and LaunchImageTV.launchimage folders within the Images.xcassets folder. This will not affect how icons are generated for iOS.

Build Settings

Next, you must reference and link up the Images.xcassets folder with the Corona project:

  1. Open the Corona project's build.settings file.

  2. If you're updating an older Corona project or template to use the icons within Images.xcassets/AppIcon.appiconset, remove the entire CFBundleIconFiles table (settings → iphone → plist → CFBundleIconFiles).

settings =
{
    iphone =
    {
        plist =
        {
            UILaunchStoryboardName = "LaunchScreen",
            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",
            },
        },
    },
}
  1. In the settings → iphone table, add the key-value pair of xcassets = "Images.xcassets". Note that this entry goes in the top-level iphone table, not within its plist child table.
settings =
{
    iphone =
    {
        xcassets = "Images.xcassets",
        plist =
        {
            UILaunchStoryboardName = "LaunchScreen",
        },
    },
}
  1. Save your build.settings file.

That's it! With all of these aspects in place, Corona will build the app using the specified Xcode Asset Catalog (Images.xcassets) to generate assets, icons, and plist entries.