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:

OptionDefaultWhat it does
acceptanywhich files the picker shows, like ".png,.jpg" or "image/*"
multiplefalsetrue lets the player pick several files at once
maxSize16 MBthe 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:

FieldWhat it is
namethe file name, like "cat.png"
sizethe size in bytes
typethe kind of file, like "image/png"
datathe 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.button or 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 with ctx:image.
  • Text: file.data is already a string, so a .txt or .json file is ready to use. Read JSON with json.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.