How to create an Onset package

In this tutorial, we will see how to write your first package for Onset. A package (view more on packages) is a collection of scripts (written in LUA) and assets files (HTML, JS, CSS). He has its own LuaVM state. A mechanism is available to allow packages to communicate between them.

Scripts allow you to personalize the game and can be executed on the server-side and/or the client-side. Assets files are used to build your game interfaces quickly. 

How to create a package?

Let's go to create a simple package. First thing to know, a package this own directory in onset/packages.

He must have a package.json file that contains its description and the list of files that need to be loaded. This file will be read by Onset when the server starts (if we have enabled our package).

1. Create a new folder; he will contain our new package. For example, onset/packages/helloworld.
   Note: the name of the folder is the package name.
   
2. Create a package.json file in onset/packages/helloworld.
   
3. The content of this file needs to be a valid JSON:
   
   {
       "author": "YourName",
       "version": "1.0",
       "server_scripts": [],
       "client_scripts": [],
       "files": []
   }

   
   
4. Currently, the package is not loaded on the server.
   To enable the package, edit onset/server_config.json (see server config) and add the package name (folder name in onset/packages) in packages section:
   
   	"packages": [
   		...,
   		"helloworld"
   	],

   
   
5. Reboot your Onset server. In server console, you will see:
   
   [ERROR] Package "helloworld" does not have any scripts
   [ERROR] Package "helloworld" failed loading

   
   The server try to load our package. Currently, our package is empty!

Writing your first Onset script

In a package, you can structure your files like you won't, but we strongly recommend (for maintainability) to have:

• A client folder for client-side scripts.
• A server folder for server-side scripts.
• A assets folder for the html, js, css and other files used to build your game interfaces.

When the server successfully loads the package, we will display a message in the server console. It will contain the name of the server.

Onset exposes an API which allow you to access native functions of the game as well as an event system making hook easy.

For our example, on our Onset server, we will hook OnPackageStart event, and use internal GetServerName() function to get the server name. This script will be executed on server-side:

1. Create a onset/packages/helloworld/server folder.
   
2. In this folder, add server.lua file with the following content:
   
   function OnPackageStart()
       print("Hello World by mTxServ.com!")
       print(("Name of the Onset server: `%s`\n"):format(GetServerName()))
   end
   
   AddEvent("OnPackageStart", OnPackageStart)

   
   Our first script is ready.
   
3. Now we need to add it in the package.json, on the server_scripts section:
   
   {
       "author": "mTxServ",
       "version": "1.0",
       "server_scripts": [
           "server/server.lua"
       ],
       "client_scripts": [],
       "files": []
   }

   
   Save it.
   
4. To try it, reboot your server. In server console, you will see:
   
   [INFO] Starting package "helloworld"
   [SCRIPT] Hello World by mTxServ.com!
   [SCRIPT] Name of the Onset server: `mTxServ.com`

   
   
5. Let's create a script that will announce the connections/disconnections of the players and add it in server.lua:
   
   function OnPlayerJoin(player)
       AddPlayerChatAll(GetPlayerName(player).." connected")
   end
   AddEvent("OnPlayerJoin", OnPlayerJoin)
   
   function OnPlayerQuit(player)
       AddPlayerChatAll(GetPlayerName(player).." disconnected")
   end
   AddEvent("OnPlayerQuit", OnPlayerQuit)

   
   
6. Restart your server and try it ;)
   
7. We have finished our first package!
   Learn more about events and functions on official wiki.
   You can see our whitelist package or our translation (i18n) package if you want to learn more.

Limitations of a package

• Package only support files with the following extensions:
  lua, js, css, html, htm, png, jpg, jpeg, gif, wav, mp3, ogg, oga, flac, woff2, ttf, pak
  
• You can only load 32 packages on your server.
  
• You can only have 255 files per package.

Official Documentation

Many features are available (events, functions, etc.), allowing you to modify the game easily. Consult the official documentation!