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:
| Value | What it is |
|---|---|
body | the response, when the status is 2xx (like 200). Otherwise nil |
err | why it failed, or nil. For example "HTTP 404", a timeout or "request failed (...)" |
res | the whole response whenever the server answered, even with an error status. nil if it never answered |
res has these fields:
| Field | What it is |
|---|---|
res.status | the status code, like 200 or 404 |
res.ok | true for a 2xx status |
res.body | the response, also for error statuses, so you can read the server's error |
res.headers | the 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).
| Option | Default | What it does |
|---|---|---|
method | GET | GET, HEAD, POST, PUT, PATCH or DELETE (http.request only) |
url | where to send it (http.request only) | |
body | a string, or a table to send as JSON (http.request only). GET and HEAD cannot have one | |
headers | a table of header names and values, at most 32 | |
type | from the body | the content type of the body |
timeout | 30 | seconds to wait before giving up, at most 120 |
maxSize | 16 MB | the 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 getrequest 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
OPTIONSrequest. 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 inAccess-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.



