minetest_modding_book/en/chapters/privileges.md

---
title: Privileges
layout: default
root: ../../
---

## Introduction

Privileges allow server owners to grant or revoke the right to do certain
actions.

* When should a priv be used?
* Checking for privileges
* Getting and Setting

## When should a priv be used?

A privilege should give a player **the right to do something**.
They are **not for indicating class or status**.

The main admin of a server (the name set by the `name` setting) has all privileges
given to them.

**Good:**

* interact
* shout
* noclip
* fly
* kick
* ban
* vote
* worldedit
* area_admin - admin functions of one mod is ok

**Bad:**

* moderator
* admin
* elf
* dwarf

## Declaring a privilege

{% highlight lua %}
minetest.register_privilege("vote", {
    description = "Can vote on issues",
    give_to_singleplayer = true
})
{% endhighlight %}

If `give_to_singleplayer` is true, then you can remove it as that's the default
value when not specified:

{% highlight lua %}
minetest.register_privilege("vote", {
    description = "Can vote on issues"
})
{% endhighlight %}

## Checking for privileges

There is a quicker way of checking that a player has all the required privileges:

{% highlight lua %}
local has, missing = minetest.check_player_privs(player_or_name,  {
    interact = true,
    vote = true })
{% endhighlight %}

`has` is true if the player has all the privileges needed.\\
If `has` is false, then `missing` will contain a dictionary
of missing privileges<sup>[checking needed]</sup>.

{% highlight lua %}
if minetest.check_player_privs(name, {interact=true, vote=true}) then
    print("Player has all privs!")
else
    print("Player is missing some privs!")
end

local has, missing = minetest.check_player_privs(name, {
    interact = true,
    vote = true })
if has then
    print("Player has all privs!")
else
    print("Player is missing privs: " .. dump(missing))
end
{% endhighlight %}

## Getting and Setting

You can get a table containing a player's privileges using `minetest.get_player_privs`:

{% highlight lua %}
local privs = minetest.get_player_privs(name)
print(dump(privs))
{% endhighlight %}

This works whether or not a player is logged in.\\
Running that example may give the following:

{% highlight lua %}
{
    fly = true,
    interact = true,
    shout = true
}
{% endhighlight %}

To set a player's privs, you use `minetest.set_player_privs`:

{% highlight lua %}
minetest.set_player_privs(name, {
    interact = true,
    shout = true })
{% endhighlight %}

To grant a player some privs, you would use a mixture of those two:

{% highlight lua %}
local privs = minetest.get_player_privs(name)
privs.vote = true
minetest.set_player_privs(name, privs)
{% endhighlight %}

## Adding privileges to basic_privs

`basic_privs` is a privilege that allows a player to only grant certain privileges.
It's common to give this privilege to moderators so they can grant and revoke
interact and shout, but can't give themselves or other players any bigger
privileges such as giveme and server.

To add a privilege to basic_privs, you need to change the basic_privs setting
to include any privs you wish.

By default basic_privs has the following value:

    basic_privs = interact, shout

And then you can add vote as so:

    basic_privs = interact, shout, vote