wolfhacklua API 1.1 Forum

Permissions

Some things a script does reach outside its own folders or the overlay's own drawing. Those need a permission: the script lists it in its manifest, and the user switches it on for that script on the Scripts page. Without both, calling the function raises an error that says which permission is missing.

Always available#

No permission is needed for: ui, draw, assets, store, file (the script's own data folder), json, anim, color, timer, task, events, log, app, time, and also data, media and theme.

Permissions that must be granted#

PermissionUnlocksNotes
inputinput.key_down, input.mouseKey and button state anywhere, only while the game or the menu has the focus. No history.
netnet.request, net.get, net.postHTTPS to the hosts in the manifest's net_hosts only. No redirects or cookies; GET and POST; limited headers; 256 KB out, 4 MB in; 30 requests a minute; 4 at a time.
memorymem reads, scans, lookupsAny address of the game process. 4 KB per read, 8192 reads per frame. Nothing is changed.
memory_writemem.write_*, mem.undo*Data pages only. Also needs the master switch. Every write is undone when the script stops.
memory_patchWrites to code pagesNeeds memory_write in the manifest too. The most dangerous permission.

Asking and granting#

In a single-file script:

lua
--@permissions input,net
--@net_hosts api.example.com

In a folder script, in manifest.json:

json
{ "permissions": ["input", "net"], "net_hosts": ["api.example.com"] }

After installing, open the script's card on the Scripts page. Under Permissions each permission the script asked for has a toggle and a description. A permission the manifest does not list cannot be granted: add it and press Reload.

Errors tell you which case you are in:

  • "... needs the 'net' permission, which is not granted": switch it on in the script's Permissions.
  • "... which is not requested by this script": add it to the manifest.

Grants belong to the code the user saw#

When a script's files change, its net, input and memory grants are switched off until granted again. Updating a script therefore needs a fresh decision from the user.

net: a note for users#

A script with net can send anything it can read to the hosts it lists, including the game data it sees. Read the host list before granting.

Memory: read this before using it#

memory lets a script read anything in the game process. memory_write lets it change the game. These are capabilities of the overlay, not features of Lua: the host checks every access, but a trusted script can still do harm.

  • The master switch. Scripts > Let scripts write game memory is off at every start unless you turned it on. With it off no script writes anything, whatever it was granted. Turning it off undoes every script's writes.
  • Data pages only. Writes to code pages need memory_patch.
  • Limits. 1 to 256 bytes per write; 512 writes per frame; 4096 writes in force; one write stays inside one memory region; user-mode addresses only.
  • Undo. The host remembers the bytes each write replaced and puts them back when the script stops, or when the permission or switch is taken away. If the game changed the bytes meanwhile, they are left as the game has them. If the game restarted, old writes are forgotten.

What the sandbox does and does not do#

The interpreter removes io, os.execute, package, debug, FFI and DLL loading, caps memory, and gives every callback a time budget. That limits damage from bugs. It is not an operating-system sandbox: the interpreter and the host's functions run in the overlay's process, so a memory-safety bug in them could be abused by a hostile script. Install only scripts you have read or trust.

API 1.1 · source docs-src/pages/guide/permissions.md