Privileges: create chapter

_data/links.yml

@@ -35,40 +35,44 @@
 
 - hr: true
 
-- title: Chat and Commands
+- title: Privileges
   num:   8
+  link:  chapters/privileges.html
+
+- title: Chat and Commands
+  num:   9
   link:  chapters/chat.html
 
 - title: Player Physics
-  num:   9
+  num:   10
   link:  chapters/player_physics.html
 
 - title: Formspecs
-  num:   10
+  num:   11
   link:  chapters/formspecs.html
 
 - title: HUD
-  num:   11
+  num:   12
   link:  chapters/hud.html
 
 - hr: true
 
 - title: ItemStacks
-  num:   12
+  num:   13
   link:  chapters/itemstacks.html
 
 - title: Inventories
-  num:   13
+  num:   14
   link:  chapters/inventories.html
 
 - hr: true
 
 - title: Releasing a Mod
-  num: 14
+  num: 15
   link: chapters/releasing.html
 
 - title: Read More
-  num: 15
+  num: 16
   link: chapters/readmore.html
 
 - hr: true

chapters/chat.md

@@ -48,9 +48,8 @@ minetest.chat_send_player("player1", "This is a server message", true)
 minetest.chat_send_player("player1", "This is a server message", false)
 {% endhighlight %}
 
-The boolean at the end has been
+The boolean at is no longer used, and has no affect
-[depreciated](https://github.com/minetest/minetest/commit/9a3b7715e2c2390a3a549d4e105ed8c18defb228)
+<sup>[[commit]](https://github.com/minetest/minetest/commit/9a3b7715e2c2390a3a549d4e105ed8c18defb228)</sup>.
-so the third parameter is ignored and has no effect.
 
 
 ## Chat commands
@@ -78,7 +77,7 @@ privs = {
 },
 {% endhighlight %}
 
-This makes it so that only players with the `interact` privilege can run the
+This makes it so that only players with the `interact` [privilege](privileges.html) can run the
 command. Other players will see an error message informing them which
 privilege they're missing.
 

chapters/privileges.md

@@ -0,0 +1,158 @@
+---
+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
+
+<div class="notice">
+	<h2>Workaround / PR pending</h2>
+
+	This is a workaround for a missing feature.
+	I have submitted a
+	<a href="https://github.com/minetest/minetest/pull/3976">pull request / patch</a>
+	to make it so you don't need to edit builtin to add a priv to basic_privs.
+</div>
+
+To allow people with basic_privs to grant and revoke your priv, you'll
+need to edit [builtin/game/chatcommands.lua](https://github.com/minetest/minetest/blob/master/builtin/game/chatcommands.lua#L164-L252):
+
+In both grant and revoke, change the following if statement:
+
+{% highlight lua %}
+if priv ~= "interact" and priv ~= "shout" and
+		not core.check_player_privs(name, {privs=true}) then
+	return false, "Your privileges are insufficient."
+end
+{% endhighlight %}
+
+For example, to add vote:
+
+{% highlight lua %}
+if priv ~= "interact" and priv ~= "shout" and priv ~= "vote" and
+		not core.check_player_privs(name, {privs=true}) then
+	return false, "Your privileges are insufficient."
+end
+{% endhighlight %}