# How to add analytics to a LÖVE (Love2D) game

> Track a LÖVE (Love2D) game: lua-https in a love.thread, a saved player ID, a queue in the save folder, consent, and why stock LÖVE 11.5 has no HTTPS.

By Yos Riady. Updated 2026-11-18. Published 2026-11-18. Canonical URL: https://manalens.dev/blog/love2d-analytics

Send events from a love.thread with the lua-https module to /v0/events, up to 50 per request. LÖVE 11.5 is the current stable release, and the LÖVE wiki lists lua-https as available since 12.0, which is still in development. So compile lua-https for 11.5 or use a 12.0 build, and keep the queue in the save folder.

## Key points

- Stock LÖVE 11.5 cannot reach an https:// collector, so compile lua-https for it or use a LÖVE 12.0 build.
- Run https.request() in a love.thread, because a blocking call blocks the whole LÖVE main loop.
- Set Content-Type to application/json in lua-https, or the module sends the body as a form and the collector cannot read the JSON.

## Which route fits a LÖVE game?

lua-https in a background thread. LÖVE bundles LuaSocket, but socket.http speaks plain HTTP only: an https:// URL needs LuaSec, which LÖVE does not ship. The LÖVE wiki describes lua-https as a simple Lua HTTPS module that uses the native platform backends on Windows, Linux, macOS, iOS and Android.

lua-https is part of LÖVE 12.0, which the wiki still marks as in development, with unofficial nightly builds. The wiki also says you can compile it from source for earlier versions. Either way, require("https") gives https.request(url, options), which returns the status code, or 0 on failure.

https.request() returns only when the request ends, so the code runs it in a love.thread. The game loop sends a batch to the thread on a channel and reads the status code back on another channel.

Sources: LÖVE wiki, lua-https, 12.0, socket and love.thread.

## What must every LÖVE event contain?

One JSON envelope, the same one the Godot and Unity SDKs send. POST it to /v0/events on your collector with two headers: x-publishable-key and Content-Type: application/json. The body is {"events": [...]} with 1 to 50 events. A good request returns {"accepted":N}.

- type "track", an event name in snake_case, channel "app" and version (your tracker version, up to 32 characters).
- message_id: a new UUID version 4 for each event. Keep it on a retry. The collector counts each message_id once.
- anonymous_id: one UUID version 4 per install, saved on the device. The collector checks the version digit, so a random hex string of the same length is refused.
- session_id: 1 to 64 characters of letters, digits and . _ : -. Start a new one after 30 minutes without play.
- original_timestamp: the time of the event in ISO 8601 UTC, such as 2026-11-09T10:00:00Z. It can be up to 7 days old, and at most 10 minutes in the future.
- context.app.platform (windows, macos, linux, web, android, ios or other) and engine "other". Add storefront, app_version and build to filter reports by build.
- properties: a flat object of strings, numbers, booleans or null.

Sources: Manalens app events documentation.

## How do I send events from LÖVE?

LÖVE has no JSON encoder, so this code uses json.lua by rxi, a small pure Lua library. Copy json.lua into your project. It encodes an empty table as [], so track() leaves properties out when there are none; the collector treats a missing properties field as empty.

love.math.random() is seeded at startup, the wiki says, so the UUID helper needs no seed. lua-https sends the data as a form body unless you set Content-Type, so the worker sets application/json.

