LÖVE Potion

https://lovebrew.org
Admin
LÖVE Potion is a homebrew framework for creating games and applications on Nintendo 3DS, Switch, and...
Tokens:11,826
Snippets:140
Trust Score:5.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install gdb on Unix-like (Linux, macOS)

Source: https://lovebrew.org/development/debugging

Install devkitARM-gdb and devkitA64-gdb using sudo with dkp-pacman on Unix-like systems. addr2line is already installed with the devkitPro environment.

```bash
sudo (dkp-)pacman -S devkitARM-gdb devkitA64-gdb  
```

--------------------------------

### Install required portlibs (Unix-like Linux/macOS)

Source: https://lovebrew.org/development/environment

Installs portlibs for the chosen console using the pkglist.txt file. Prepends 'sudo (dkp-)' for Unix-like systems. Replace {console} with the target console name.

```bash
sudo (dkp-)pacman -S --needed - < platform/{console}/pkglist.txt  
```

--------------------------------

### Install gdb on Windows (msys2)

Source: https://lovebrew.org/development/debugging

Install devkitARM-gdb and devkitA64-gdb using pacman in msys2. addr2line is already installed with the devkitPro environment.

```bash
pacman -S devkitARM-gdb devkitA64-gdb  
```

--------------------------------

### Install base development groups (Unix-like Linux/macOS)

Source: https://lovebrew.org/development/environment

Run in terminal after setting up devkitPro environment. Prepends 'sudo (dkp-)' to pacman command for Unix-like systems. Installs base development groups.

```bash
sudo (dkp-)pacman -Syu && sudo (dkp-)pacman -S switch-dev 3ds-dev wiiu-dev catnip  
```

--------------------------------

### Install required portlibs (Windows msys2)

Source: https://lovebrew.org/development/environment

Installs portlibs for the chosen console using the pkglist.txt file. Replace {console} with the target console name.

```bash
pacman -S --needed - < platform/{console}/pkglist.txt  
```

--------------------------------

### Install base development groups (Windows msys2)

Source: https://lovebrew.org/development/environment

Run in terminal after setting up devkitPro environment. Syncs packages and installs base development groups for Windows (msys2).

```bash
pacman -Syu && pacman -S switch-dev 3ds-dev wiiu-dev  
```

--------------------------------

### Start arm-none-eabi-gdb

Source: https://lovebrew.org/development/gnu-debugger

Start the ARM GDB debugger for the Nintendo 3DS.

```bash
/opt/devkitpro/devkitARM/bin/arm-none-eabi-gdb  
```

--------------------------------

### Handle text input and open keyboard with gamepad

Source: https://lovebrew.org/compatibility/software-keyboard

Example of using love.textinput to capture typed text and love.gamepadpressed to open the software keyboard when the 'back' button is pressed. The text is stored in a variable and drawn on screen.

```lua
local my_text = ""  
function love.textinput(text)  
    my_text = text  
end  
  
function love.draw(screen)  
    love.graphics.print(my_text)  
end  
  
function love.gamepadpressed(joystick, button)  
    if button == "back" then  
        love.keyboard.setTextInput(true)  
    end  
end  

```

--------------------------------

### Start gdb for aarch64

Source: https://lovebrew.org/development/gnu-debugger

Launch the aarch64-none-elf-gdb executable from devkitPro to begin a debugging session.

```bash
/opt/devkitpro/devkitA64/bin/aarch64-none-elf-gdb  

```

--------------------------------

### Set keyboard options in LÖVE Potion

Source: https://lovebrew.org/compatibility/software-keyboard

Example usage of love.keyboard.setTextInput with a table of options in LÖVE Potion. The options include type, password, and hint, with defaults as documented.

```lua
-- Example usage in LÖVE Potion  
love.keyboard.setTextInput(true, {  
    type = "basic",  
    password = false,  
    hint = "Enter your username"  
})  

```

--------------------------------

### Track touches with love.touchpressed, love.touchreleased, love.touchmoved

Source: https://lovebrew.org/compatibility/touch-input

