LÖVE2D Mobile Publishing Guide

How a LÖVE2D game is structured

LÖVE2D games are written in Lua. The most important file is main.lua. When LÖVE starts your game, it looks for this file first.

A simple LÖVE project usually looks like this:

my-game/
  main.lua
  conf.lua
  assets/
    images/
    audio/
    fonts/
  src/
    player.lua
    menu.lua

The 3 main LÖVE functions

Small test game

function love.load()
  message = "Hello from LÖVE2D!"
end

function love.update(dt)
  -- dt means delta time. It helps movement feel smooth.
end

function love.draw()
  love.graphics.print(message, 40, 40)
end

Example conf.lua

conf.lua is optional, but it is useful. It runs before the game starts and lets you set title, size, identity, and other settings.

function love.conf(t)
  t.identity = "mygame"
  t.window.title = "My Game"
  t.window.width = 1280
  t.window.height = 720
  t.window.resizable = false
end

What is a .love file?

A .love file is your game packed into one file. It is basically a zip file with your game files inside it.

The important rule: main.lua must be at the top level of the archive, not hidden inside another folder.

Correct:
  game.love
    main.lua
    conf.lua
    assets/

Wrong:
  game.love
    my-game-folder/
      main.lua

Mobile game tips before packaging

• Make UI scale to different screen sizes.
• Use touch controls, not only keyboard controls.
• Compress large images and audio files.
• Test portrait and landscape early.
• Do not use copyrighted music, images, or characters.
• Test saving/loading before store release.

Publish a LÖVE2D game to Google Play

For Android, the normal path is to use the official love-android project. You put your LÖVE game inside the Android project, build a release file, sign it, and upload it to Google Play Console.

APK vs AAB

Android setup steps

1. Install Android Studio. It includes the Android SDK and tools you need.
2. Clone love-android. This is the Android wrapper/project for LÖVE games.
3. Add your LÖVE game files. Put your game inside the embed assets folder.
4. Set app information. App name, package name, version code, version name, orientation, and permissions.
5. Build debug APK. Test it on your phone first.
6. Build release AAB. This is normally what you upload to Google Play.
7. Complete Play Console setup. Store page, data safety, age rating, screenshots, and testing.

Updated notes from older Android tutorials

Older LÖVE2D Android videos are still useful for understanding the basic idea: install Android tools, clone love-android, put your game into the Android project, build an APK, and test it on a real phone. Some details have changed, so use the current love-android README and Google Play rules for final builds.

Example command workflow

This is a common terminal workflow. On Windows, use Git Bash, PowerShell, or Android Studio terminal.

git clone --recurse-submodules https://github.com/love2d/love-android
cd love-android

