From 53fe0ffaa9904f8830a951ac89c36b46c1afa4ad Mon Sep 17 00:00:00 2001
From: Wuzzy <Wuzzy@disroot.org>
Date: Thu, 19 May 2022 22:14:07 +0200
Subject: [PATCH] Document API of rp_player_effects

---
 mods/rp_player_effects/API.md     | 63 +++++++++++++++++++++++++++++++
 mods/rp_player_effects/README.txt |  6 ++-
 mods/rp_player_effects/init.lua   |  8 ++--
 3 files changed, 71 insertions(+), 6 deletions(-)
 create mode 100644 mods/rp_player_effects/API.md

diff --git a/mods/rp_player_effects/API.md b/mods/rp_player_effects/API.md
new file mode 100644
index 00000000..ac0ab119
--- /dev/null
+++ b/mods/rp_player_effects/API.md
@@ -0,0 +1,63 @@
+# API documentation for `rp_player_effects`
+
+This mod is a safe way to change player physics while keeping
+compatibility with other mods.
+
+Effects change the player physics (walk speed/jump height/gravity, using
+`player:set_physics_override` internally).
+Each player can have any number of effects active at a time.
+
+If two effects that affect the same physics attribute (like speed),
+the values of all effects are multiplied.
+
+E.g. if player X has two effects `sluggish` with `speed=0.3`
+and `superspeed` with `speed=2.0`, then the effective player
+speed will be `0.3 * 2.0 = 0.6` times of the normal speed.
+
+**IMPORTANT:** In order for this mod to work, it is *forbidden*
+for all mods except `rp_player_effects` to call
+`player:set_physics_override` directly.
+
+## Functions
+### `player_effects.register_effect(ename, def)`
+
+Adds a new effect that players can have.
+
+* `ename`: Effect identifier (not translatable!)
+* `def`: Effect definition. This is a table:
+    * `title`: Player-facing effect name
+    * `description`: Short (!) player-facing effect description
+    * `duration`: Effect duration in seconds. If this time is over, the effect will be removed. Negative value = infinite. (default: 1)
+    * `physics`: Table of player physics overrides. Supports `speed`, `jump` and `gravity`, same as in `player:set_physics_override`
+    * `icon`: Optional effect icon for the HUD
+    * `save`: If true, effect will be preserved on server shutdown.
+              If false, effect will be gone on server shutdown. (default: true)
+
+### `player_effects.get_registered_effect(ename)`
+
+Returns the definition of the effect with the given identifier `ename`.
+The definition is the same as in `player_effects.register_effect`.
+
+### `player_effects.apply_effect(player, ename)`
+
+Apply effect `ename` to player `player`. This applies the physics modifiers to
+the player.
+The effect will last for the duration as specified in the effect definition.
+If the duration is infinite, the effect can be manually removed by
+`player_effects.remove_effect`.
+
+### `player_effects.remove_effect(player, ename)`
+
+Instantly removes the effect `ename` from the player `player`.
+
+This works for any effect.
+
+### `player_effects.clear_effects(player)`
+
+Removes all effects from `player`.
+
+Be careful with this function as you might accidentally remove effects
+from other mods you did not meant to remove.
+
+Only call this function if you're absolutely sure.
+
diff --git a/mods/rp_player_effects/README.txt b/mods/rp_player_effects/README.txt
index 48c4f070..17416b1b 100644
--- a/mods/rp_player_effects/README.txt
+++ b/mods/rp_player_effects/README.txt
@@ -2,6 +2,8 @@ Player effects mod
 ==================
 By Kaadmy, for Pixture
 
-Adds functions to handle multiple physics overrides at the same time
+Adds functions to handle multiple physics overrides at the same time.
 
-Source license: LGPLv2.1
+Developers: See `API.md` for API documentation.
+
+Source code license: LGPLv2.1
diff --git a/mods/rp_player_effects/init.lua b/mods/rp_player_effects/init.lua
index 90d8c379..8302b6cb 100644
--- a/mods/rp_player_effects/init.lua
+++ b/mods/rp_player_effects/init.lua
@@ -67,10 +67,10 @@ local function display_effect_icons(player)
    end
 end
 
-function player_effects.register_effect(name, def)
+function player_effects.register_effect(ename, def)
    local rd = {
-      title = def.title or name, -- good-looking name of the effect
-      description = def.description or S("The @1 effect", name), -- description of what the effect does
+      title = def.title or ename, -- good-looking name of the effect
+      description = def.description or S("The @1 effect", ename), -- description of what the effect does
       duration = def.duration or 1, -- how long the effect lasts, <0 is infinite and has to be disabled manually
       physics = def.physics or {}, -- physics overrides for the player
       icon = def.icon, -- effect icon for HUD (optional)
@@ -80,7 +80,7 @@ function player_effects.register_effect(name, def)
       rd.save = true
    end
 
-   player_effects.registered_effects[name] = rd
+   player_effects.registered_effects[ename] = rd
 end
 
 function player_effects.get_registered_effect(ename)