API.md

   1 # Player Physics API Documentation
   2 This document explains how to use the Player Physics API as a developer.
   3
   4 ## Quick start
   5 Let's say you have a mod `example` and want to double the speed of the player (i.e. multiply it by a factor of 2), but you also don't want to break other mods that might touch the speed.
   6
   7 Previously, you might have written something like this:
   8
   9 `player:set_physics_override({speed=2})`
  10
  11 However, your mod broke down as soon the mod `example2` came along, which wanted to increase the speed by 50%. In the real game, the player speed randomly switched from 50% and 200% which was a very annoying bug.
  12
  13 In your `example` mod, you can replace the code with this:
  14
  15 `playerphysics.add_physics_factor(player, "speed", "my_double_speed", 2)`
  16
  17 Where `"my_double_speed` is an unique ID for your speed factor.
  18
  19 Now your `example` mod is interoperable! And now, of course, the `example2` mod has to be updated in a similar fashion.
  20
  21 ## Precondition
  22 There is only one precondition to using this mod, but it is important:
  23
  24 Mods *MUST NOT* call `set_physics_override` directly for numerical values. Instead, to modify player physics, all mods that touch player physics have to use this API.
  25
  26
  27
  28
  29 ## Functions
  30 ### `playerphysics.add_physics_factor(player, attribute, id, value)`
  31 Adds a factor for a player physic and updates the player physics immediately.
  32
  33 #### Parameters
  34 * `player`: Player object
  35 * `attribute`: Which of the physical attributes to change. Any of the numeric values of `set_physics_override` (e.g. `"speed"`, `"jump"`, `"gravity"`)
  36 * `id`: Unique identifier for this factor. Identifiers are stored on a per-player per-attribute type basis
  37 * `value`: The factor to add to the list of products
  38
  39 If a factor for the same player, attribute and `id` already existed, it will be overwritten.
  40
  41
  42
  43 ### `playerphysics.remove_physics_factor(player, attribute, id)`
  44 Removes the physics factor of the given ID and updates the player's physics.
  45
  46 #### Parameters
  47 Same as in `playerphysics.add_physics_factor`, except there is no `value` argument.
  48
  49
  50
  51 ### `playerphysics.get_physics_factor(player, attribute, id)`
  52 Returns the current physics factor of the given ID, if it exists.
  53 If the ID exists, returns a number. If it does not exist, returns nil.
  54
  55 Note a missing physics factor is mathematically equivalent to a factor of 1.
  56
  57 #### Parameters
  58 Same as in `playerphysics.add_physics_factor`, except there is no `value` argument.
  59
  60
  61
  62 ## Examples
  63 ### Speed changes
  64 Let's assume this mod is used by 3 different mods all trying to change the speed:
  65 Potions, Exhaustion and Electrocution.
  66 Here's what it could look like:
  67
  68 Potions mod:
  69 ```
  70 playerphysics.add_physics_factor(player, "speed", "run_potion", 2)
  71 ```
  72
  73 Exhaustion mod:
  74 ```
  75 playerphysics.add_physics_factor(player, "jump", "exhausted", 0.75)
  76 ```
  77
  78 Electrocution mod:
  79 ```
  80 playerphysics.add_physics_factor(player, "jump", "shocked", 0.9)
  81 ```
  82
  83 When the 3 mods have done their change, the real player speed is simply the product of all factors, that is:
  84
  85 2 * 0.75 * 0.9 = 1.35
  86
  87 The final player speed is thus 135%.
  88
  89 ### Speed changes, part 2
  90
  91 Let's take the example above.
  92 Now if the Electrocution mod is done with shocking the player, it just needs to call:
  93
  94 ```
  95 playerphysics.remove_physics_factor(player, "jump", "shocked")
  96 ```
  97
  98 The effect is now gone, so the new player speed will be:
  99
 100 2 * 0.75 = 1.5
 101
 102 ### Sleeping
 103 To simulate sleeping by preventing all player movement, this can be done with this easy trick:
 104
 105 ```
 106 playerphysics.add_physics_factor(player, "speed", "sleeping", 0)
 107 playerphysics.add_physics_factor(player, "jump", "sleeping", 0)
 108 ```
 109
 110 This works regardless of the other factors because 0 times anything equals 0.