This mod provides a game-agnostic API to limit node interaction based on an access list. The owner of an access list can add player names to grant them access to the node or feature the list controls.

The mod provides a purposeful and neutral looking formspec, and customizing options to adapt it to your game/mod but also allows to prepend the formspec as needed.

The access list dialog for a crafting table in widescreen format.

All API functions were created to be used for having an access list system in individual mods, but also to allow overriding already existing item interactions from the game and from other mods.

API calls

See the API documentation for detailed descriptions of these functions.

-- Available API Functions
access_list.init(pos, player, third)
access_list.show_formspec(pos, player, third)
access_list.has_access(pos, player, third)
access_list.can_dig(pos, player, third)
access_list.get_raw_list(pos, player, third)
access_list.get_clean_list(pos, player, third)

-- Metadata information table
access_list.meta[...]

Detailed usage examples are also available in the examples directory.

Minimal API implementation example

This example registers a node with an access list. The API functions can be used without a wrapper function where the Luanti API uses position, player, … or position, something_else, player, … as parameter order.

core.register_node('mymod:my_cool_node', {
    description = 'Access list example node',
    groups = { oddly_breakable_by_hand = 1 },

    after_place_node = access_list.init,
    on_dig = access_list.can_dig,
    on_rightclick = access_list.show_formspec
})

Without additional code this node has no further functionality than managing the access list and protecting itself from digging.

Access list entries

The access list is stored as a single string with line breaks and is processed into a usable list when needed. This means that the list can contain arbitrary text. Whenever the list is processed, all entries are validated and the player name is checked against the sanitized list.

You can add comments to the list. Comments can start with either # or -- and you can mix them as you like. Everything from the comment indicator to the end of the line (including surrounding whitespace) is treated as a comment.

Foobar
Its-a-me

# My friends
CoolGuy123
Someone_Else

More-Names-Here -- This one!

# My friends, -- This one!, and the empty lines are ignored, all other lines are valid names. Players with those names have access.

If an access list contains an asterisk (*), it makes the access public. This means all players are granted access regardless of the other entries in the list.

Access list management

The access list formspec shows the node details and position of the currently edited access list, the access list itself, and the owner.

The owner can edit the access list. Administrators (i.e. all users with the server privilege) can edit the access list and set the owner. All other players – even if on the access list – cannot see or edit the access list or the owner.

• By clicking “Save” the access list gets saved in the position’s node metadata.
• With “Cleanup”, the list is saved and then replaced with an alphabetically ordered list where all lines with invalid names, all empty lines, all comments, and all duplicated lines are removed.
• Using “Reload” fetches the currently active access list and the owner and replaces all unsaved changes.
• If the owner field is empty on submitting, and the submitter is an admin, the owner gets reset to the placer of the node the access list comes from.

The current action or status is shown as chat message to the currently interacting user.

Error handling

If the access list metadata is missing, only admins have access. If the owner metadata field is still available, owners have access, too. Players that are not admins or the owner are locked out. You need to re-place the node to initialize the access list functionality again.

Metadata may become unavailable if a game or another mod replaces node metadata instead of modifying only the fields it needs. In this case you should contact the other mod’s author or the game’s maintainer.

Configuration

The formspec can be customized in terms of size and colors. By default it uses no_prepend[] to provide a uniform look regardless of game. The non-color options are mainly meant for adjusting the mod to larger game fonts or when prepending the formspec with large styling or backgrounds.

# If you set this to false, the `no_prepend[]` formspec option and the
# colors get removed and the game’s default prepending is used.
access_list_no_prepend = true

# Background colors
access_list_background_color  = #343434
access_list_header_background = #dededeaa

# Button colors
access_list_button_edit    = #8ae234
access_list_button_reload  = #fcaf3e
access_list_button_cleanup = #729fcf

# Coordinate indicator colors
access_list_coordinates_x = #ef2929
access_list_coordinates_y = #8ae234
access_list_coordinates_z = #729fcf

# If width or height are below the calculated minimum width or height,
# those get adjusted on-the-fly and these values are ignored.
access_list_width  =  8
access_list_height = 10

# The padding is used around the edges of the formspec and between
# individual elements. Input height includes text fields and buttons,
# and – even if not used for input – text labels.
access_list_padding      = 0.25
access_list_input_height = 0.5
access_list_button_width = 1.8

You can set the configuration options in minetest.conf or any other configuration file the server was started with (global). The mod also supports world-specific configuration located in ./worlds/worldname/_access_list.conf which takes precedence over the global settings.

Changing metadata key names

If you need to use the default metadata key names for other purposes you can chance the ones using by this mod. But keep in mind that all already placed nodes using the access list become unusable because the mod cannot find the already set metadata anymore.

access_list_meta_list = access_list:list
access_list_meta_owner = access_list:owner
access_list_meta_placer = access_list:placer

It is highly recommended to validate if this is really necessary. The key names are scoped to the mod name. Other mod’s names should not be used by arbitrary mods.

Translations

Missing your language? Feel free to add it!

Licensing

The mod is licensed under the MIT License. All examples Lua files are licensed under the BSD Zero Clause License.