packages: Difference between revisions

From Onset Developer Wiki
No edit summary
No edit summary
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
A package is collection of Lua scripts and other files. You can have up to 32 packages and 255 files per package on your server.
A package is collection of Lua scripts and other files. You can have up to 64 packages and 1024 files per package on your server.


Allowed file type extensions: '''lua, js, css, html, htm, png, jpg, jpeg, gif, wav, mp3, ogg, oga, flac, woff2, ttf, pak'''
Allowed file type extensions: '''lua, js, css, html, htm, png, jpg, jpeg, gif, svg, wav, mp3, ogg, oga, flac, m4a, woff2, ttf, pak, json, map'''


Example packages: https://github.com/BlueMountainsIO/OnsetLuaScripts
Example packages: https://github.com/BlueMountainsIO/OnsetLuaScripts
Line 7: Line 7:
==Lua context==
==Lua context==
Each package has their own LuaVM state. Lua script files that are loaded in the same package can access the same global variables.
Each package has their own LuaVM state. Lua script files that are loaded in the same package can access the same global variables.
Variables defined as ''local'' are only visible in that single .lua file.


You can export functions from one package and import them in another package. See [[AddFunctionExport]] and [[ImportPackage]].
You can export functions from one package and import them in another package. See [[AddFunctionExport]] and [[ImportPackage]].
Line 12: Line 13:


==Folder layout==
==Folder layout==
Each package has a folder that is placed inside the '''packages''' folder on your server.
Each package has a folder that is placed inside the '''packages''' or inside the '''autostart''' folder on your server. Example layout:
<pre>
<pre>
OnsetServer.exe
OnsetServer.exe
server_config.json
server_config.json
    /autostart
        /myautostartpackage
            index.lua
            script.lua
     /packages
     /packages
         /mypackagename
         /mypackagename
            index.lua
             package.json
             package.json
         /mapeditor
         /mapeditor
            index.lua
            package.json
             /client
             /client
                 editor.lua
                 editor.lua
             /server
             /server
                 server.lua
                 server.lua
            package.json
</pre>
</pre>
==autostart==
Packages can be automatically started on server start. For that to work you must place your package into the '''autostart''' folder. If the folder does not exist, create it at the root where your OnserServer executable is located.
Notice: [[StartPackage]] will first look into the '''autostart''' folder before looking in the '''packages''' folder.
==index.lua==
The ''index.lua'' is executed before the server loads the ''package.json'' file. In this Lua file you can register scripts and files to this package.
The following functions are only available to the ''index.lua'' script. Besides that, only Lua library functions are exposed the ''index.lua'' but no other Onset server functions.
* [[AddServerScript]]
* [[AddClientScript]]
* [[AddSharedScript]]
* [[AddFile]]
<syntaxhighlight lang="Lua">
--index.lua
AddServerScript("server/*_s.lua")
AddClientScript("client/*_c.lua")
AddSharedScript("shared/*.lua")
AddFile("audio/sound.mp3")
AddFile("ui/*.html")
</syntaxhighlight>
For the package to work, there has to be either an ''index.lua'' or a ''package.json'' config file. Both at the same time are also supported.


==package.json==
==package.json==
Your package.json defines server and client script files. It also defines what files are required for this package to work.
Your ''package.json'' defines server and client script files. It also defines what files are required for this package to work.
Files defined in '''client_scripts''' and '''files''' are being downloaded by clients once they join the game server.
Files defined in '''client_scripts''', '''shared_scripts''' and '''files''' are being downloaded by clients once they join the game server.
 
Lua scripts defined in '''shared_scripts''' are executed on both server and client. The function [[IsServer]] and [[IsClient]] can be used to determine if a script currently runs on the server or client.
 
For the package to work there has to be either an index.lua or a package.json config file. Both at the same time are also supported.
 
Wildcards (*) are supported.
 
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
{
{
Line 35: Line 74:
"version": "1.0",
"version": "1.0",
"server_scripts": [
"server_scripts": [
"server/editor.lua"
"server/*.lua"
],
],
"client_scripts": [
"client_scripts": [
"client/editor.lua"
"client/editor.lua"
],
"shared_scripts": [
"shared_script.lua"
],
],
"files": [
"files": [
Line 46: Line 88:
"client/gui/jquery.js",
"client/gui/jquery.js",
"client/gui/OpenSansRegular.woff2",
"client/gui/OpenSansRegular.woff2",
"client/gui/OpenSansBold.woff2"
"client/gui/OpenSansBold.woff2",
"client/gui/images/*"
]
]
}
}
Line 52: Line 95:
Each package has a package.json in it's root path. See the folder layout above.
Each package has a package.json in it's root path. See the folder layout above.
Additionally you have to tell the server what packages exist. See [[server_config]] to configure that.
Additionally you have to tell the server what packages exist. See [[server_config]] to configure that.
{| class="wikitable" style="text-align: left;"
!colspan="6"|Package Limitations
|-
|Max packages
|64
|-
|Max client files per package, including client scripts
|1024
|-
|Max file size
|2GB
|-
|Max client script size
|1MB
|}


