itchy/ReadMe.md

itchy

A super simple version checker for use with LÖVE games published on itch.io.

Installation

Just copy check.lua to where you want in your source.

Usage

Start it in its own thread, and send a table on the "send-itchy" channel with information on what you're looking for. Wait for a response on the "receive-itchy" channel.

-- initialize
versionCheck = love.thread.newThread("lib/itchy/check.lua")
versionCheckSend = thread.getChannel("send-itchy")
versionCheck:start()
versionCheckSend:push({
  target = "guard13007/asteroid-dodge", -- target/url must be defined, see Options
  version = current_version             -- defined elsewhere (also, optional)
  -- other options are available!! see list below
})
-- receive info
versionCheckReceive = thread.getChannel("receive-itchy")
if versionCheckReceive:getCount() > 0 then
  data = versionCheckReceive:demand() -- this is a table of info, format specified below
  -- easiest usage is to just print something like this to the user somewhere
  print("Version: " .. current_version .. " Latest version: " .. data.message)
end

Returned data example:

{
  status = 200,                -- nil or status code of an HTTP request
  body = '{"latest":"0.2.0"}', -- raw resulting body from the HTTP request
  version = "0.2.0",           -- a number or string
  latest = true,               -- nil or boolean your version == latest version?
  message = "0.2.0, you have the latest version"   -- an error or status message
}

Errors from LuaSocket will be returned as "socket.http.request error: " .. err

The library tries to parse a response body for valid JSON of the format {"latest":"VERSION"} (itch.io's format) and will do basic version comparisons based on this value. If it is unable to extract it or compare, version and latest will be nil.

If HTTP status 200 (OK) is encountered or a version is successfully parsed from a response, the script terminates (or moves on to checking on an interval.) Otherwise, it will keep trying with an exponential back-off starting at a 1 second delay.

Options

At minimum a url or target must be specified.

• url (string) If you have a different URL to check for the latest version from, you can specify it here.
• target (string) The target string of your game on itch.io (username/game-slug)
• channel (string) If you do not specify the channel name to look for on itch.io, it will use osx for Mac OS / OS X, win32 for Windows, linux for Linux, android for Android, ios for iOS, and if any other OS is returned by love.system.getOS() it will use that string as-is.
• version (string/number) Version of the game running right now.
• proxy (string) This library uses an HTTP proxy for the HTTPS call to itch.io's API. By default it uses https://104.236.139.220:16343 which is a DigitalOcean VPS I own. If you'd rather use a different proxy server, you can specify it here.
• interval (number) If specified, a check for the latest version will happen again every interval seconds.