Build a mod
Files from your computer
Let players pick files from their own computer with the browser's file picker, read them in your mod, and save files back to their downloads.
Your mod can ask the player for a file, the same way an "Upload" button on a website does. The browser's own file picker opens, the player chooses a file, and your mod gets its bytes. Use it for pictures on the HUD, settings to import, notes, maps, anything.
Pick a file
local picture
local function choosePicture()
local ok, err = files.open({ accept = "image/png" }, function(list, err)
if not list then
ui.notify("Picture", err)
elseif list[1] then
picture = textures.fromData(list[1].data)
end
end)
if not ok then
ui.notify("Picture", err)
end
end
settings.button("choose", { label = "Choose a picture...", onClick = choosePicture })
hud.add("picture", function(ctx)
if picture then
ctx:image(picture, 4, 4, 64, 64)
end
end)
Open the mod's Settings, click Choose a picture..., pick a PNG, and it shows up in the corner of the screen.
files.open(options, callback) opens the picker. The options are all optional:
| Option | Default | What it does |
|---|---|---|
accept | any | which files the picker shows, like ".png,.jpg" or "image/*" |
multiple | false | true lets the player pick several files at once |
maxSize | 16 MB | the largest file you accept, in bytes. It can be at most 64 MB |
When the player has chosen, your callback gets a list of files. Each file is a table:
| Field | What it is |
|---|---|
name | the file name, like "cat.png" |
size | the size in bytes |
type | the kind of file, like "image/png" |
data | the whole file, as a Lua string of bytes |
If the player closes the picker without choosing, the list is empty. If a file is too big or cannot be read, the callback gets nil and a message instead.
Only after a click
Browsers only open a file picker right after the player clicks or presses a key, so a website cannot open one out of nowhere. Call files.open from:
- a button, like
settings.buttonor a button on your own screen - a keybind's
onPress - a chat command
Anywhere else, for example in a timer or the tick event, files.open gives back false and a message, and nothing opens.
On phones and tablets a small window pops up with a button to tap, because touch screens need that extra tap.
Use what you got
- Pictures:
textures.fromData(file.data)turns the bytes of a PNG into a texture you can draw withctx:image. - Text:
file.datais already a string, so a.txtor.jsonfile is ready to use. Read JSON withjson.decode(file.data). - Anything else:
string.byte(file.data, i)reads one byte at a time.
The file is not kept. To remember what the player chose after the game restarts, save what you need in storage.
Save a file
files.save(name, data, type) downloads a file to the player's computer, like a "Download" button on a website:
commands.register("export", function()
files.save("waypoints.json", json.encode(storage.points, true), "application/json")
end, "Download your waypoints")
type is optional. Saving does not need a click, but browsers may ask the player first when a site downloads several files at once.
WebAssembly mods
WebAssembly mods use the same functions through the SDK, for example zeus::call("files.open", ...) in Rust. data arrives as bytes.



