12 KiB
Scripting
Project uses LuaJIT as a scripting language.
Core functions
require "packid:module_name" -- load Lua module from pack-folder/modules/
-- no extension included, just name
-- deprecated functions
load_script("packid:scripts/script_name.lua") -- load Lua script if not loaded yet
load_script("packid:scripts/script_name.lua", true) -- load Lua script anyway
pack library
pack.is_installed(packid: str) -> bool
Check if specified pack is installed in the world
pack.data_file(packid: str, filename: str) -> str
Returns data file path like world:data/packid/filename
and creates missing directories.
Use this function when saving pack settings or other data to the world.
Example:
file.write(pack.data_file(PACK_ID, "example.txt"), text)
For pack containermod will write text to the file world:data/containermod/example.txt
player library
player.get_pos(playerid: int) -> number, number, number
Returns x, y, z coordinates of the player
player.set_pos(playerid: int, x: number, y: number, z: number)
Set player position
player.get_rot(playerid: int) -> number, number, number
Returns x, y, z of camera rotation (radians)
player.set_rot(playerid: int, x: number, y: number, z: number)
Set camera rotation (radians)
player.get_inventory(playerid: int) -> int, int
Returns player inventory ID and selected slot index (0-9)
player.is_flight() -> bool
player.set_flight(bool)
Getter and setter for player flight mode
player.is_noclip() -> bool
player.set_noclip(bool)
Getter and setter for player noclip mode (collisions disabled)
world library
world.get_day_time() -> number
Returns current day time in range [0.0-1.0] where 0.0 and 1.0 - midnight, 0.5 - noon.
world.set_day_time(time: number)
Set day time value.
world.get_total_time() -> number
Returns total time passed in the world
world.get_seed() -> int
Returns world seed.
pack library
pack.get_folder(packid: str) -> str
Returns installed content-pack folder
pack.is_installed(packid: str) -> bool
Check if the world has specified pack installed
pack.get_installed() -> array of strings
Returns all installed content-pack ids
gui library
Library contains ui elements access functions. Library should not be directly used, because script layouts/layout_name.xml.lua already has a generated variable document (instance of Document)
Example:
print(document.some_button.text) -- where 'some_button' is an element id
document.some_button.text = "new text"
inventory library
Library for inventories interaction.
inventory.get(invid: int, slot: int) -> int, int
Requires an inventory ID and slot index. Returns item ID and count. ID = 0 (core:empty) means that slot is empty.
inventory.set(invid: int, slot: int, itemid: int, count: int)
Set slot content.
inventory.size(invid: int) -> int
Returns inventory size (slots number). Throws an exception if there's no inventory having specified ID.
inventory.add(invid: int, itemid: int, count: int) -> int
Add an item to the specified inventory. Returns remaining count if could not to add fully.
inventory.get_block(x: int, y: int, z: int) -> int
Returns block inventory ID or 0.
inventory.bind_block(invid: int, x: int, y: int, z: int)
Bind inventory to the specified block.
inventory.unbind_block(x: int, y: int, z: int)
Unbind inventory from the specified block.
Warning
Unbound inventories will be deleted on world close.
inventory.clone(invid: int) -> int
Create inventory copy. Returns the created copy ID.
inventory.move(invA: int, slotA: int, invB: int, slotB: int)
Move item from slotA of invA to slotB of invB. invA may be the same as invB. If slotB will be chosen automaticly if argument is not specified.
block library
block.name(blockid: int) -> str
Returns block string ID (name) by index
block.index(name: str) -> int
Returns block integer ID (index) by name
block.get(x: int, y: int, z: int) -> int
Returns integer ID by block position
block.get_states(x: int, y: int, z: int) -> int
Returns block state (rotation + additional information) as an integer.
block.set(x: int, y: int, z: int, id: int, states: int)
Set block with specified integer ID and state (default - 0) at specified position.
Warning
block.setdoes not trigger on_placed.
block.is_solid_at(x: int, y: int, z: int) -> bool
Check if block at the specified position is solid.
block.is_replaceable_at(x: int, y: int, z: int) -> bool
Check if block may be placed at specified position. (Examples: air, water, grass, flower)
block.defs_count() -> int
Returns count of available block IDs.
Following three functions return direction vectors based on block rotation.
block.get_X(x: int, y: int, z: int) -> int, int, int
Returns X: integer direction vector of the block at specified coordinates. Example: no rotation: 1, 0, 0
block.get_Y(x: int, y: int, z: int) -> int, int, int
Returns Y: integer direction vector of the block at specified coordinates. Example: no rotation: 0, 1, 0
block.get_Z(x: int, y: int, z: int) -> int, int, int
Returns Z: integer direction vector of the block at specified coordinates. Example: no rotation: 0, 0, 1
block.get_rotation(x: int, y: int, z: int) -> int
Returns block rotation index based on used profile.
block.set_rotation(x: int, y: int, z: int, rotation: int)
Set block rotation by index.
User bits
Part of a voxel data used for scripting. Size: 8 bit.
block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
Get specified bits as an unsigned integer.
block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
Set specified bits.
item library
item.name(itemid: int) -> str
Returns item string ID (name) by index
item.index(name: str) -> int
Returns item integer ID (index) by name
item.stack_size(itemid: int) -> int
Returns max stack size for the item
item.defs_count() -> int
Returns count of available item IDs.
hud library
hud.open_inventory()
Open player inventory
hud.close_inventory()
Close inventory
hud.open_block(x: int, y: int, z: int) -> int, str
Open block UI and inventory. Throws an exception if block has no UI layout.
Returns block inventory ID (if "inventory-size"=0 a virtual inventory will be created), and UI layout ID.
hud.show_overlay(layoutid: str, playerinv: bool)
Show overlay with layout specified. Shows player inventory also if playerinv is true
Note
Only one block may be open at same time
hud.open_permanent(layoutid: str)
Add element to the screen. The element will be removed on world close only. inventory element will be bound to the player inventory.
hud.close(layoutid: str)
Remove an element from the screen
hud.get_block_inventory() -> int
Get open block inventory ID or 0
Block events
function on_placed(x, y, z, playerid)
Called on block placed by player
function on_broken(x, y, z, playerid)
Called on block broken by player
function on_interact(x, y, z, playerid) -> bool
Called on block RMB click interaction. Prevents block placing if true returned.
function on_update(x, y, z)
Called on block update (near block changed)
function on_random_update(x, y, z)
Called on random block update (grass growth)
function on_blocks_tick(tps: int)
Called tps (20) times per second.
Item events
function on_use(playerid: int)
Called on RMB click out of a block.
function on_use_on_block(x: int, y: int, z: int, playerid: int)
Called on block RMB click. Prevents block placing-block placing if returns true
function on_block_break_by(x: int, y: int, z: int, playerid: int)
Called on block LMB click (unbreakable blocks included). Prevents block destruction if returns true.
World events
Script scripts/world.lua events.
function on_world_open()
Called on world open.
function on_world_save()
Called before world save.
function on_world_tick()
Called 20 times per second
function on_world_quit()
Called on world close (after saving)
Layout events
Script layouts/layout_name.xml.lua events.
function on_open(invid: int, x: int, y: int, z: int)
Called on element added to the screen. invid=0 if no inventory bound x,y,z=0 if no block bound
function on_close(invid: int)
Called on element removed from the screen.
HUD events
Script scripts/hud.lua events.
function on_hud_open(playerid: int)
Called after world open.
function on_hud_close(playerid: int)
Called on world close (before saving)
Engine libraries
file
Filesystem interaction library.
file.resolve(path: str) -> str
Function turns entry_point:path (example user:worlds/house1) to a regular path. (example C://Users/user/.voxeng/worlds/house1)
Note
The function should be used for debug only. entry_point:path notation is required in all file functions.
Resulting path is not canonical and may be relative.
file.read(path: str) -> str
Read whole text file.
file.read_bytes(path: str) -> array of integers
Read file into bytes array.
file.write(path: str, text: str) -> nil
Overwrite text file.
file.write_bytes(path: str, data: array of integers)
Overwrite binary file with bytes array.
file.length(path: str) -> int
Get file length (bytes) or 0.
file.exists(path: str) -> bool
Check if file or directory exist.
file.isfile(path: str) -> bool
Check if the path points to a file.
file.isdir(path: str) -> bool
Check if the path points to a directory.
file.mkdir(path: str) -> bool
Create directory. Returns true if new directory created
file.mkdirs(path: str) -> bool
Create directories chain. Returns true if new directory created
time
time.uptime() -> float
Returns time elapsed since the engine started.
Available modules
TOML serialization/deserialization
local toml = require "core:toml"
local t = {a=53, b=42, s="test", sub={x=1, y=6}}
local s = toml.serialize(t)
print(s)
local t2 = toml.deserialize(s)
output:
b = 42
s = "test"
a = 53
[sub]
y = 6
x = 1