Skip to main content

Environment

Filesystem​

All files in your repository with a known extension will be exposed via a virtual filesystem.

  • .lua files can be loaded using the standard library require().
  • .toml files can be loaded using the function File.LoadTOML.
  • .json files can be loaded using the function File.LoadJSON or in the case of behavior trees BT.Load.
  • .wav files can be loaded using the function File.LoadAudio.
  • .png, .gif, .bmp and .jpg files can be loaded using the function File.LoadSprites/File.LoadTexture.
  • .obj files can be loaded using the function File.LoadModel.
  • .mtl files can be bundled together with the .obj files although they can't be directly accessed.

With all of these primitives, path string is case insensitive and you may omit the extension with the exception of LoadSprites/LoadTexture. The path is relative to the module base by default but you can prefix it with @ to signify global lookup which ignores the current path allowing you to read other modules files.

You may choose to prevent any files from being shared by using _ either in the directory or the file name as a prefix (e.g. /_private/x.png or /resources/_private.png), however do note that Lua files are already unreadable so there's no real reason to do so unless you're trying to keep a data file or art that belongs to you private.

-- Returns all directory and files at the given directory path, entries that are directories are terminated with '/'.
string[]        File.Enumerate(string path, int? level)

-- Checks the existance of a file at the given path.
bool            File.Exists(string path, int? level)

-- Loads a JSON file and returns it as a Lua object.
any             File.LoadJSON(string path, int? level)

-- Loads a TOML file and returns it as a Lua object.
any             File.LoadTOML(string path, int? level)

-- Loads the given texture as a sprite map and returns the texture id and the width and height of the atlas.
{int, int, int} File.LoadSprites(string path, int? dims, int? level)

-- Loads the given texture as a singular sprite
{int, float}    File.LoadTexture(string path, int? flags, int? level)

-- Loads an audio file and returns the audio bank id.
int             File.LoadAudio(string path, int? level)

-- Loads the Wavefront object as a CommandBuffer.
CommandBuffer   File.LoadModel(string path, int? level)

-- Gets the current path.
string          File.CurrentPath(int? level)

Example​

MyRepo/index.lua
local a = require "directory.test"
local b = require "directory/test"
local j = File.LoadJSON("directory/test")
local t = File.LoadTOML("directory/test")
print(a, b, j.a, j.b, t.a.b) -- Prints "42     42     42.4     42.42     42.4242"
MyRepo/directory/test.lua
return 42
MyRepo/directory/test.json
{ "a": "42.4", "b": 42.42 }
MyRepo/directory/test.toml
[a]
b = 42.4242
tip

For the security of your private scripts, we have disabled string.dump globally, and additionally you cannot read any .lua file using these primitives.

Dependencies​

We consider every public directory with a index.lua or index.ts an exported module. Exported modules can only be accessed after the Init event and they will need to be referenced. Every other script is lazily loaded and you can use the require function to import them.

An exception to this is the core modules provided by us, all of which you can access by their name as if they were builtins (e.g. Core/Aimbot -> Aimbot.*) and are guaranteed to be loaded before any other scripts thus eliminating the need to wait for the Init event.

-- Initialization event that gets emitted after module parsing is complete.
--   Note: `Init` event cannot be used after it is triggered.
Event<void> Event.OnInit

Exports​

Every non-local variable and function in the index.lua file will be a public export. For all other scripts, you must return the export list explicitly.

ModA/index.lua
Value = 5
ModA/B/index.lua
Value = 6
ModA/test.lua
return { Value = 7 }

Imports​

Module entries are accessed using the global @<ModuleName> tables or by calling the function @ with the module name. Alternatively if this is an essential import you can use require function with the argument @<ModuleName>/@<ModuleName>.index.

Example/index.lua
local test = require "@ModA.test"
print(test.Value)           -- 7

Event.OnInit |_| do
   print(@ModA.Value)       -- 5
   print(@[[ModA.B]].Value) -- 6
end