== Client package cache ==
== Client package cache ==
Files downloaded from a server are being cached on the client in this folder: '''%appdata%\..\Local\Horizon\Saved\ServerContent
Files downloaded from servers are being cached on the client in the folder: '''%LocalAppData%\Onset\Saved\ServerContent'''


That way files are only downloaded once. If you change a file on the server the checksum of it will change. In this case the client will be downloaded again by the client.
That way files are only downloaded once. If you change a file on the server the checksum of it will change. In this case the client will be downloaded again by the client.
The ''server.json'' file stores information of the server from where the files have been downloaded from.
The ''server.json'' file stores information of the server from where the files have been downloaded from.

Latest revision as of 12:14, 11 January 2021

A package is collection of Lua scripts and other files. You can have up to 64 packages and 1024 files per package on your server.

Allowed file type extensions: lua, js, css, html, htm, png, jpg, jpeg, gif, svg, wav, mp3, ogg, oga, flac, m4a, woff2, ttf, pak, json, map

Example packages: https://github.com/BlueMountainsIO/OnsetLuaScripts

Lua context

Each package has their own LuaVM state. Lua script files that are loaded in the same package can access the same global variables. Variables defined as local are only visible in that single .lua file.

You can export functions from one package and import them in another package. See AddFunctionExport and ImportPackage. This enables you to create packages that act as pure libraries.

Folder layout

Each package has a folder that is placed inside the packages or inside the autostart folder on your server. Example layout:

OnsetServer.exe
server_config.json
    /autostart
        /myautostartpackage
            index.lua
            script.lua
    /packages
        /mypackagename
            index.lua
            package.json
        /mapeditor
            index.lua
            package.json
            /client
                editor.lua
            /server
                server.lua

autostart

Packages can be automatically started on server start. For that to work you must place your package into the autostart folder. If the folder does not exist, create it at the root where your OnserServer executable is located.

Notice: StartPackage will first look into the autostart folder before looking in the packages folder.

index.lua

The index.lua is executed before the server loads the package.json file. In this Lua file you can register scripts and files to this package.

The following functions are only available to the index.lua script. Besides that, only Lua library functions are exposed the index.lua but no other Onset server functions.

--index.lua
AddServerScript("server/*_s.lua")
AddClientScript("client/*_c.lua")
AddSharedScript("shared/*.lua")
AddFile("audio/sound.mp3")
AddFile("ui/*.html")

For the package to work, there has to be either an index.lua or a package.json config file. Both at the same time are also supported.

package.json

Your package.json defines server and client script files. It also defines what files are required for this package to work. Files defined in client_scripts, shared_scripts and files are being downloaded by clients once they join the game server.

Lua scripts defined in shared_scripts are executed on both server and client. The function IsServer and IsClient can be used to determine if a script currently runs on the server or client.

For the package to work there has to be either an index.lua or a package.json config file. Both at the same time are also supported.

Wildcards (*) are supported.

{
	"author": "Blue Mountains",
	"version": "1.0",
	"server_scripts": [
		"server/*.lua"
	],
	"client_scripts": [
		"client/editor.lua"
	],
	"shared_scripts": [
		"shared_script.lua"
	],
	"files": [
		"client/gui/editor.html",
		"client/gui/editor.css",
		"client/gui/editor.js",
		"client/gui/jquery.js",
		"client/gui/OpenSansRegular.woff2",
		"client/gui/OpenSansBold.woff2",
		"client/gui/images/*"
	]
}

Each package has a package.json in it's root path. See the folder layout above. Additionally you have to tell the server what packages exist. See server_config to configure that.

Package Limitations
Max packages 64
Max client files per package, including client scripts 1024
Max file size 2GB
Max client script size 1MB

Client package cache

Files downloaded from servers are being cached on the client in the folder: %LocalAppData%\Onset\Saved\ServerContent

That way files are only downloaded once. If you change a file on the server the checksum of it will change. In this case the client will be downloaded again by the client. The server.json file stores information of the server from where the files have been downloaded from.