Generating Live Builds

Live builds are a powerful and efficient way to see exactly how your in-development Solar2D app will appear on real devices. Benefits include:

Build and deploy your app just once and then see code/assets update almost instantly on your devices.

Improve your workflow by testing on multiple devices and different platforms concurrently, all from a single code base.

Iterate on projects faster without rebuilding them to see the final result, even if they use native plugins like ad providers or game networking.

Important

To use live builds on Windows, you must install iTunes.

Live Build Creation

To create a live build, simply follow these steps:

  1. In the Solar2D Simulator, open the Build dialog window (FileBuild) for either iOS, Android, or tvOS.
  1. Confirm that the first several settings are correct in terms of how you typically build an app from the Solar2D Simulator. If you're not familiar with preparing/building apps for devices, please see the following guides:

Important

Only Development provisioning profiles (iOS or tvOS) or Debug keystores (Android or Kindle Fire) can be used to produce live builds.

  1. Check the Create Live Build option and, when you're ready, click the Build button.
macOS Windows
  1. After the build is successfully completed, a .CoronaLiveBuild file will be created in the project's root directory and the project will be added to Corona Live Server.

  2. Install the app on your desired device(s) as usual. If you're not familiar with this process, please see the documentation for iOS, Android, Kindle Fire, or tvOS.

Note

You can install the same compiled/built app on multiple devices. For example, if you generate a standard .apk for Android, you can install it on multiple Android-powered devices — you don't need to create a new live build for every device you intend to test on.

  1. Run the app on the device as usual. Assuming everything is running as expected, code/asset changes that you make in your local project should be reflected almost instantly on the device.
Important
  • When you run the app, make sure that the device(s) you're using are on the same local network as the computer where Corona Live Server is running.

  • Modifications to project configuration/setup files like build.settings and config.lua will not typically be reflected when the live build updates. Thus, you should generate a new live build and re-install it on the target device(s) after modifying these project files.

  • If you experience any issues with project syncing, please consult the Troubleshooting section below.

Corona Live Server

Corona Live Server is an application which syncs project changes over your local network. Every time you create a live build, Simulator will initiate it and automatically add the built project to the Corona Live Server project list.

Notes
  • In order to sync a project, Corona Live Server must find a valid .CoronaLiveBuild file. As outlined above, this will be created when doing a live build for the project.

  • To start Corona Live Server manually, select Corona SimulatorCorona Live Server.

  • You can add a project by pressing [+] and selecting the folder containing the project, or by simply dragging and dropping a folder onto the Corona Live Server dock icon (macOS) or shortcut (Windows).

  • Clicking the "close" button on the Corona Live Server window does not shut it down. To exit/quit entirely, do so from its main application menu or, alternatively, from the right-click context menu of the dock icon (macOS) or system tray icon (Windows).

  • Closing the project list window will not stop Corona Live Server. You can re-open the window from the Window menu or by clicking on the Corona Live Server dock icon (macOS) or system tray icon (Windows).

Live Build File

Once a live build is successfully created, the source project will contain a hidden .CoronaLiveBuild file in its root directory. This file contains the information required to synchronize the project between the device and the development machine.

Typically, you will not need to edit the contents of this file. However, in very specific cases, it can be modified to customize the behavior of live builds and Corona Live Server:

key = XXXXXXXX-YYYY-ZZZZ-WWWW-AAA0987654321
#ip =
#port =

Troubleshooting

If the live build doesn't update/refresh, please proceed through the following instructions. If functionality returns to normal at any step along the way, do not proceed further.

  1. Ensure that both your computer and the device are connected to the same local network.
  2. Make sure your computer is running Corona Live Server with the same project you're running on the device.
  3. Turn off Wi-Fi on the device, wait several seconds, and turn it back on.
  4. Wait for "discoverability" to take effect. Depending on the network, this may take up to a minute.
  5. Quit Corona Live Server, then completely close/exit your app on the device. Note that merely closing the window does not quit Corona Live Server — you must explicitly exit/quit the application.
  6. Restart Corona Live Server and manually add your project to the list of synced projects as outlined in the Corona Live Server section above.
  7. Remove/uninstall the live build from the device.
  8. Rebuild the app and make sure that Create Live Build is selected from the build dialog window. Also, remember that only Development provisioning profiles (iOS or tvOS) or Debug keystores (Android or Kindle Fire) can be used to produce live builds.
  9. Start your app on the device and test for proper functionality. If the live build still doesn't update, experiment with modifying the .CoronaLiveBuild file as outlined in the Live Build File section above.
  10. If you need further assistance beyond this, please consult the Solar2D Forums.