wolfhacklua API 1.1 Forum

Your first script

This page takes you from an empty text file to a script that is running, edited and reloaded. It needs no permissions and no game.

1. Create the file#

Make a text file called hello.lua anywhere (the desktop is fine). Use a plain-text editor and save it as UTF-8. Paste this:

Hello v1.0.0 no permissions
Download hello.lua
hello.lualua
--@name Hello
--@version 1.0.0
--@author you
--@description My first script: writes a line to the console and draws a greeting.

log.info("hello loaded, API " .. api.version)

events.on("draw", function()
  draw.text(40, 40, 0xFFFFFFFF, "Hello from Lua!  " .. os.date("%H:%M:%S", time.wall()), { size = 22, shadow = true })
end)

The first lines starting with --@ are header lines. When you install a single .lua file the overlay turns them into the script's manifest: its name, version, author and description. The file name (hello) becomes the script's id: it is lowercased, any character other than letters, digits, - and _ becomes -, and it is cut to 48 characters (a name shorter than 2 characters gets -script added).

The two lines of code do this:

  • log.info(...) writes a line to the script's console.
  • events.on("draw", fn) asks the overlay to call fn once for every frame it draws. Inside it, draw.text(x, y, colour, text, options) draws text at a pixel position. Colours are written 0xRRGGBBAA; 0xFFFFFFFF is opaque white.

2. Install it#

  1. Open the overlay menu and choose Scripts (the last page of the menu).
  2. In the Install box on the left paste the full path of your file, for example C:\Users\you\Desktop\hello.lua, and press Install.
  3. The script appears in the Installed scripts list with the status Off. A script is always off after installing.

You can also copy the file (or a script folder) into Documents\Base\scripts\ yourself; the Open scripts folder button opens it. A file you drop there shows up on the Scripts page, switched off.

3. Check its permissions and switch it on#

Select the script in the list. The card on the right shows its name, version, status and a Permissions section if it asks for any. Our script asks for none, so there is nothing to grant. Switch Enabled on.

The status changes to Running. With the menu closed, the greeting is drawn at the top left of the screen, on top of the game.

4. Edit and reload#

Change the text in your file, save it, and press Reload on the script's card. Reload runs the files again from scratch: the old script is unloaded (its handlers, timers and resources are released) and the new code starts. Nothing is carried over except the script's saved settings.

5. Read the console#

Open the Console tab on the Scripts page. It shows everything every script logged, with warnings and errors coloured. You should see the hello loaded line. A script's own card shows its latest status text, which is where an error message is repeated.

6. If something is wrong#

What you seeWhat to check
The script is Off after installThat is normal. Switch Enabled on.
Error with a message mentioning main.lua and a line numberA mistake in your code. The message names the line; fix it and press Reload.
IncompatibleThe manifest is wrong or asks for a newer API than this build offers. The status text says which. See troubleshooting.
StoppedThe host stopped the script for running too long or raising too many errors. See performance.
Running, but nothing on screenDrawing only happens inside events.on("draw", ...). Check the colour's alpha (FF at the end is opaque) and the position.
A message saying a permission is not grantedSwitch it on under the script's Permissions; if it says not requested, add it to the manifest.

More in troubleshooting.

Next steps#

API 1.1 · source docs-src/pages/start/first-script.md