WARNING

this is VERY OUT OF DATE. this is a mod for my (flux's) personal use, and maintaining documentation outside the code isn't worth the time. if other people start using this, i'll reconsider that position.

classes

futil.class1(super) a simple class w/ optional inheritance
futil.class(...) a less simple class w/ multiple inheritance and is_a support

data structures

futil.Deque

a deque. supported methods:
- Deque:size()
- Deque:push_front(value)
- Deque:push_back(value)
- Deque:pop_front()
- Deque:pop_back()
futil.PairingHeap

a pairing heap. supported methods:
- PairingHeap:size()
- PairingHeap:peek_max()
- PairingHeap:delete(value)
- PairingHeap:delete_max()
- PairingHeap:get_priority(value)
- PairingHeap:set_priority(value, priority)

futil.DefaultTable

a table in which missing keys are automatically filled in. example usage:

local default_table = futil.DefaultTable(function(key) return {} end)
default_table.foo.bar = 100 -- foo is automatically created as a table

general routines

futil.check_call(func)

wraps func in a pcall. if no error occurs, returns the results. otherwise, logs and returns nil.
futil.memoize1(f)

memoize a single-argument function
futil.memoize_dumpable(f)

memoize a function if the arguments produce a unique result when dump()-ed
futil.memoize1_modstorage(id, func)

memoize a function and store the results in modstorage, so they persist between sessions.
futil.truncate(s, max_length, suffix)

if the string is longer than max_length, truncate it and append suffix. suffix is optional, defaults to "..."
futil.lc_cmp(a, b)

case-insensitive comparator
futil.table.set_all(t1, t2)

sets all key/value pairs of t2 in t1
futil.table.pairs_by_value(t, sort_function)

iterator which returns key/value pairs, sorted by value
futil.table.pairs_by_key(t, sort_function)

iterator which returns key/value pairs, sorted by key
futil.table.size(t)

gets the size of a table
futil.table.is_empty(t)

returns true if the table is empty
futil.equals(a, b)

returns true if the tables (or other values) are equivalent. do not use w/ recursive structures. currently does not inspect metatables.
futil.table.count_elements(t)

given a table in which some values may repeat, returns a table mapping values to their count.
futil.table.sets_intersect(set1, set2)

returns true if set1 and set2 have any keys in common.
futil.table.iterate(t)

iterates the values of an array-like table
futil.table.reversed(t)

returns a reversed copy of the table.
futil.table.contains(t, value)

returns true if value is in table
futil.table.keys(t)

returns a table of the keys in the given tables.
futil.table.values(t)

returns a table of the values in the given tables.
futil.table.sort_keys(t, sort_function)

returns a table of the sorted keys of the given table.
futil.wait(n)

busy-waits n microseconds
futil.file_exists(path)

returns true if the path points to a file that can be opened
futil.load_file(filename)

returns the contents of the file if it exists, otherwise nil.
futil.write_file(filename, contents)

writes to a file. returns true if success, false if not.
futil.path_concat(...)

concatenates part of a file path.
futil.path_split(path)

splits a path into parts.
futil.string.truncate(s, max_length, suffix)

truncate a string if it is longer than max_length, adding suffix (default "...").
futil.string.lc_cmp(a, b)

compares the lower-case values of strings a and b.
futil.seconds_to_interval(time)

transforms a time (in seconds) to a format like "[[[[:]:]:]:]"p
futil.format_utc(timestamp)

formats a timestamp in UTC.

predicates

futil.is_nil(v)

true if v is nil
futil.is_boolean(v)

true if v is a boolean.
futil.is_number(v)

true if v is a number.
futil.is_string(v)

true if v is a string.
futil.is_userdata(v)

true if v is userdata.
futil.is_function(v)

true if v is a function.
futil.is_thread(v)

true if v is a thread.
futil.is_table(v)

true if v is a table.

functional

futil.functional.noop()

the NOTHING function does nothing.
futil.functional.identity(x)

returns x
futil.functional.izip(...)

zips iterators.
futil.functional.zip(...)

zips tables.
futil.functional.imap(func, ...)

maps a function to a sequence of iterators. the first arg to func is the first element of each iterator, etc.
futil.functional.map(func, ...)

maps a function to a sequence of tables. the first arg to func is the first element of each table, etc.
futil.functional.apply(func, t)

for all keys k, set t[k] = func(t[k])
futil.functional.reduce(func, t, initial)

applies binary function func to successive elements in t and a "total". supply initial if possibly #t == 0. e.g. local sum = function(values) return reduce(function(a, b) return a + b end, values, 0) end.
futil.functional.partial(func, ...)

curries func. `partial(func, a, b, c)(d, e, f) == func(a, b, c, d, e, f)
futil.functional.compose(a, b)

binary operator which composes two functions. compose(a, b)(x) == a(b(x))
futil.functional.ifilter(pred, i)

returns an interator which returns the values of iterator i which match predicate pred
futil.functional.filter(pred, t)

returns an interator which returns the values of table t which match predicate pred
futil.functional.iall(i)

given an iterator, returns true if all non-nil values of the iterator are not false.
futil.functional.all(t)

given a table, returns true if the table doesn't contain any false values
futil.functional.iany(i)

given an iterator, returns true if the iterator produces any non-false values.
futil.functional.any(t)

given a table, returns true if it contains any non-false values.

iterators

futil.iterators.range(...)
- one arg: return an iterator from 1 to x.
- two args: return an iterator from x to y
- three args: return an iterator from x to y, incrementing by z
iterators.repeat_(value, times)
- times = nil: return value forever
- times = positive number: return value times times
futil.iterators.chain(...)

given a sequence of iterators, return an iterator which will return the values from each in turn.
futil.iterators.count(start, step)

returns an infinite iterator which counts from start by step. if step is not specified, counts by 1.
futil.iterators.values(t)

returns an iterator of the values in the table.
futil.list(iterator)

given an iterator, returns a table of the values of the iterator.
futil.list_multiple(iterator)

given an iterator which returns multiple values on each step, create a table of tables of those values.

math

futil.math.idiv(a, b)

returns the whole part of a division and the remainder, e.g. math.floor(a/b), a%b.
futil.math.bound(m, v, M)

if v is less than m, return m. if v is greater than M, return M. else return v.
futil.math.in_bounds(m, v, M)

return true if m <= v and v <= M
futil.math.is_integer(v)

returns true if v is an integer.
futil.math.is_u8(i)

returns true if i is a valid unsigned 8 bit value.
futil.math.is_u16(i)

returns true if i is an unsigned 16 bit value.
futil.math.sum(t, initial)

given a table, get the sum of the values in the table. initial is the value from which to start counting. if initial is nil and the table is empty, will return nil.
futil.math.isum(i, initial)

like the above, but given an iterator.

minetest-specific routines

futil.add_groups(itemstring, new_groups)

new_groups should be a table of groups to add to the item's existing groups
futil.remove_groups(itemstring, ...)

... should be a list of groups to remove from the item's existing groups
futil.get_items_with_group(group)

returns a list of itemstrings which belong to the specified group
futil.get_location_string(inv)

given an InvRef, get a location string suitable for use in formspec
futil.resolve_item(item)

given an itemstring or ItemStack, follows aliases until it finds the real item. returns an itemstring.
futil.items_equals(item1, item2)

returns true if two itemstrings/stacks represent identical stacks.
futil.get_blockpos(pos)

converts a position vector into a blockpos
futil.get_block_bounds(blockpos)

gets the bound vectors of a blockpos
futil.formspec_pos(pos)

convert a position into a string suitable for use in formspecs
futil.iterate_area(minp, maxp)

creates an iterator for every point in the volume between minp and maxp
futil.iterate_volume(pos, radius)

like the above, given a position and radius (L∞ metric)
futil.serialize(x)

turns a simple lua data structure (e.g. a table no userdata or functions) into a string
futil.deserialize(data)

the reverse of the above. not safe; do not use w/ untrusted data
futil.strip_translation(msg)

strips minetest's translation escape sequences from a message
futil.get_safe_short_description(item)

gets a short description which won't contain unmatched translation escapes
futil.escape_texture(texturestring)

escapes a texture modifier, for use within another modifier
futil.get_horizontal_speed(player)

get's a player's horizontal speed.
futil.is_on_ground(player)

returns true if a player is standing on the ground. NOTE: this is currently unfinished, and doesn't report correctly if a player is standing on things with complex collision boxes which are rotated via paramtype2="facedir" or similar.

fake inventory

this is useful for testing multiple actions on an inventory without having to worry about changing the inventory or reverting it. this is a better solution than a detached inventory, as actions on a detached inventory are still sent to clients. fake inventories support all the regular methods of a minetest inventory object, with some additions.

futil.FakeInventory()

create a fake inventory.
futil.FakeInventory.create_copy(inv)

copy all the inventory lists from inv into a new fake inventory. will also create a copy of another fake inventory.
futil.FakeInventory.room_for_all(inv, listname, items)

create a copy of inv, then tests if all items in the list items can be inserted into listname.

globalstep

implements common boilerplate for globalsteps which are intended to execute every so often.

futil.register_globalstep({
    period = 1,  -- the globalstep should be run every <period> seconds
    catchup = "single", -- whether to "catch up" if lag prevents the callback from running
                        -- if not specified, no catchup will be attempted.
                        -- if "single", the callback will be run at most once per server-step until we've caught up.
                        -- if "full", will re-run the callback within the current step until we've caught up.
    func = function(dtime) end,  -- code to execute
})

hud manager

code to manage HUDs

local hud = futil.define_hud("my_hud", {
    period = nil,  -- if a number is given, will automatically update the hud for all players every <period> seconds.
    name_field = nil, -- which hud field to use to store an identifier. this should be a field not used by the given
                      -- hud_elem_type. defaults to "name", which is good for most types. waypoints are an exception.
    get_hud_def = function(player) return {} end,  -- return the expected hud definition for the player.
                                                   -- if nil is returned, the hud will be removed.
    enabled_by_default = false, -- whether the hud should be enabled by default.
})

local player = minetest.get_player_by_name("flux")
if hud:toggle_enabled(player) then
    print("hud now enabled")
else
    print("hud now disabled")
end

print("hud is " .. (hud:is_enabled(player) and "enabled" or "disabled"))

hud:update(player)  -- calls hud.get_hud_def(player) and updates the players hud

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

WARNING

classes

data structures

general routines

predicates

functional

iterators

math

minetest-specific routines

fake inventory

globalstep

hud manager

Uh oh!

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

WARNING

classes

data structures

general routines

predicates

functional

iterators

math

minetest-specific routines

fake inventory

globalstep

hud manager