Modular Multipurpose Minetest Modding Library
Go to file
2021-03-30 18:10:50 +02:00
minetest Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
.gitignore B3D test utility 2021-02-01 16:27:21 +01:00
b3d_specification.txt Experimental Blitz3D .b3d file reader 2021-01-31 21:41:42 +01:00
b3d.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
binary.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
bluon.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
conf.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
data.lua Fix syntax error & indentation 2021-03-27 21:04:49 +01:00
file.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
func.lua Add func.call_by_value 2021-03-22 18:17:26 +01:00
heap.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
init.lua Bump version 2021-03-30 18:10:50 +02:00
kdtree.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
log.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
math.lua Fix math.fround 2021-03-30 18:06:58 +02:00
mod.conf Large configuration improvements, text helpers 2020-06-02 23:07:33 +02:00
mod.lua Fix whitespace 2021-03-30 18:06:10 +02:00
player.lua Deprecate player.get_color_int, beautification 2021-01-30 11:50:05 +01:00
quaternion.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
ranked_set.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
Readme.md Bump version 2021-03-30 18:10:50 +02:00
schema.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
screenshot.png Large configuration improvements, text helpers 2020-06-02 23:07:33 +02:00
table.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00
test.lua Make tests Minetest-independent 2021-03-30 18:06:41 +02:00
text.lua Removed dead code 2021-03-27 20:11:07 +01:00
trie.lua Add trie 2020-12-19 15:13:03 +01:00
vector.lua Indentation: Use only tabs 2021-03-27 20:10:49 +01:00

Modding Library (modlib)

Multipurpose Minetest Modding Library

About

No dependencies. Licensed under the MIT License. Written by Lars Mueller aka LMD or appguru(eu).

API

Mostly self-documenting code. Mod namespace is modlib or _ml, containing all variables & functions.

Bluon

Binary Lua object notation. Experimental. Handling of subnormal numbers (very small floats) may be broken.

new(def)

def = {
    aux_is_valid = function(object)
        return is_valid
    end,
    aux_len = function(object)
        return length_in_bytes
    end,
    -- read type byte, stream providing :read(count), map of references -> id
    aux_read = function(type, stream, references)
        ... = stream:read(...)
        return object
    end,
    -- object to be written, stream providing :write(text), list of references
    aux_write = function(object, stream, references)
        stream:write(...)
    end
}

:is_valid(object)

Returns whether the given object can be represented by the instance as boolean.

:len(object)

Returns the expected length of the object if serialized by the current instance in bytes.

:write(object, stream)

Writes the object to a stream supporting :write(text). Throws an error if invalid.

:read(stream)

Reads a single bluon object from a stream supporting :read(count). Throws an error if invalid bluon.

Checking whether the stream has been fully consumed by doing assert(not stream:read(1)) is left up to the user.

Format

  • nil: nothing ("")
  • false: 0
  • true: 1
  • Numbers:
    • Constants: 0, nan, +inf, -inf
    • Integers: Little endian U8, U16, U32, U64, -U8, -U16, -U32, -U64
    • Floats: Little endian F32, F64
  • Strings:
    • Constant: ""
    • Length as unsigned integer: T8, T16, T32, T64
  • Tables:
    • List and map part count as unsigned integers
    • L0, L8, L16, L32, L64 times M0, M8, M16, M32, M64
  • Reference:
    • Reference ID as unsigned integer: R8, R16, R32, R64
  • Reserved types:
    • Everything <= 55 => 200 free types

Features

  • Embeddable: Written in pure Lua
  • Storage efficient: No duplication of strings or reference-equal tables
  • Flexible: Can serialize circular references and strings containing null

Simple example

local object = ...
-- Write to file
local file = io.open(..., "w")
modlib.bluon:write(object, file)
file:close()
-- Write to text
local rope = modlib.table.rope{}
modlib.bluon:write(object, rope)
text = rope:to_text()
-- Read from text
local inputstream = modlib.text.inputstream"\1"
assert(modlib.bluon:read(object, rope) == true)

Advanced example

-- Serializes all userdata to a constant string:
local custom_bluon = bluon.new{
    aux_is_valid = function(object)
        return type(object) == "userdata"
    end,
    aux_len = function(object)
        return 1 + ("userdata"):len())
    end,
    aux_read = function(type, stream, references)
        assert(type == 100, "unsupported type")
        assert(stream:read(("userdata"):len()) == "userdata")
        return userdata()
    end,
    -- object to be written, stream providing :write(text), list of references
    aux_write = function(object, stream, references)
        assert(type(object) == "userdata")
        stream:write"\100userdata"
    end
}
-- Write to text
local rope = modlib.table.rope{}
custom_bluon:write(userdata(), rope)
assert(rope:to_text() == "\100userdata")

Configuration

Legacy

  1. Configuration is loaded from <worldpath>/config/<modname>.<extension>, the following extensions are supported and loaded (in the given order), with loaded configurations overriding properties of previous ones:
    1. json
    2. lua
    3. luon, Lua but without the return
    4. conf
  2. Settings are loaded from minetest.conf and override configuration values

Locations

  1. Default configuration: <modfolder>/conf.lua
  2. World configuration: config/<modname>.<format>
  3. Mod configuration: <modfolder>/conf.<format>
  4. Minetest configuration: minetest.conf

Formats

  1. lua
  • Lua, with the environment being the configuration object
  • field = value works
  • Return new configuration object to replace
  1. luon
  • Single Lua literal
  • Booleans, numbers, strings and tables
  1. conf
  • Minetest-like configuration files
  1. json
  • Not recommended

Versions

rolling-56

  • Fixes math.fround
  • Other minor fixes