userfile

User-system → engine file upload. Opens the user's own file picker (native OS dialog / Android / web browser) and brings the chosen file(s) into the engine. A thin public Luau surface over the __userfile Internal FFI namespace.

local userfile = require("@builtin::modules.api.engine.userfile")

-- Pick one or more files. Yields until the user finishes, so call it from a
-- coroutine / task (like any task.await).
local r = userfile.pick({ filters = { { name = "Images", extensions = { "png", "jpg" } } } })
if not r.cancelled then
    vfs.write("/source/textures/wall.png", r.files[1].bytes)
end

API

• userfile.pick(opts?) -> PickResult — open the system file picker and return the chosen file(s). Yields until the user finishes.
• userfile.pickFolder(opts?) -> PickResult — convenience for pick({ folder = true }); picks a whole directory tree. On the web (no native folder chooser) this degrades to a multi-file selection.

PickOpts

• multiple — allow selecting more than one file.
• folder — pick a whole directory tree.
• title — dialog window title (native only).
• filters — restrict selectable extensions, e.g. { { name = "Images", extensions = { "png", "jpg" } } }.
• writeTo — write each chosen file into the VFS under this directory. When set, each returned entry carries vfsPath (read it back with vfs.read) and the bytes are NOT delivered inline; when omitted, each entry carries bytes (the file content as a binary-safe string).

PickResult

{ cancelled: boolean, files: { PickedFile } }. cancelled is true (and files empty) when the user dismissed the picker. Each PickedFile is { name, mime, size, bytes?, vfsPath? } — exactly one of bytes / vfsPath is present, decided by whether writeTo was set.

The picker opens synchronously (so the web browser's file input stays inside the user-activation gesture) and its result travels as JSON; files delivered inline arrive base64-encoded and are decoded back to a binary-safe bytes string before returning. A cancel returns { cancelled = true, files = {} }; a genuine failure (e.g. a lost browser user-activation gesture) raises an error.