How to Add Lua Packages to an Onset Server

To add a package to an Onset server, upload the package folder into the server's packages/ directory, make sure it contains a valid package.json, add the folder name to the packages list in server_config.json, and restart. The server only loads packages named in that list, so a folder that is uploaded but not listed does nothing. Watch the console on start: every package prints as it loads, and Lua errors name the file and line.

How Onset packages work

In Onset, the server is the game. The map, vehicles and weapons exist, but jobs, spawns, chat commands, money and every rule come from packages: folders of Lua scripts the server runs. Some scripts run on the server, some are sent to players and run on their machine, and extra files such as HTML interfaces or sounds are downloaded on join.

Onset itself has had no developer updates in several years, so the packages you find are mostly community made and some are old. Many still work fine, because the scripting API has not changed either.

Package folder layout

A typical package looks like this:

packages/
  freeroam/
    package.json
    server/
      main.lua
    client/
      main.lua
    ui/
      menu.html

The folder name (freeroam here) is the package name you put in server_config.json.

package.json

package.json tells the server what to run and what to send to players:

{
  "author": "YourName",
  "version": "1.0",
  "server_scripts": [
    "server/main.lua"
  ],
  "client_scripts": [
    "client/main.lua"
  ],
  "files": [
    "ui/menu.html"
  ]
}

• server_scripts run on the server only. Players never see this code.
• client_scripts are downloaded and run by every player.
• files are other assets players download, such as web UI files and images.

Every path is relative to the package folder and must match the real file name exactly, including upper and lower case on a Linux server.

Enabling the package

Open server_config.json and add the folder name to packages:

"packages": [
  "default",
  "freeroam"
]

Packages load in the order listed. If one package uses functions exported by another, list the one it depends on first. Mind the commas: the last item has no comma after it, and every other item does.

A small package to test with

To confirm your setup works before installing a large framework, make a package called hello with one server script:

AddEvent("OnPackageStart", function()
    print("hello package loaded")
end)

AddEvent("OnPlayerJoin", function(player)
    AddPlayerChat(player, "Welcome to the server, " .. GetPlayerName(player))
end)

AddCommand("heal", function(player)
    SetPlayerHealth(player, 100.0)
    AddPlayerChat(player, "Healed.")
end)

Point server_scripts at that file, add hello to the list, restart, and look for hello package loaded in the console. Join and type /heal in chat. If both work, your folder structure and config are right, and any later problem is inside the package you install.

Plugins versus packages

Packages are Lua. Plugins are native libraries that add features packages can use, the common one being the MariaDB plugin for saving data to a database. Plugins go in the plugins/ folder and in the plugins list of server_config.json. A roleplay framework that expects a database will fail on start if the plugin is missing or the database details are wrong, and the console usually says so.

Common load errors

When a package fails, Onset keeps loading the others, so a broken roleplay server can look half working: cars spawn but jobs do not. Always read the start of the console after a change.

Updating and removing packages

To update, stop the server, back up the package folder (and the database if it has one), replace the files and start again. To remove a package, delete its name from the packages list first. Leaving a listed package without its folder produces errors on every start. A habit of backing up before changes is worth a lot here, as how to back up a game server explains.

Doing this on a hosted server

On a GamezServers Onset server the packages and plugins folders and server_config.json are in the browser file manager, or reachable over SFTP for big uploads. The live console shows each package loading and any Lua error the moment you restart, and a one click backup before you install a new framework lets you roll back in seconds. New to the panel? Getting started walks through the first login. If you have not set up the server itself yet, see how to host an Onset server.

FAQ

Where do Onset packages go?

In the packages/ folder of the server, one folder per package, and each folder name must be listed in packages in server_config.json.

Why is my Onset package not loading?

Usually it is missing from the packages list, the folder name does not match, or package.json has a syntax error. Check the console as the server starts.

Do players need to download packages?

Players download client scripts and files automatically when they join. They do not install anything by hand.

Can I run several packages at once?

Yes. List them all in packages. Load order matters when one package depends on another.