README.md

   1 # Player Effects
   2 ## Summary
   3 This is an framework for assigning temporary status effects to players. This mod is aimed to modders and maybe interested people. This framework is a work in progress and not finished.
   4
   5 ## Profile
   6 * Name: Player Effects
   7 * Short name: `playereffects`
   8 * Current version: 1.0.0 (This is a [SemVer](http://semver.org/).)
   9 * Dependencies: None!
  10 * Discussion page: [here](https://forum.minetest.net/viewtopic.php?f=11&t=9689)
  11
  12 ## Information for players
  13 This mod alone is not aimed directly at players. Briefly, the point of this mod is to help other mods to implement temporary status effects for players in a clean and consistant way.
  14 Here is the information which may be relevant to you: Your current status effects are shown on the HUD on the right side, along with a timer which shows the time until the effect gets disabled. It is possible for the server to disable this feature entirely. Some status effects may also be hidden and are never exposed to the HUD.
  15
  16 You only have to install this mod iff you have a mod which implements Player Effects. Here is a list of known mods which do:
  17
  18 * Magic Beans—Wuzzy’s Fork [`magicbeans_w`]
  19
  20 ## Information for server operators
  21 By default, this mod stores the effects into the file `playereffects.mt` in the current world path every 10 seconds. On a regular server shutdown, this file is also written to. The data in this file is read when the mod is started.
  22
  23 It is save to delete `playereffects.mt` when the mod does currently not run. This simply erases all active and inactive effects when the server starts again.
  24
  25 You can disable the automatic saving in `settings.lua`.
  26
  27 ### Configuration
  28 Player Effects can be configured. Just edit the file `settings.lua`. You find everything you need to know in that file. Be careful to not delete the lines, just edit them.
  29
  30 ## Information for modders
  31 This is a framework for other mods to depend on. It provides means to define, apply and remove temporary status effects to players in a (hopefully) unobstrusive way.
  32 A status effect is an effect for a player which changes some property of the player. This property can be practically everything. Currently, the framework supports one kind of effect, which I call “exclusive effects”. For each property (speed, gravity, whatver), there can be only one effect in place at the same time. Here are some examples for possible status effects:
  33
  34 * high walking speed (`speed` property)
  35 * high jump height (`jump` property)
  36 * low player gravity (`gravity` property)
  37 * high player gravity (`gravity` property)
  38 * having the X privilege granted (binary “do I have the property?” property) (yes, this is weird, but it works!)
  39
  40 The framework aims to provide means to define effect types and to apply and cancel effects to players. The framework aims to be a stable foundation stone. This means it needs a lot of testing.
  41
  42 ## Known bugs
  43 ### Effect timers don’t stop when game gets paused
  44 When you paused the game in singleplayer mode, the effect timers just continue as if nothing happened. Of course, all effect timers should be stopped while the game is paused, like everything else. Apparently this bug cannot be fixed with the current Lua API.
  45
  46 ## API documentation
  47 ### Data types
  48 #### Effect type (`effect_type`)
  49 An effect type is a description of what is later to be concretely applied as an effect to a player. An effect type, however, is *not* assigned to a player.
  50
  51 `effect_type` is a table with these fields:
  52
  53 * `description`: Human-readable short description of the effect. Will be exposed to the HUD, iff `hidden` is `false`.
  54 * `groups`: A table of groups to which this effect type belongs to.
  55 * `apply`: Function to be called when effect is applied. See `playereffects.register_effect_type`.
  56 * `cancel`: Function to be called when effect is cancelled. See `playereffects.register_effect_type`.
  57 * `icon`: This is optional. It can be the file name of a texture. Should have a size of 16px×16px. Will be exposed to the HUD, iff `hidden` is `false`.
  58 * `hidden`: Iff this is false, it will not be exposed to the HUD when this effect is active.
  59 * `cancel_on_death`: Iff this is true, the effect will be cancelled automatically when the player dies.
  60
  61 Normally you don’t need to read or edit fields of this table. Use `playereffects.register_effect_type` to add a new effect type to Player Effects.
  62
  63 #### Effect group
  64 An effect group is basically a concept. Any effect type can be member of any number of effect groups. The main point of effect groups is to find effects which affect the same property. For example, an effect which makes you faster and another effect which makes you slower both affect the same property: speed. The group for that then would be the string `"speed"`. See also `examples.lua`, which includes the effects `high_speed` and `low_speed`.
  65
  66 Currently, the main rule of Player Effects requires that there can only be one effect in place. Don’t worry, Player Effects already does that job for you. Back to the example: it is possible to be fast and it is possible to be slow. But it is not possible to be fast `and` slow at the same time. Player Effects ensures that by cancelling all conflicting concepts before applying a new one.
  67
  68 The concept of groups may be changed or extended in the future.
  69
  70 You can invent effect groups (like the groups in Minetest) on the fly. A group is just a string. Practically, you should use groups which other people use.
  71
  72 #### Effect (`effect`)
  73 An effect is an current change of a player property (like speed, jump height, and so on). It is the realization of an effect type. All effects are temporary.
  74
  75 `effect` is a table with the following modding-relevant fields:
  76
  77 * `playername`: The name of the player to which the effect belongs to.
  78 * `effect_id`: A globally unique identifier of the effect. It is a number and assigned automatically by Player Effects.
  79 * `effect_type_id`: The identifier of the effect’s effect type. It is a string and assigned by `playereffects.register_effect_type`.
  80 * `metadata`: An optional field which may contain a table with additional, modder-defined data to be “remembered” for later. The `apply` callback can set this field.
  81
  82 Internally, Player Effects also uses these fields:
  83
  84 * `start_time`: The operating system time (from `os.time()`) of when the effect has been started.
  85 * `time_left`: The number of seconds left before the effect runs out. This number is only set when the effect starts or the effect is unfrozen because i.e. a player re-joins. You can’t use this field to blindly get the remaining time of the effect.
  86
  87 You should normally not need to care about these internally used fields.
  88
  89
  90 ### Functions
  91 #### `playereffects.register_effect_type(effect_type_id, description, icon, groups, apply, cancel, hidden, cancel_on_death)`
  92 Adds a new effect type for the Player Effects mods, so it can be later be applied to players.
  93
  94 ##### Parameters
  95 * `effect_type_id` is the identifier (a string) which is internally used by the mod. Later known as `effect_type_id`. You may choose the identifier at will, but please use only alphanumeric ASCII characters. The identifier must be unique along all mods.
  96 * `description` is the text which is exposed to the HUD and visible to the player.
  97 * `icon`: This is optional an can be `nil`. It can be the file name of a texture. Should have a size of 16px×16px. In this case, this is the icon for the HUD. Basically this is just eye-candy. If this is `nil`, no icon is shown. The icon will be exposed to the HUD, iff `hidden` is `false`.
  98 * `groups` is a table of strings to which the effect type is assigned to.
  99 * `apply`: See below.
 100 * `cancel`: See below.
 101 * `hidden` is an optional boolean value. Iff `true`, the effect description and icon will not be exposed to the player HUD. Otherwise, the effect is exposed. Default: `false`
 102 * `cancel_on_death` is an optional boolean value. Iff true, the effect will be cancelled automatically when the player dies. Default: `true`.
 103
 104
 105 ###### `apply` function
 106 The `apply` function is a callback function which is called by Player Effects. Here the modder can put all the gameplay-relevant code.
 107
 108 `apply` takes a player object as its only argument. This is the player to which the effect is applied to.
 109
 110 The function may return a table. This table will be added as the field `metadata` to the resulting `effect`.
 111
 112 The function may return `false`. This is used to tell Player Effects that the effect could, for whatever reason, not be successfully applied. Currently, this feature is experimental and possibly broken.
 113
 114 The function may also return just `nil` on a normal success without metadata.
 115
 116 ###### `cancel` function
 117 The `cancel` function is called by Player Effects when the effect is to be cancelled. Here the modder can do all the code which is needed to revert the changes an earlier `apply` call made.
 118
 119 `cancel` takes an `effect` as its first argument and a player object as its second argument. Remember, this `effect` may also contain a field called `metadata`, which may have been added by an earlier `apply` call. `player` is the player to which the effect is/was applied. This argument is just there for convenience reasons.
 120
 121 Player Effects does not care about the return value of this function.
 122
 123 ##### Return value
 124 Always `nil`.
 125
 126 #### `playereffects.apply_effect_type(effect_type_id, duration, player)`
 127 Attempts to apply a new effect of a certain type for a certain duration to a certain player. This function can fail, although this should rarely happen.
 128
 129 ##### Parameters
 130 * `effect_type_id`: The identifier of the effect type. This is the name which was used in `playereffects.register_effect_type` and always a string.
 131 * `duration`: How long the effect. Please use only positive values and only integers.
 132 * `player`: The player object to which the new effect should be applied to.
 133
 134 ##### Return value
 135 The function either returns `false` or a number. Iff the function returns `false`, the effect was not successfully applied. The function may return `false` on these occasions:
 136
 137 * `player` is not a valid player object
 138 * The `apply` function of the effect type returned `false`
 139
 140 On success, the function returns a number. This number is the effect ID of the effect which has been just created. This effect ID can be used later, for `playereffects.cancel_effect`, for example.
 141
 142 #### `playereffects.cancel_effect(effect_id)`
 143 Cancels a single effect.
 144
 145 ##### Parameter
 146 * `effect_id`: The effect ID of the effect which shall be cancelled.
 147
 148 ##### Return value
 149 Always `nil`.
 150
 151 #### `playereffects.cancel_effect_group(groupname, playername)`
 152 Cancels all a player’s effects which belong to a certain group.
 153
 154 ##### Parameters
 155 * `groupname`: The name of the effect group (string) of which all active effects of the player shall be cancelled.
 156 * `playername`: The name of the player to which the effects which are about to be cancelled belong to.
 157
 158 ##### Return value
 159 Always `nil`.
 160
 161 #### `playereffects.cancel_effect_type(effect_type_id, cancel_all, playername)`
 162 Cancels one or all player effect with a certain effect type
 163 Careful! This function has *not* been tested yet!
 164
 165 ##### Parameters
 166 * `effect_type_id`: Identifier of the effect type.
 167 * `cancel_all`: Iff true, cancels all active effects with this effect type
 168 * `playername`: Name of the player to which the effects belong to
 169
 170 ##### Return value
 171 Always `nil`.
 172
 173 #### `playereffects.get_remaining_effect_time(effect_id)`
 174 Returns the remaining time of an effect.
 175
 176 ##### Parameter
 177 * `effect_id`: The effect identifier of the effect in question
 178
 179 ##### Return value
 180 Iff the effect exists, the remaining effect time is returned in full seconds. Iff the effect does not exist, `nil` is returned.
 181
 182 #### `playereffects.get_player_effects(playername)`
 183 Returns all active effects of a player.
 184
 185 ##### Parameter
 186 `playername`: The name of the player from which the effects are requested.
 187
 188 ##### Return value
 189 A table of all `effect`s which belong to the player. If the player does not exist, this function returns an empty table.
 190
 191 ## Examples
 192 This mod comes with extensive examples. The examples are currently enabled by default and will be disabled from the first stable release. See `examples.lua` to find out how they are programmed. The examples are only for demonstration purposes. They are not intended to be used in an actual game.
 193
 194 ### Chat commands
 195 The examples are mainly accessible with chat commands. Since this is just an example, everyone can use these examples.
 196
 197 #### Apply effect
 198 These commands apply (or try to) apply an effect to you. You will get a response in the chat which give you the `effect_id` on success. On failure, the example will tell you that it failed.
 199
 200 * `fast`: Makes you faster for 10 seconds.
 201 * `slow`: Makes you slower for 120s.
 202 * `hfast`: Makes you faster for 10s. This is a hidden effect and is not exposed to the HUD.
 203 * `highjump`: Increases your jump height for 20s.
 204 * `fly`: Gives you the `fly` privilege for a minute. You keep the privilege even when you die. Better don’t mess around with this privilege manually when you use this.
 205 * `blind`: Tints the whole screen black for 5 seconds. This is highly experimental and will be drawn over many existing HUD elements. In other words, prepare your HUD to be messed up.
 206 * `null`: Tries to apply an effect which always fails. This demonstrates the failure of effects.
 207
 208 #### Cancel effects
 209 * `cancelall`: Cancels all your active effects.
 210
 211 #### Testing
 212 * `stresstest [number]`: Applies `number` dummy effects which don’t do anything to you. Iff omitted, `number` is assumed to be 100. This command is there to test the performance of this mod for absurdly large effect numbers.