``` Lua (main.lua, LÖVE 12.0 or lua-https built for 11.5)
-- main.lua (conf.lua sets t.identity = "my_game")
local json = require("json") -- json.lua by rxi
local URL, KEY = "https://YOUR_COLLECTOR_ENDPOINT/v0/events", "YOUR_PUBLISHABLE_KEY"
local WORKER = [[
local https = require("https")
local url, key = ...
local jobs, results = love.thread.getChannel("mana_jobs"), love.thread.getChannel("mana_results")
while true do
  local body = jobs:demand()
  local code = https.request(url, { method = "POST", data = body,
    headers = { ["Content-Type"] = "application/json", ["x-publishable-key"] = key } })
  results:push(code)
end
]]
local PLATFORMS = { Windows = "windows", ["OS X"] = "macos", Linux = "linux", Android = "android", iOS = "ios" }
local WEEK = 7 * 24 * 3600
local st, queue, inflight, retry_at, backoff, next_flush, session_id = {}, {}, 0, 0, 2, 0, nil

local function uuid4()
  local b = {}
  for i = 1, 16 do b[i] = love.math.random(0, 255) end
  b[7], b[9] = b[7] % 16 + 64, b[9] % 64 + 128
  local s = string.format(string.rep("%02x", 16), unpack(b))
  return s:sub(1, 8) .. "-" .. s:sub(9, 12) .. "-" .. s:sub(13, 16) .. "-" .. s:sub(17, 20) .. "-" .. s:sub(21)
end
local function now_iso(t) return os.date("!%Y-%m-%dT%H:%M:%S.000Z", t) end
local function save_queue() love.filesystem.write("mana_queue.json", json.encode(queue)) end
local function save_state() love.filesystem.write("mana_state.json", json.encode(st)) end

function track(name, props)
  if not st.consent then return end
  if props and next(props) == nil then props = nil end
  queue[#queue + 1] = { type = "track", event = name, channel = "app", version = "0.1.0",
    message_id = uuid4(), anonymous_id = st.anonymous_id, session_id = session_id,
    original_timestamp = now_iso(), properties = props,
    context = { app = { platform = PLATFORMS[love.system.getOS()] or "other", storefront = "itch",
      app_version = "1.4.0", build = "571", engine = "other" },
      locale = "en", library_name = "my-game", library_version = "1.4.0" } }
  if #queue > 1000 and inflight == 0 then table.remove(queue, 1) end
  save_queue()
end

local function start()
  local first = st.first_open_at == nil
  if first then st.first_open_at = now_iso(); save_state() end
  track("game_open", { is_first_open = first, first_open_at = st.first_open_at })
  track("session_start")
end

function set_consent(on)
  if on and not st.consent then
    st.consent, st.anonymous_id = true, st.anonymous_id or uuid4()
    save_state()
    start()
  elseif not on then
    st, queue = {}, {}
    love.filesystem.remove("mana_state.json")
    love.filesystem.remove("mana_queue.json")
  end
end

local function load_json(name)
  local text = love.filesystem.read(name)
  local ok, value = pcall(json.decode, text or "")
  return ok and value or nil
end

function love.load()
  st = load_json("mana_state.json") or {}
  queue = load_json("mana_queue.json") or {}
  session_id = uuid4()
  love.thread.newThread(WORKER):start(URL, KEY)
  if st.consent then start() end
end

function love.update(dt)
  local code = love.thread.getChannel("mana_results"):pop()
  if code then
    if (code >= 200 and code < 300) or (code >= 400 and code < 500 and code ~= 408 and code ~= 429) then
      for _ = 1, math.min(inflight, #queue) do table.remove(queue, 1) end
      save_queue()
      backoff = 2
    else
      retry_at = love.timer.getTime() + backoff
      backoff = math.min(backoff * 2, 300)
    end
    inflight = 0
  end
  local now = love.timer.getTime()
  if now >= next_flush and now >= retry_at and inflight == 0 and st.consent then
    local cutoff = now_iso(os.time() - WEEK)
    while queue[1] and queue[1].original_timestamp < cutoff do table.remove(queue, 1) end
    if #queue > 0 then
      inflight = math.min(50, #queue)
      local batch = {}
      for i = 1, inflight do batch[i] = queue[i] end
      love.thread.getChannel("mana_jobs"):push(json.encode({ events = batch }))
    end
    next_flush = now + 10
  end
end
```

Sources: LÖVE wiki, lua-https, love.thread, Channel, love.math.random, love.filesystem and love.system.getOS; json.lua by rxi.