Use this example to manage active touches in a table, updating positions on move and removing on release. Draws a filled circle at each touch position. The code uses the standard LÖVE touch callbacks and is suitable for touch-enabled handhelds.

```lua
local touches = {}  

function love.touchpressed(id, x, y, dx, dy, pressure)  
    touches[id] = {x = x, y = y}  
end  

function love.touchreleased(id, x, y, dx, dy, pressure)  
    touches[id] = nil  
end  

function love.touchmoved(id, x, y, dx, dy, pressure)  
    touches[id] = {x = x, y = y}  
end  

function love.draw()  
    for id, touch in pairs(touches) do  
        love.graphics.circle("fill", touch.x, touch.y, 20)  
    end  
end  
```

--------------------------------

### Stereoscopic 3D depth example

Source: https://lovebrew.org/compatibility/rendering

Uses love.graphics.getDepth() to apply stereoscopic 3D depth on the Nintendo 3DS. The example centers text on the top screen and offsets it based on the 3D slider value. Note that depth is always zero on Nintendo 2DS family systems.

```lua
local str, font = "Hello World", nil  
local textDepth = 6  
function love.load()  
    font = love.graphics.getFont()  
end  
  
function love.draw(screen)  
    if screen == "bottom" then  
        return  
    end  
  
    local sysDepth = -love.graphics.getDepth()  
  
    if screen == "right" then  
        sysDepth = -sysDepth  
    end  
  
    local left = math.floor(0.5 * (400 - font:getWidth(str)))  
    love.graphics.print("Hello World", left - sysDepth * textDepth, 120)  
end  

```

--------------------------------

### Resolve addresses with aarch64-none-elf-addr2line (Nintendo Switch)

Source: https://lovebrew.org/development/addr2line

Use this command on a Linux system with devkitA64 installed to resolve crash addresses from a Nintendo Switch LÖVE Potion game. Replace [address_one, ...] with the hex values from the crash report, such as the one after (lovepotion.nro + 0xa30498). The -aipfCe flags provide address, inlines, functions, demangled names, and line numbers.

```bash
/opt/devkitpro/devkitA64/bin/aarch64-none-elf-addr2line -aipfCe -e path/to/lovepotion.elf [address_one, ...]  
```

--------------------------------

### Resolve addresses with arm-none-eabi-addr2line (Nintendo 3DS)

Source: https://lovebrew.org/development/addr2line

Use this command on a Linux system with devkitARM installed to resolve crash addresses from a Nintendo 3DS LÖVE Potion game. Replace [address_one, ...] with the PC and LR values from the Arm11 Exceptions screen. The -aipfCe flags provide address, inlines, functions, demangled names, and line numbers.

```bash
/opt/devkitpro/devkitARM/bin/arm-none-eabi-addr2line -aipfCe arm -e path/to/lovepotion.elf [address_one, ...]  
```

--------------------------------

### Hello World in LÖVE Potion (main.lua)

Source: https://lovebrew.org/

Full source for a minimal LÖVE Potion app that draws 'Hello World!' centered on the screen and quits when a gamepad button is pressed. Place this in a 'game' directory as 'main.lua' next to the binary.

```lua
function love.draw(screen)  
    local width, height = love.graphics.getDimensions(screen)  
    love.graphics.print("Hello World!", width / 2, height / 2)  
end  
  
function love.gamepadpressed(joystick, button)  
    love.event.quit()  
end  
```

--------------------------------

### Configure [build] section in lovebrew.toml

Source: https://lovebrew.org/bundler-app/getting-started/configuration

Configures the build section of lovebrew.toml. targets selects consoles (ctr, hac, cafe), source names the game folder, and packaged controls whether the source is fused into the final binary.

```toml
[build]  
targets = ["ctr", "hac", "cafe"]  
source = "game"  
packaged = false  

```

--------------------------------

### Navigate to build directory

Source: https://lovebrew.org/development/gnu-debugger

Navigate to the directory containing the compiled LÖVE Potion ELF binary so that gdb can load the correct debug symbols.

```bash
cd path/to/build/directory  
```

--------------------------------

