VoxelEngine/doc/en/scripting/filesystem.md

Filesystem and serialization

file library

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.

json library

The library contains functions for serializing and deserializing tables:

json.tostring(object: table, human_readable: bool=false) -> str

Serializes an object into a JSON string. If the second parameter is true, multi-line human-readable formatting will be used, rather than the compact format used by default.

json.parse(code: str) -> table

Parses a JSON string into a table.

toml library

The library contains functions for serializing and deserializing tables:

toml.tostring(object: table) -> str

Serializes an object into a TOML string.

toml.parse(code: str) -> table

Parses a TOML string into a table.

bjson library

The library contains functions for working with the binary data exchange format vcbjson.

-- Encodes a table into a byte array
bjson.tobytes(
    -- encoded table
    value: table,
    -- compression
    [optional] compression: bool=true
) --> Bytearray

-- Decodes a byte array into a table
bjson.frombytes(bytes: table | Bytearray) --> table

Storing data in a world

When saving pack data in the world, you should use the function:

pack.data_file(packid: str, filename: str) -> str

Returns data file path like: world:data/packid/filename and creates missing directories.

If paths other than data/{packid}/... are used, data may be lost.