## How do I track events and end a session?

Call track() from gameplay code and set_consent() from your consent screen. love.quit() runs when the game is closed, so queue session_end there. The queue is already on disk, so the events go out at the next launch; the code does not send at quit, because https.request() would hold the window open.

love.focus(false) runs when the window loses focus. Use it to mark the start of an idle period, and start a new session when the player returns after 30 minutes.

``` Lua (main.lua, continued)
local session_started, idle_since = love.timer.getTime(), nil

function love.quit()
  track("session_end", { duration_s = math.floor(love.timer.getTime() - session_started) })
  return false -- let the game close
end

function love.focus(focused)
  if not focused then idle_since = love.timer.getTime() return end
  if idle_since and love.timer.getTime() - idle_since > 30 * 60 then
    track("session_end", { duration_s = math.floor(idle_since - session_started) })
    session_id, session_started = uuid4(), love.timer.getTime()
    track("session_start")
  end
  idle_since = nil
end

-- Gameplay:
-- track("level_complete", { level = 3, attempt = 1, score = 1200 })
```

Sources: LÖVE wiki, love.quit, love.focus and love.timer.getTime; Manalens app events documentation.

## How do the player ID, the offline queue and consent work?

The anonymous_id is a UUID version 4 in mana_state.json, created when the player gives consent. The queue is in mana_queue.json, capped at 1,000 events, and written on every track() call. Both files are in the LÖVE save folder: %appdata%\LOVE plus the identity on Windows, ~/Library/Application Support/LOVE on macOS and ~/.local/share/love on Linux. A fused game uses its own folder.

Keep the batch and wait longer before each retry after a network error or a 5xx, 408 or 429 response. Drop it after any other 4xx, because the collector refused the data and a retry gets the same answer. The flush also drops events older than 7 days, because one old event refuses the whole batch with 400.

Until consent is true, track() does nothing and no ID is written. set_consent(false) deletes both files. Whether your game needs consent is a decision for you and your legal advisers.

Sources: LÖVE wiki, love.filesystem and love.filesystem.write; Manalens app events documentation.

## What changes for web, desktop and mobile builds?

The LÖVE wiki lists Windows, macOS, Linux, Android and iOS as distribution targets. A native build sends no Origin header, so CORS does not apply, and the collector accepts the request with the Publishable key alone.

- Web: there is no official web export. The wiki points to love.js, a community port, and notes that it does not support threads and can lag behind LÖVE releases. This code does not run there. In a browser, the request would also need CORS: the collector answers the preflight for your project domain, its subdomains and Allowed origins.
- Android: building lua-https into an older love-android means compiling it into the Lua modules of the Android project, the wiki says.
- Mobile: use an https:// endpoint, because Android and iOS block cleartext HTTP by default. lua-https uses the platform TLS stack.

Sources: LÖVE wiki, Game Distribution and lua-https; Manalens app events documentation.

## What are the LÖVE gotchas?

Most of these are about HTTPS and blocking calls.

- Stock LÖVE 11.5 cannot reach an https:// collector: socket.http needs LuaSec for HTTPS, and LÖVE does not ship it.
- LuaSocket and lua-https calls block. The wiki says a blocking operation blocks the whole LÖVE main loop, so run them in a love.thread.
- lua-https sends data as application/x-www-form-urlencoded unless you set Content-Type. Without the header, the collector cannot read the JSON.
- Writes fail with Could not set write directory until you set t.identity in conf.lua or call love.filesystem.setIdentity().
- A thread loads only love.data, love.filesystem and love.thread. Errors inside it go to love.threaderror(), so add that callback while you test.

Sources: LÖVE wiki, socket, lua-https, love.filesystem.write, love.thread and Game Distribution.

## How do I check that LÖVE events arrive?

Send one batch from a development build and read the response status. Print the code that the worker pushes back on the mana_results channel: it should be 200.