### Load lovepotion.elf in gdb

Source: https://lovebrew.org/development/gnu-debugger

Load the LÖVE Potion ELF binary into gdb.

```gdb
file lovepotion.elf  
```

--------------------------------

### love.filesystem.openFile

Source: https://lovebrew.org/compatibility/filesystem

Opens a file for reading or writing. On certain platforms, the same file cannot be opened more than once without being closed first.

```APIDOC
## love.filesystem.openFile

### Description
Opens a file for reading or writing. On certain platforms, the same file cannot be opened more than once without being closed first.

### Method
love.filesystem.openFile

### Parameters
- **filename** (string) - Required - The name of the file to open.
- **mode** (string) - Required - The mode to open the file in, e.g., "w" for write, "r" for read.

### Returns
- **file** (File) - The opened file object, or nil if an error occurred.
- **error** (string) - An error message if the file could not be opened.

### Example
```lua
local save_file = love.filesystem.openFile("save.dat", "w") -- create file  
save_file:write("lmao testing")  

local error = nil  

save_file, error = love.filesystem.openFile("save.dat", "r") -- open to read what we want  
save_file:read() -- save_file would be nil, so operating on a nil value  

print(error) -- might be i/o error or that the OS was busy  
```
```

--------------------------------

### Mount SD Card with love.filesystem.mountFullPath

Source: https://lovebrew.org/compatibility/filesystem

Mounts the SD card for read access. The path is /vol/external01 on Wii U. Returns true on success, prints an error message if mounting fails.

```lua
-- for Wii U, the path is /vol/external01  
local success = love.filesystem.mountFullPath("sdmc:/", "sdmc", "read", true)  
if not success then print("Failed to mount SD card!") end  

```

--------------------------------

### love.filesystem.mountFullPath

Source: https://lovebrew.org/compatibility/filesystem

Mounts an external path (like the SD card) for read/write access. This function is used to access files outside the game's sandbox.

```APIDOC
## love.filesystem.mountFullPath

### Description
Mounts an external path (like the SD card) for read/write access. This function is used to access files outside the game's sandbox.

### Method
love.filesystem.mountFullPath

### Parameters
- **path** (string) - Required - The full path to the external directory (e.g., "sdmc:/" for SD card).
- **mountpoint** (string) - Required - The mount point name to use for the mounted path.
- **access** (string) - Required - Access mode, e.g., "read" for read-only.
- **appendToPath** (boolean) - Required - Whether to append to the path.

### Returns
- **success** (boolean) - True if the mount was successful, false otherwise.

### Example
```lua
-- for Wii U, the path is /vol/external01  
local success = love.filesystem.mountFullPath("sdmc:/", "sdmc", "read", true)  
if not success then print("Failed to mount SD card!") end  
```
```

--------------------------------

### Enable console in conf.lua

Source: https://lovebrew.org/getting-started/debugging

Create or modify conf.lua in the game directory to enable the console. This is required before connecting a TCP client for debugging.

```lua
function love.conf(t)  
  t.console = true  
end  

```

--------------------------------

### Connect with netcat (nc)

Source: https://lovebrew.org/getting-started/debugging

Connect to the LÖVE Potion console using netcat. Replace <console_ip_address> with the console's IP address. There is no timeout limit, so the console waits until a connection is established.

```bash
nc <console_ip_address> 8000  

```

--------------------------------

### Reopening a File Without Closing First (Gotcha)

Source: https://lovebrew.org/compatibility/filesystem

Demonstrates the gotcha where reopening a file without closing it first causes an error on Horizon and Cafe OSes. The second openFile call returns nil and an error, and reading from nil fails.

```lua
local save_file = love.filesystem.openFile("save.dat", "w") -- create file  
save_file:write("lmao testing")  
  
local error = nil  
  
save_file, error = love.filesystem.openFile("save.dat", "r") -- open to read what we want  
save_file:read() -- save_file would be nil, so operating on a nil value  
  
print(error) -- might be i/o error or that the OS was busy  

```

--------------------------------

### Enable gdb stub in atmosphère system_settings.ini