mkdir -p app/src/embed/assets
cp -R /path/to/your/game/* app/src/embed/assets/

./gradlew assembleEmbedNoRecordDebug
./gradlew assembleEmbedNoRecordRelease
./gradlew bundleEmbedNoRecordRelease

How to embed your game

Android settings you must understand

• applicationId or app.application_id: your unique package name, like com.yourstudio.yourgame.
• versionCode: an internal number. Increase it every update.
• versionName: the visible version, like 1.0.0.
• targetSdk: the Android version you target. Google Play currently requires Android 15 / API 35 or higher for new apps and updates.
• Signing key / keystore: the private key used to sign your app. Keep it safe.

app.name=My Puzzle Game
app.application_id=com.yourstudio.mypuzzlegame
app.orientation=landscape
app.version_code=1
app.version_name=1.0.0

Google Play requirements to remember

Install and test on a real Android device

For development, use a debug APK on a real device before you prepare the store build. Android Studio and ADB are usually faster and cleaner than copying APK files manually.

1. Enable Developer options and USB debugging on the phone.
2. Connect by USB, or use wireless debugging on Android 11 or higher.
3. Check the device with adb devices.
4. Install the debug APK with adb install -r path/to/your-game.apk.
5. Run the game, rotate the device if supported, test touch input, save/load, audio pause/resume, and performance.
6. Use adb logcat when the game crashes or shows a black screen.

Before uploading to Google Play

• Test the APK on a real Android phone.
• Build a signed release AAB.
• Check that the game saves data correctly.
• Check that screen orientation is correct.
• Remove unused permissions.
• Prepare screenshots, icon, feature graphic, description, and privacy policy.

Publish a LÖVE2D game to the Apple App Store

iOS publishing is more manual than Android. You need a Mac, Xcode, an Apple Developer account, signing, provisioning, App Store Connect, and TestFlight.

iOS setup steps

1. Use a Mac. iOS builds require Xcode, and Xcode runs on macOS.
2. Install Xcode. Use the version Apple currently requires for App Store uploads.
3. Join Apple Developer Program. You need this for App Store publishing and device signing.
4. Download LÖVE source and Apple dependencies. Match versions when possible.
5. Open the Xcode project. Select the iOS target.
6. Add your game. Include your game files or packaged game.love.
7. Set signing. Use your team, bundle ID, capabilities, version, and build number.
8. Test with real device and TestFlight. Then submit for review.

Example iOS source setup

This is a common source-based setup pattern. The exact branch/version should match the LÖVE version you want to use.

git clone --depth 1 --branch 11.5 https://github.com/love2d/love.git
git clone --depth 1 --branch 11.5 https://github.com/love2d/love-apple-dependencies.git

cp -R love-apple-dependencies/iOS/libraries love/platform/xcode/ios/
cp -R love-apple-dependencies/shared love/platform/xcode/

open love/platform/xcode/love.xcodeproj

What signing means in simple words

Apple signing proves that the app comes from your Apple Developer account and that it is allowed to run on devices or be uploaded to App Store Connect.

App Store Connect flow

1. Create a new app record in App Store Connect.
2. Set the name, bundle ID, SKU, platform, and primary language.
3. Upload your build from Xcode Organizer or Transporter.
4. Add screenshots, description, keywords, age rating, privacy details, and pricing.
5. Test using TestFlight.
6. Submit the app for App Review.

iOS beginner warnings

• Use the correct Xcode version before uploading.
• Increase the build number every upload.
• Use a real iPhone/iPad for testing, not only Simulator.
• Do not add capabilities you do not use.
• Answer privacy and age-rating questions carefully.
• Apple review can reject apps for crashes, misleading content, missing privacy info, or broken features.

Store listing, screenshots, and privacy

Publishing is not only about the build file. Google and Apple also check your store page, screenshots, privacy answers, age rating, and policies.

Google Play store page

Apple App Store page

Simple store description template

Short description:
A simple and fun 2D game made for quick mobile play.

Full description:
Play [Game Name], a simple 2D game where you [main action].

Features:
- Easy controls
- Fast rounds
- Clean 2D style
- Fun gameplay for short sessions

Download now and start playing.

Privacy policy reminder

Even if your game does not collect data, stores may still ask you to confirm that clearly.

Monetization basics for mobile games

Ads and in-app purchases can help a free game earn money, but they also add policy, privacy, testing, and support work. Decide what you will sell or show before release so the app, store listing, and privacy answers all match.

Which monetization type should you use?

Ads setup checklist

Best ad formats for simple games

Privacy and consent for ads

• On Google Play, complete the Data safety form based on what your app and third-party SDKs collect or share. The developer is responsible for accurate declarations.
• If ads use personal data or advertising identifiers, explain that in the privacy policy and store forms.
• For regions that require consent, use a consent flow before requesting personalized ads. Google's User Messaging Platform SDK can manage privacy choices for AdMob.
• For iOS 14.5 or later, Apple requires App Tracking Transparency permission before tracking users or accessing the advertising identifier.
• If the game is for children or teens, check Google Play Families, AdMob family rules, Apple kids category rules, and age rating answers before showing ads.

Google Play in-app purchases

For digital goods or features sold inside a Google Play-distributed game, use Google Play's billing system unless a specific policy exception applies. Digital game examples include coins, extra lives, characters, ad-free upgrades, new levels, and subscriptions.

Purchase flow you should support

1. Load products from the store. Do not hardcode final prices in your UI; show the localized price returned by the store.
2. Start the official purchase flow. Use Play Billing on Android or StoreKit on iOS.
3. Verify the purchase. For stronger security, verify purchases with your backend before granting expensive items.
4. Grant the reward once. Add coins, unlock premium, or remove ads only after a valid purchase result.
5. Acknowledge or consume. Acknowledge non-consumables and subscriptions. Consume consumables only after the item is granted.
6. Restore and query purchases. On app start and after reinstall, check existing entitlements so users keep what they paid for.
7. Handle refunds and cancellations. Remove or update entitlements when a purchase is refunded, canceled, expired, or revoked.

Apple in-app purchases

For iPhone and iPad, create purchases in App Store Connect and use StoreKit in the iOS app. Apple supports consumable, non-consumable, auto-renewable subscription, and non-renewing subscription products.

• Create the product in App Store Connect with a clear reference name and product ID.
• Use StoreKit to load product information, start payments, handle transaction updates, and deliver the purchased content.
• Provide a restore purchases option for restorable products, such as non-consumables and subscriptions.
• Use StoreKit Testing, sandbox testing, and TestFlight before App Review. In-app purchases in TestFlight use the sandbox environment, are free for testers, and do not carry into production.
• Submit in-app purchases for review with the app when required.

LÖVE2D integration note

• Keep game rewards in Lua, but keep store purchase validation in native code or on a backend.
• Never unlock paid items only from a local Lua flag that can be edited easily.
• For "remove ads", save the entitlement and check it before loading any ad placement.
• For coins or gems, use server validation if the economy matters or if purchases are expensive.

Store disclosure checklist

Official monetization links

• Google Play billing system
• Google Play Billing Library version deprecation
• Create an in-app product in Play Console
• Set up Google Mobile Ads SDK for Android
• Set up Google UMP SDK for AdMob consent
• Google Play Data safety form help
• Apple In-App Purchase overview
• Apple user privacy and data use

Final publishing checklist

Use this page before you send your app for review.

Game quality

Android checklist

• Package name is final, for example com.yourstudio.yourgame.
• versionCode increased.
• versionName correct.
• love-android cloned with submodules, or submodules initialized after cloning.
• JDK, Android SDK, NDK, and CMake versions match the current love-android README.
• Target API requirement checked.
• Release build signed.
• AAB built for Google Play.
• APK tested on a real Android phone through Android Studio, ADB, or a trusted manual install.
• Keystore backed up safely.
• Ad SDK, Play Billing Library, and purchase products checked if monetization is used.
• AD_ID and BILLING permissions checked and only included when needed.

iOS checklist

• Mac and correct Xcode version ready.
• Bundle ID is final and matches App Store Connect.
• Signing team selected.
• Version and build number set.
• Real iPhone/iPad tested.
• TestFlight tested.
• App Store Connect metadata completed.
• StoreKit products, restore purchases, sandbox purchases, and ATT prompt checked if monetization is used.

Store checklist

• Icon ready.
• Screenshots ready.
• Short description ready.
• Full description ready.
• Privacy policy URL ready.
• Data safety / app privacy completed.
• Contains ads / in-app purchase disclosures completed if used.
• Ad placements, consent flow, and purchase restore flow tested.
• Age rating completed.
• Release notes written.

Common problems and simple answers

Why does my .love file not run?

Most of the time, main.lua is not at the top level of the archive. Open the file and make sure main.lua is not inside another folder.

Should I upload APK or AAB to Google Play?

Use APK for testing. Use AAB for Google Play release.

Can I still follow older LÖVE2D Android videos?

Use them for the general workflow, but check current instructions before building. The useful parts are still cloning love-android with submodules, installing Android SDK/NDK tools, embedding your game, and testing on a real device. Avoid outdated APKTool or manual repackaging steps unless the current love-android docs explicitly say to use them.

Do I need to copy APK files manually to my phone?

No. Manual copying can work for quick testing, but Android Studio or adb install -r path/to/app.apk is usually faster. If you install from a file manager, Android may require "install unknown apps" permission for that file manager.

Why is Android Studio showing Gradle errors?

Common reasons are wrong JDK version, missing Android SDK/NDK, old Gradle files, or mixing incompatible LÖVE/love-android versions. Use a released tag and follow that version's instructions.

Do I need microphone permission?

No, not unless your game actually records audio or uses the microphone. For most games, use the NoRecord build variant.

Can I publish iOS from Windows?

Not normally. iOS publishing needs Xcode, and Xcode requires macOS.

What is the difference between version and build number?

The version is what users see, like 1.0.0. The build number is an internal upload number. You must increase it every upload, especially on iOS.

What is love-release?

love-release is a helper tool for packaging LÖVE games, mostly useful for desktop or .love workflows. For mobile stores, learn the official Android and iOS build paths first.

Do I need a privacy policy?

You should have one if your app collects data, uses ads, analytics, crash reporting, accounts, online features, purchases, or third-party SDKs. Even simple games may need privacy answers in the store dashboard.

Can I add ads to a LÖVE2D mobile game?

Yes, but usually not from Lua alone. You normally add the ad SDK to the Android or iOS wrapper project, then bridge ad events back to your LÖVE game.

Can I sell coins, remove ads, or unlock levels?

Yes. Use Google Play Billing for Android digital goods and StoreKit for Apple platforms. Use consumable products for repeat purchases like coins, and non-consumable products for permanent unlocks like remove ads.

Should I use rewarded ads or interstitial ads?

Rewarded ads are usually safer for small games because the player chooses to watch them. Interstitial ads should only appear at natural breaks, not during active gameplay or near touch controls.

Useful official links

• LÖVE Wiki
• love-android GitHub
• LÖVE GitHub
• love-apple-dependencies GitHub
• Google Play target API requirement
• Android App Bundle guide
• Install Android NDK and CMake
• Run apps on a hardware device
• Android Debug Bridge
• Google Play billing system
• Google Mobile Ads SDK for Android
• Apple upcoming requirements
• Apple In-App Purchase