LÖVE Template for Visual Studio Code

A pre-configured Visual Studio Code template for LÖVE including GitHub Actions for automated builds. Inspired by and adapted from LOVE VSCode Game Template and LÖVE Actions.

Features

• 🌕 Rich Lua language features with Lua Language Server
• 🐛 Debugging with Local Lua Debugger
• 🩷 Intellisense for the LÖVE API via Love2D Support
• 👨‍💻 Consistent coding styles with Editorconfig
• ️⛱️ Shader languages support
• 🐙 GitHub Local Actions
• 📦 GitHub Actions for automated builds
  • Compatible with act
• ️👷 Automated builds of the .love file from within Visual Studio Code
• 🗂️ Organized with Workspaces
• ️⚙️ Shared product configuration between the game and the GitHub Actions
• ️❄️ Nix flake to provision a dev shell

Prerequisites

• Visual Studio Code
• LÖVE 11.5 (currently only 11.5 is supported)
  • love should be in your PATH
• bash
• 7z

Setup

• Use this template to create a new repository for your game, then clone that repository locally.
• Open the Workspace.code-workspace file with Visual Studio Code.
  • You will be prompted that there are recommended extensions.
    • Click 'Install'
  • If this does not happen, install:
    • Lua
    • Local Lua Debugger
    • Love2D Support
    • Editorconfig
    • GitHub Local Actions (optional)
    • Shader languages support (optional)
• Configure .game/product.env and game/conf.lua with the settings specific to your game.
  • Make sure that PRODUCT_UUID is changed using uuidgen.
• Replace resources/icon.png with your game's high-resolution icon.

Running

• Press Alt + L or Ctrl + F5 to Run the game.
• Press F5 to Debug the game.
  • In debug mode you can use breakpoints and inspect variables.
  • This does have some performance impact though.
  • You can switch to Release mode in the Run and Debug tab (Ctrl + Shift + D)

Building

Builds a date stamped .love file and puts it in the builds folder. Doubles up as a poor man's backup system.

• Press Ctrl + Shift + B to Build the game.

Releasing

Make a new release by creating a version number git tag without the v prefix.

• Create a new tag: Use the following command to create a new tag.
  • Replace 1.0.0 with your desired version number.

git tag 1.0.0

• Push the tag to GitHub: Push the tag to the remote repository.

git push origin 1.0.0

• GitHub Actions: The GitHub workflow will automatically create a release and upload packages for all the supported platforms as an assets.

Structure

.
├── .github                   GitHub Actions configuration
├── .editorconfig             EditorConfig file
├── .vscode                   Visual Studio Code configuration
│   ├── extensions.json
│   ├── launch.json
│   ├── settings.json
│   └── tasks.json
├── builds                    Game builds
├── game
│   ├── conf.lua              LÖVE configuration file
│   ├── main.lua              The main entry point of the game
│   ├── product.env           Settings shared between the game and GitHub Actions
│   ├── assets                Game assets
│   ├── lib                   3rd party libraries
│   └── src                   Source code
├── resources                 Resources use when building the game. Icons, shared libraries, etc.
└── tools                     Tools for building and packaging the game

.vscode

The .vscode folder contains project specific configuration.

• extensions.json: Contains the list of recommended extensions
• launch.json: Contains the settings for running the game or launching the debugger
• settings.json: Contains the settings for the Lua extension
• tasks.json: Contains the settings for building the game

GitHub Actions

The GitHub Actions workflow will automatically build and package the game for all the supported platforms.

• Android
  • .apk debug and release builds for testing
  • .aab release build for the Play Store
• iOS (🚧)
• Linux
  • AppImage
  • Tarball
• macOS (🚧)
  • portable .dmg
  • App Store
• Web (️🚧)
• Windows
  • win32
  • win64
  • Self-extracting archive (64-bit only)

Android

In order to sign the APKs and AABs, the zipalign & Sign Android Release Action is used. You'll need to create Debug and Release keystores and set the appropriate secrets in the GitHub repository settings.

Debug

This creates a standard debug keystore matching Android Studio's defaults, except it is valid for 50 years.

keytool -genkey -v \
  -keystore debug.keystore \
  -alias androiddebugkey \
  -keyalg RSA -keysize 2048 -validity 18250 \
  -storepass android \
  -keypass android \
  -dname "CN=Android Debug,O=Android,C=US"

Create base64 encoded signing key to sign apps in GitHub CI.

openssl base64 < debug.keystore | tr -d '\n' | tee debug.keystore.base64.txt

Add these secrets to the GitHub repository settings:

• ANDROID_DEBUG_SIGNINGKEY_BASE64
• ANDROID_DEBUG_ALIAS
• ANDROID_DEBUG_KEYSTORE_PASSWORD
• ANDROID_DEBUG_KEY_PASSWORD

Release

This creates a release keystore with a validity of 25 years.

keytool -genkey -v \
  -keystore release-key.jks \
  -alias release-key \
  -keyalg RSA -keysize 2048 -validity 9125 \
  -storepass [secure-password] \
  -keypass [secure-password] \
  -dname "CN=[your name],O=[your organisation],L=[your town/city],S=[your state/region/county],C=[your country code]"

Create base64 encoded signing key to sign apps in GitHub CI.

openssl base64 < release-key.jks | tr -d '\n' | tee release-key.jks.base64.txt

Add these secrets to the GitHub repository settings:

• ANDROID_RELEASE_SIGNINGKEY_BASE64
• ANDROID_RELEASE_ALIAS
• ANDROID_RELEASE_KEYSTORE_PASSWORD
• ANDROID_RELEASE_KEY_PASSWORD