1. Create a test project in Manalens and copy its Publishable key.
2. Run the game with a LÖVE build that has lua-https, from a terminal so you see print output.
3. Send game_open and session_start from the LÖVE build, then check that the response is {"accepted":2}.
4. Open the activity feed and check that platform, build and engine are set on the events.
5. Switch off the network, play for a minute, switch it on, and check that the queued events arrive once.
6. Replace the test key with the production Publishable key before you ship.

Sources: Manalens app events documentation.

## How do I start?

Manalens is the analytics and growth engine built for games. Add the worker thread to your LÖVE game, ask for consent, and use the Game KPIs board to see D1 retention and session length for each build.

- [All installation options](https://manalens.dev/docs/install)

Sources: Manalens product documentation.

## Frequently asked questions

### Can LÖVE 11.5 send HTTPS requests?

Not out of the box. LÖVE bundles LuaSocket, whose socket.http needs LuaSec for https:// URLs, and LÖVE does not ship LuaSec. Use the lua-https module: the LÖVE wiki lists it as part of 12.0, which is still in development, and says you can compile it from source for earlier versions.

### Why does my LÖVE game freeze when it sends events?

Because https.request() and socket.http return only when the request ends, and the LÖVE wiki says a blocking call blocks the whole main loop. Run the request in a love.thread, push the JSON batch on a channel, and read the status code back in love.update(), as the code sample does.

### Where does LÖVE save the analytics files?

In the save folder that love.filesystem writes to: %appdata%\LOVE plus your identity on Windows, ~/Library/Application Support/LOVE on macOS and ~/.local/share/love on Linux. Set t.identity in conf.lua first, or every write fails. A fused game uses its own folder name instead of the LOVE folder.

### Does this work in a LÖVE web build?

No. LÖVE has no official web export. The LÖVE wiki points to love.js, a community port, and says it does not support threads, so the threaded sender in this guide does not run there. For a browser game, consider an engine with a web target, or write a separate JavaScript sender.

## Sources

- [LÖVE wiki: lua-https (read 18 November 2026)](https://love2d.org/wiki/lua-https)
- [LÖVE wiki: 12.0 (read 18 November 2026)](https://love2d.org/wiki/12.0)
- [LÖVE wiki: socket (read 18 November 2026)](https://love2d.org/wiki/socket)
- [LÖVE wiki: love.thread (read 18 November 2026)](https://love2d.org/wiki/love.thread)
- [LÖVE wiki: love.filesystem (read 18 November 2026)](https://love2d.org/wiki/love.filesystem)
- [LÖVE wiki: love.quit (read 18 November 2026)](https://love2d.org/wiki/love.quit)
- [LÖVE wiki: love.math.random (read 18 November 2026)](https://love2d.org/wiki/love.math.random)
- [LÖVE wiki: Game Distribution (read 18 November 2026)](https://love2d.org/wiki/Game_Distribution)

## Related guides

- [Game marketing measurement guide](https://manalens.dev/blog/game-marketing-measurement-guide)
- [Engine analytics compared: Unreal, Godot, GameMaker, Construct, Phaser](https://manalens.dev/blog/game-engine-analytics-compared)
- [How to add analytics to a Defold game](https://manalens.dev/blog/defold-analytics)
- [How to add analytics to a Pico-8 game](https://manalens.dev/blog/pico-8-analytics)
- [What events to track first in your game](https://manalens.dev/blog/game-tracking-plan-first-events)
- [Player analytics guides](https://manalens.dev/blog/topic/player-analytics)
- [How to add analytics to a Godot game](https://manalens.dev/blog/godot-analytics)
- [How to add analytics to a GameMaker game](https://manalens.dev/blog/gamemaker-analytics)
- [How to add analytics to a GDevelop game](https://manalens.dev/blog/gdevelop-analytics)
- [How to add analytics to a Phaser game](https://manalens.dev/blog/phaser-analytics)
