README.md

   1 # Player Physics API
   2
   3 Version: 1.1.0
   4
   5 This mod makes it possible for multiple mods to modify player physics (speed, jumping strength, gravity) without conflict.
   6
   7 ## Introduction
   8 ### For players
   9 Mods and games in Minetest can set physical attributes of players, such as speed and jump strength. For example, player speed could be set to 200%. But the way this works makes it difficult for multiple mods to *modify* physical attributes without leading to conflicts, problems and hilarious bugs, like speed that changes often to nonsense values.
  10
  11 The Player Physics API aims to resolve this conflict by providing a “common ground” for mods to work together in this regard.
  12
  13 This mod does nothing on its own, you will only need to install it as dependency of other mods.
  14
  15 When you browse for mods that somehow mess with player physics (namely: speed, jump strength or gravity) and want to use more than one of them, check out if they support the Player Physics API. If they don't, it's very likely these mods will break as soon you activate more than one of them, for example, if two mods try to set the player speed. If you found such a “hilarious bug”, please report it to the developers of the mods (or games) and point them to the Player Physics API.
  16
  17 Of course, not all mods need the Player Physics API. Mods that don't touch player physics at all won't need this mod.
  18
  19 The rest of this document is directed at developers.
  20
  21 ### For developers
  22 The function `set_physics_override` from the Minetest Lua API allows mod authors to override physical attributes of players, such as speed or jump strength.
  23
  24 This function works fine as long there is only one mod that sets a particular physical attribute at a time. However, as soon as at least two different mods (that do not know each other) try to change the same player physics attribute using only this function, there will be conflicts as each mod will undo the change of the other mod, as the function sets a raw value. A classic race condition occurs. This is the case because the mods fail to communicate with each other.
  25
  26 This mod solves the problem of conflicts. It bans the concept of “setting the raw value directly” and replaces it with the concept of factors that mods can add and remove for each attribute. The real physical player attribute will be the product of all active factors.
  27
  28 See `API.md` for the API documentation.
  29
  30 ## License
  31 This mod is free software, released under the MIT License.