Introduction

Write your own Guild Wars 2 plugins in Lua.

Lua plugins are small programs you write yourself, in Lua 5.5, that run inside the game next to the OKTW plugins. A Lua plugin can read the game (your character, the agents around you, your inventory, the map, events and much more), act on it (cast skills, move, use items, trade) and draw its own windows and overlays.

Every plugin runs in its own sandbox, with its own memory and its own time budget each frame. A plugin that errors or runs too long is stopped and reported in the console; it can't freeze or crash the game.

#Where plugins live

Plugins live in the scripts folder next to the injector. Every folder in it is one plugin, and the folder's name is the plugin's name. A plugin starts from its main.lua (or init.lua) and can load any other file in its folder with require.

scripts/
  my-plugin/
    main.lua           runs when the plugin starts
    app.lua            require("app")
    lib/util.lua       require("lib.util")
    settings.txt       written by the plugin with files.write

Copy a plugin's folder into scripts and it shows up in the Lua Plugins window within a few seconds.

#Get the template

Every new plugin starts from the template: a blank plugin with the callbacks wired up and its settings saved for you.

• Unzip it into scripts and rename my-plugin to your plugin's name.
• Start it from the Lua Plugins window, then start writing in app.lua. Your first plugin goes through it file by file.

#Running a plugin

The Lua Plugins window lists every plugin: green while it runs, red after an error. Each row has a start/stop button and a reload button. Reload stops the plugin, reads all of its files again and starts it, so you can edit a file and see the change in a second.

Click a row to open the plugin's own window, with its status, memory use, task count, everything it printed and the Start with the game option. See In-game tools.

#Next steps

• Your first plugin walks through the template every new plugin starts from.
• Callbacks lists what the game calls in your plugin, and when.
• Tasks and wait shows how to do things over time without freezing the game.
• The API sections document every module, function and value.