voxelcore/doc/en/scripting.md

Scripting

Project uses LuaJIT as a scripting language.

Subsections:

• Engine events
• User input
• Filesystem and serialization
• UI properties and methods
• Entities and components
• Libraries
  • app
  • assets
  • base64
  • bjson, json, toml, yaml
  • block
  • byteutil
  • cameras
  • entities
  • file
  • gfx.blockwraps
  • gfx.particles
  • gfx.posteffects
  • gfx.skeletons
  • gfx.text3d
  • gfx.weather
  • gui
  • hud
  • input
  • inventory
  • item
  • mat4
  • network
  • pack
  • pathfinding
  • player
  • quat
  • random
  • rules
  • session
  • time
  • utf8
  • vec2, vec3, vec4
  • world
• Module core:bit_converter
• Module core:data_buffer
• Module core:vector2, core:vector3

Type annotations

The documentation for Lua libraries uses type annotations, not part of Lua syntax.

• vector - an array of three or four numbers
• vec2 - array of two numbers
• vec3 - array of three numbers
• vec4 - array of four numbers
• quat - array of four numbers - quaternion
• matrix - array of 16 numbers - matrix

Namespaces

Currently, the engine uses a namespace hierarchy that minimizes conflicts between individual modules, scripts, and even packs.

The following structure is relevant:

• Global namespace (_G), which is the root namespace. Writing to it outside of engine core modules is highly undesirable, as it can waste hours of debugging time.
  • Pack namespace - created each time content is loaded for each pack included in the configuration. This namespace is used by modules, as well as item and block scripts.
    • Component namespace.
    • UI document namespace.
• Isolated world generator namespace.

Modules

A module is a global object with a lifetime limited to the lifetime of the loaded content, used both for interaction between different packages and as a substitute for global variables within the package itself.

The module must be located in contentpack/modules/** (subfolders are allowed, but you will need to specify them)

local module_name = require "contentpack:module_name" -- imports the module

-- If the module is in the same pack in which it is imported, you can use the shortcut:
local module_name = require "module_name"

-- When using nested folders:
local module_name = require "contentpack:path/to/module_name" -- the path does not include `modules`
local module_name = require "path/to/module_name" -- if in the same pack

The module will have the namespace of the folder in which it is located, regardless of the namespace from which the first import was performed.

When creating a module, you should follow the following approach, which is what require expects:

local this = {
    variable_name = ... -- public variables
}

-- private module variables
local variable_name = ...

-- private module functions
local function function_name(...)
    ...
end

-- public module functions
function this.function_name(...)
    ...
end

return this -- the result that require will return and cache

When reimported, the module will not be reloaded; instead, require will return the cached result.