Before diving into the API, let's discuss how to get started with Plugin development.
Log into a BETA world in the Old School Runescape client. Developer lua commands are only enabled on BETA worlds.
Create a folder in your Plugins directory. On Windows, this is located at C:\Users\<user>\AppData\Local\Jagex\Old School Runescape\Plugins. If you have no plugins installed you may have to create Plugins first. Pick an easy-to-remember name for your plugin. It is not a player-visible string, but you will be typing it to invoke the plugin from the developer tools.
TIP: If you are maintaining your plugin work in a repository, it may be useful to symlink a directory from your repository into the client's Plugins folder. The command to do this in Windows is mklink /D Link Target.
index.lua file:-- index.lua
osrs.print("Hello world of OSRS Plugin Development!")
manifest.json file like this:{
"name":"My Plugin Title",
"description":"My Plugin Description",
"author":"Your Name",
"version":"0.0.1",
"api_version":"0.0.1"
}
In the game client press ALT+~ to open the Debug Console.
Type luaplugin <plugin_directory>. This will run the plugin!
commands for running, installing, and uninstalling plugins.
plugin_name [--restart] : Runs a plugin that has already been installed. Optionally pass --restart to bounce the lua vm prior to running. This enables rapidly running a plugin multiple times without side effects.
--install <plugin_name>: Install a plugin from the remote repository.
--installfromurl
--uninstall <plugin_name>: Uninstalls a plugin and deletes all of its persisted data.
--list : lists all plugins in the remote repository.
--search
Command for manipulating a search path used by the runlua command. Directories in the path will be searched in order for the named script.
add
remove
list: prints all entries in the luapath
clear: deletes all entries in the path.
Directly runs a lua file. This can be a convenient alternative to luaplugin if you need more control of lua execution. This command will not automatically reset the VM, and can run lua scripts at any location in the filesystem. The file argument should be a full path, or be findable in the luapath. The .lua extension can be omitted.
Restarts the luavm.
Extracts a zipped plugin to the user's plugin directory. Passing '--delete' will delete the zipfile on completion. If the plugin already exists, it will be updated in place; however, it is recommended to do a luaplugin --uninstall instead to ensure no dangling files from the prior version remain behind.
Parses the submitted string into a lua chunk and runs it directly in the VM.
Example:
$ lua x = 5
$ lua f = function(n) return 3*n+5 end
$ lua osrs.print( f(x) )
Development: 20
Lets you inspect global variables in the VM.
Example:
$ lua x = { a="hello", b=1001, c={ desc="Inner table!", id=2002}}
$ luavar x
Development: x.b = 1001
Development: x.a = hello
Development: x.c= table: 000001D9FE08440
$ luavar x.c
Development: x.c.desc = Inner table!
Development: x.c.id = 2002
Controls the lua debugger. If no port is given, will listen on port 21110. See "Source line debugging" section.
enables or disables the plugin. This lets you turn off a plugin without uninstalling it.
All exposed lua functionality is available in the osrs global object. Large functional groups are further organized into modules, such as osrs.Events. These modules are stateful and must always be invoked with a : (colon), to use lua's member function syntax (for example: osrs.Events:subscribe(...)).
When a plugin is started, its entrypoint file (index.lua by default), will run from beginning to end. If it doesn't register any callbacks, then it's done. To keep running logic over time, it must register at least one callback with th engine. A simple example of this would be osrs.setInterval( function() osrs.print("Heartbeat") return true end, 1.0). That installs a callback that will run every second, indefinitely. Other examples would be subscribing to an event with osrs.Events, or creating a UI element with osrs.Ui.
The game client supports source line lua debugging, via VSCode. You can step through your lua plugin code, set breakpoints, and manipulate lua memory state. The below steps walk through the setup process.
First, install Visual Studio Code. This is a freely available editor and programming environment.
Once installed, open the Extension tab ("blocks" icon on the left-hand toolbar).Search for "lrdb-beamng" in the Extensions Marketplace search bar, and install it. It's important to use this version of the lrdb extension, and not "LRDB", which doesn't support attaching to the OSRS client.
Once installed, open a lua file that you'd like to debug in vscode, and set a breakpoint in it (hit F9 on a line of interest).
Go to the Debug tab in the left-hand toolbar (bug icon overlapping an arrow). At the bottom, you should see a new section, "LUA REMOTE DEBUGGER -VMS". It will currently be empty. The extension is scanning ports 21110-21120 for running lua VMs, and we haven't started one yet.
Now run the OSRS game client.
Once logged in, start the debugger, via luadebug start in the debug console. If you do a luadebug status you should see that the debugger is listening on part 21110.
Back in VSCode, if you hit the "Refresh" icon in the "LUA REMOTE DEBUGGER -VMS" section, you should now see a VM instance available on port 21110. Click it to attach the debugger. The "Debug Console" tab in VSCode should report "Debugger connected!".
If in the OSRS debug console, you invoke your script (i.e., runlua <yourscript>), your breakpoint should be hit. You can now step through your program, and inspect variables.
TIPS:
Bound C++ objects will appear as type: memory_address in the inspector. You can still investigate these objects' state, using the Debug Console! For example, a Vector2 will show up as somevec: sol.jag::math::Vector2T<float>: 000001EE1E4E6858. In the Debug Console, you can see its members by typing somevec.x and somevec.y.
A common pattern is to maintain some state in a local variable, and then access that state in a method callback (such as an event handler, or the callback to osrs.setInterval). These variables will be available for view in the "Upvalues" section of the Variables Inspector.
It is possible to test your locally built plugins on your mobile device, without needing to submit them for approval. You will need to zip your plugin and then host your plugin on a local webserver. Once the plugin is hosted, you can use the developer luaplugin --installfromurl <url> command to install the plugin from your local webserver.
Make sure your phone and computer are on the same local network. This will probably be the case if your phone is connected to your wifi.
Make sure your computer is discoverable on the local network. On Windows you may need to go to Settings, "Network & Internet", then select the network adaptor you're using and make sure you're using the "Private network" profile type.
Install a local webserver. An easy, cross-platform way to do this is to install the latest Node.js, and the http-server package.
a. Install node.js. LTS node.js.
b. Install http-server. From the command-line, type npm install -g http-server. You may need to run this command with administrator privileges (sudo on linux/mac, or open an Administrator Console on Windows).
c. Now you can serve any directory on your system via cd'ing to it in console and running http-server -p 8080.
You might want to test your connection to your phone. You could serve a directory with a trivial index.html with it. When you do this, http-server will tell you what ip addresses it is listening on. You want the IP address associated with your LAN/WAN (not 127.0.0.1). When you have it, open a browser on your phone and browse to http://192.168.8.20:8080 (or whatever IP address you're listening on), and verify you can see the contents of your index file.
Now you are ready to prepare and serve your plugin. Go to your plugin folder, and zip it, e.g. if your folder was "MyPlugin", you could right-click on it and make MyPlugin.zip.
In the directory containing MyPlugin.zip, start your webserver (e.g. http-server -p 8080 if using the node http-server package).
You can now install the plugin from the debug console via luaplugin --installfromurl http://192.168.8.20:8080/MyPlugin.zip (updating your IP address and zip name as necessary).