Source: https://lovebrew.org/development/gnu-debugger

Add these settings to /atmosphere/config/system_settings.ini on the microSD card to enable the standalone gdb stub. Reboot the console after modifying the file.

```ini
[atmosphere]  
enable_htc = u8!0x0  
enable_standalone_gdbstub = u8!0x1  

```

--------------------------------

### Build for Nintendo Switch with catnip

Source: https://lovebrew.org/development/environment

Compiles the code for Nintendo Switch using the catnip build tool.

```bash
catnip -T Switch  
```

--------------------------------

### Define [metadata] section in lovebrew.toml

Source: https://lovebrew.org/bundler-app/getting-started/configuration

Defines the required game metadata for a lovebrew.toml bundle. All fields except icons are required; when icons are omitted, the default LÖVE Potion icon is used.

```toml
[metadata]  
title = "SuperGame" # title of the game  
author = "SuperAuthor" # author(s) of the game  
description = "SuperDescription" # description of the game  
version = "0.1.0" # current version, obeying semver  
icons = { ctr = "", hac = "", cafe = "" } # custom icon paths  

```

--------------------------------

### Bundle zip directory structure

Source: https://lovebrew.org/bundler-app/getting-started/structure

Shows the required top-level layout of a LÖVE Potion bundle zip: a `game` directory holding game assets and a `lovebrew.toml` configuration file at the root. The top-level folder name becomes the project name.

```text
SuperProject  
├── game  
│   ├── conf.lua  
│   └── main.lua  
└── lovebrew.toml  

```

--------------------------------

### Build for Nintendo Wii U with catnip

Source: https://lovebrew.org/development/environment

Compiles the code for Nintendo Wii U using the catnip build tool.

```bash
catnip -T WiiU  
```

--------------------------------

### Continue execution in gdb

Source: https://lovebrew.org/development/gnu-debugger

Continue execution in gdb after connecting to the console.

```gdb
continue  
```

--------------------------------

### Navigate to LÖVE Potion build directory

Source: https://lovebrew.org/development/gnu-debugger

Change the terminal to the directory containing the compiled LÖVE Potion ELF binary. This is required for gdb to load the correct debug symbols.

```bash
cd path/to/build/directory  

```

--------------------------------

### Build for Nintendo 3DS with catnip

Source: https://lovebrew.org/development/environment

Compiles the code for Nintendo 3DS using the catnip build tool.

```bash
catnip -T 3DS  
```

--------------------------------

### Manual fusing commands for Windows (Command Prompt)

Source: https://lovebrew.org/getting-started/get-lovepotion

Appends a zip file containing your game to the LÖVE Potion executable on Windows. Use the appropriate command for your console: 3DS, Switch, or Wii U. This method does not allow custom metadata such as title, icon, or author information.

```batch
:: 3DS  
copy /b lovepotion.3dsx+SuperGame.love SuperFused.3dsx  
  
:: Switch  
copy /b lovepotion.nro+SuperGame.love SuperFused.nro  
  
:: Wii U  
copy /b lovepotion.wuhb+SuperGame.love SuperFused.wuhb  

```

--------------------------------

### Set icons inline in [metadata]

Source: https://lovebrew.org/bundler-app/getting-started/configuration

Specifies custom icon paths inline within the [metadata] table. Paths are relative to the root of the bundle zip file.

```toml
[metadata]  
icons = { ctr = "path/to/3ds/icon.png", hac = "path/to/switch/icon.jpg", cafe = "path/to/wiiu/icon.png" }  

```

--------------------------------

### Manual fusing commands for Unix-like systems (macOS, Linux)

Source: https://lovebrew.org/getting-started/get-lovepotion

Appends a zip file containing your game to the LÖVE Potion executable on Unix-like systems. Use the appropriate command for your console: 3DS, Switch, or Wii U. This method does not allow custom metadata such as title, icon, or author information.

```shell
# 3DS  
cat lovepotion.3dsx SuperGame.love > SuperGame.3dsx  
  
# Switch  
cat lovepotion.nro SuperGame.love > SuperGame.nro  
  
# Wii U  
cat lovepotion.wuhb SuperGame.love > SuperGame.wuhb  

```

