Build a mod

Web requests

Talk to your own server from a mod with GET, POST, PUT and DELETE requests, JSON bodies, headers, status codes and timeouts.

광고

Your mod can talk to websites and to your own server: download news for a HUD, save scores, sync settings, or pass messages between players for voice chat. All of it needs the network permission (see Packaging).

Download something

http.get("https://example.com/news.json", function(body, err, res)
  if not body then
    print("Could not load the news: " .. err)
    return
  end
  local news = json.decode(body)
  print(news.title)
end)

The request runs in the background. When it is done, your function runs with three values:

ValueWhat it is
bodythe response, when the status is 2xx (like 200). Otherwise nil
errwhy it failed, or nil. For example "HTTP 404", a timeout or "request failed (...)"
resthe whole response whenever the server answered, even with an error status. nil if it never answered

res has these fields:

FieldWhat it is
res.statusthe status code, like 200 or 404
res.oktrue for a 2xx status
res.bodythe response, also for error statuses, so you can read the server's error
res.headersthe response headers, with lowercase names, like res.headers["content-type"]

Send something

http.post(url, body, callback) sends data. Give it a table and it is sent as JSON. Give it a string and it is sent as it is.

http.post("https://example.com/scores", { player = player.name(), score = 12 }, function(body, err, res)
  if res then
    print("The server answered " .. res.status)
  else
    print("Could not reach the server: " .. err)
  end
end)

A table body is sent with Content-Type: application/json, a string body with text/plain;charset=UTF-8. To send something else, set type:

http.post("https://example.com/upload", pngBytes, { type = "image/png" }, function(body, err) end)

Other methods, headers and timeouts

http.request does everything the others do and takes all its settings in one table:

http.request({
  method = "PUT",
  url = "https://example.com/notes/1",
  headers = { Authorization = "Bearer " .. settings.get("token") },
  body = "hello",
  timeout = 10,
}, function(body, err, res) end)

http.get and http.post take the same options as an extra table right before the function: http.get(url, options, callback) and http.post(url, body, options, callback).

OptionDefaultWhat it does
methodGETGET, HEAD, POST, PUT, PATCH or DELETE (http.request only)
urlwhere to send it (http.request only)
bodya string, or a table to send as JSON (http.request only). GET and HEAD cannot have one
headersa table of header names and values, at most 32
typefrom the bodythe content type of the body
timeout30seconds to wait before giving up, at most 120
maxSize16 MBthe biggest response you accept, in bytes. At most 64 MB

A typo in an option name stops with an error that names it, like http.post: unknown field timout.

What the server has to allow

Browsers protect players, and those rules apply to mods too:

  • CORS. The server must send Access-Control-Allow-Origin (for example *), or the browser hides the response and you get request failed (network error or blocked by CORS).
  • Preflight. JSON bodies, your own headers and methods other than GET, HEAD and POST make the browser ask first with an OPTIONS request. The server has to answer it with the methods and headers it allows (Access-Control-Allow-Methods, Access-Control-Allow-Headers).
  • Headers you can read. Besides a few basic ones like content-type, you only see the response headers the server lists in Access-Control-Expose-Headers.
  • https. On an https page, plain http:// addresses are blocked.

Safety and limits

  • Requests never include the player's cookies or the address of the page they play on. A mod cannot log in as the player somewhere or act for them on another website.
  • A mod can have 16 requests running at once. More fail right away through their callback with too many requests at once.
  • Your function always runs on a later frame, never in the middle of your own code.
  • When your mod reloads or is turned off, its unfinished requests are cancelled and their functions never run.

WebAssembly mods

WebAssembly mods use the same functions through the SDK, for example zeus::call("http.post", (url, body, zeus::func(...))) in Rust. Bodies arrive as bytes.