Your First Lua Plugin

Briefing

A ‘plugin’ in Autorun-ng refers to an isolated package of either Lua code or a shared library. These can extend behavior of Autorun-ng using the API it provides.

Note

The lua dumper is a simple lua plugin!
You can find the source here.

Creating the plugin

1. Create a folder named my_first_plugin in autorun/plugins:

   Linux

   mkdir -p autorun/plugins/my_first_plugin

   Windows

   mkdir autorun\plugins\my_first_plugin

2. Add a plugin.toml file inside of the folder:

   [plugin]
   name = "my_first_plugin"
   author = "you"
   version = "0.1.0"
   description = "This does the thing and it does it well"
   language = "lua"

3. Add your src directory, alongside client and menu directories inside, with their respective init.lua files. You can leave them empty for now.

   Your folder structure should look like this:

   • Directorymy_first_plugin

     • Directorysrc

       • Directoryclient

         • init.lua
       • Directorymenu

         • init.lua
     • plugin.toml

   Your plugin now exists and will run the code inside. It’s time to write it.

Writing your first code

🟠 client

This folder is for code that will run when you are in a server. It will run alongside addon code. This is where you should be worried about anti-cheat detection and creepy addons messing with stuff.

The init.lua file inside will run a single time whenever you join a server.

Example Code

Let’s make a simple plugin that prints a message to your Autorun console when you join a server.

client/init.lua

local hostName = _G.GetHostName()
Autorun.print("Hey, I just joined " .. hostName .. "!")

What does this do?

1. local hostName = _G.GetHostName() - This gets the server’s hostname using the GetHostName global C function provided by Garry’s Mod.
2. Autorun.print("Hey, I just joined " .. hostName .. "!") - This prints your message to the Autorun console, NOT the in-game console. You’d use print for that.

Why do I have to use _G?

Autorun-ng plugins run in a safe environment to ensure you don’t leak values to the global environment where evil addons roam wild.

Your only link to the global environment is through the explicit _G table.

🟢 menu

This folder is for code that will run in the Garry’s Mod menu a single time upon startup.

You don’t have to worry about detection here. No addon runs in the menu. This folder is just nice for if you want to customize your menu experience.

Example Code

Let’s make a simple plugin that prints today’s date and greets the user when you start Garry’s Mod.

menu/init.lua

local date = os.date("%Y-%m-%d")
Autorun.print("Today is " .. date .. ", hello user.")

What does this do?

1. local date = os.date("%Y-%m-%d") - This gets today’s date in the format “YYYY-MM-DD” using Lua’s built-in os.date function.
2. Autorun.print("Today is " .. date .. ", hello user.") - This prints your message to the Autorun console, NOT the in-game console. You’d use print for that.

Hey, why didn't you use _G this time?

For convenience, Autorun-ng provides access to Lua’s specific builtins.

This is so you don’t even up accessing them from _G which is dangerous as they could have replaced/detoured the functions, and needlessly makes your script detectable.

You can find the full list of stored builtins here

Finished

For menu plugins, you’ll have to restart Garry’s Mod for them to activate as they only run once upon startup of Autorun-ng.

This was a guide for a very basic plugin, it didn’t even go into events like Autorun.on!

For that, you’ll have to read the next guide.