--------------------------------

### Change to LÖVE Potion directory

Source: https://lovebrew.org/development/environment

After cloning the repository, change working directory to the cloned LÖVE Potion folder.

```bash
cd lovepotion  
```

--------------------------------

### Set icons as sub-table in [metadata.icons]

Source: https://lovebrew.org/bundler-app/getting-started/configuration

Specifies custom icon paths using a sub-table under [metadata]. Paths are relative to the root of the bundle zip file.

```toml
[metadata.icons]  
ctr = "path/to/3ds/icon.png"  
hac = "path/to/switch/icon.jpg"  
cafe = "path/to/wiiu/icon.png"  

```

--------------------------------

### Connect with Python TCP client

Source: https://lovebrew.org/getting-started/debugging

Python TCP client script (main.py) that connects to the console's IP address on port 8000 and prints received data. Run with `python main.py <console_ip_address>`.

```python
import socket  
import sys  
  
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)  
s.connect((sys.argv[1], 8000))  
  
while True:  
  data = s.recv(1024)  
  if len(data):  
    print(data.decode ("utf-8"), end="")  

```

--------------------------------

### Share the LÖVE Potion ELF binary in gdb

Source: https://lovebrew.org/development/gnu-debugger

After running the LÖVE Potion binary on the console, load the ELF binary into gdb with the 'share' command to enable symbol resolution.

```gdb
share .  

```

--------------------------------

### Connect gdb to console

Source: https://lovebrew.org/development/gnu-debugger

Connect gdb to the console's Rosalina debugger using the IP address from the Rosalina menu. Replace {ip} with the actual IP, e.g., target remote 192.168.3.30:4003.

```gdb
target remote {ip}:4003  
```

--------------------------------

### Load system font and display Play Coin glyph

Source: https://lovebrew.org/compatibility/system-fonts

Loads the 'nintendo extended' system font on Switch to display a special glyph (Play Coin icon). Requires the glyph encoded via utf8.char("0xE075") and checks love._console to determine the platform. Avoid calling newFont repeatedly in love.draw or love.update to prevent memory issues.

```lua
local utf8 = require("utf8")

-- get the encoded utf8 of the Play Coin icon
local glyph = utf8.char("0xE075")
local font = nil

function love.load()
    -- if we're on Switch, set extended as our current font
    if love._console == "Switch" then
        font = love.graphics.newFont("nintendo extended", 14)
    end
end

function love.draw(screen)
    -- this will only render on the top
    -- screen for 3DS and will render on Switch regardless
    if (screen and screen ~= "top") then
        return
    end

    love.graphics.setFont(font)
    love.graphics.print(glyph, 10, 10)
end

```

--------------------------------

### Connect gdb to the Switch console

Source: https://lovebrew.org/development/gnu-debugger

Connect gdb to the console using the extended-remote protocol on port 22225. Replace {ip} with the console's IP address, e.g., target remote 192.168.3.30:22225.

```gdb
target extended-remote {ip}:22225  

```

--------------------------------

### love.draw with screen parameter

Source: https://lovebrew.org/compatibility/rendering

Checks the screen parameter in love.draw to render only on the top screen. The screen value is 'bottom' on Nintendo 3DS, 'default' on Nintendo Switch, and 'tv' or 'gamepad' on Nintendo Wii U.

```lua
function love.draw(screen)  
    if screen ~= "bottom" then  
        -- render top screen  
    end  
end  

```

--------------------------------

### Generate backtrace in gdb

Source: https://lovebrew.org/development/gnu-debugger

Generate a backtrace when gdb pauses on an interrupt (e.g., a segfault), showing stack frames leading to the crash.

```gdb
backtrace  
```

--------------------------------

### Generate a backtrace in gdb

Source: https://lovebrew.org/development/gnu-debugger

When the program hits an interrupt (e.g., a segfault), gdb pauses execution. Use the 'backtrace' command to display the stack frames leading to the crash.

```gdb
backtrace  

```
Tokens:
Raw