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 ## Examples
  50 ### Speed changes
  51 Let's assume this mod is used by 3 different mods all trying to change the speed:
  52 Potions, Exhaustion and Electrocution.
  53 Here's what it could look like:
  54
  55 Potions mod:
  56 ```
  57 playerphysics.add_physics_factor(player, "speed", "run_potion", 2)
  58 ```
  59
  60 Exhaustion mod:
  61 ```
  62 playerphysics.add_physics_factor(player, "jump", "exhausted", 0.75)
  63 ```
  64
  65 Electrocution mod:
  66 ```
  67 playerphysics.add_physics_factor(player, "jump", "shocked", 0.9)
  68 ```
  69
  70 When the 3 mods have done their change, the real player speed is simply the product of all factors, that is:
  71
  72 2 * 0.75 * 0.9 = 1.35
  73
  74 The final player speed is thus 135%.
  75
  76 ### Speed changes, part 2
  77
  78 Let's take the example above.
  79 Now if the Electrocution mod is done with shocking the player, it just needs to call:
  80
  81 ```
  82 playerphysics.remove_physics_factor(player, "jump", "shocked")
  83 ```
  84
  85 The effect is now gone, so the new player speed will be:
  86
  87 2 * 0.75 = 1.5
  88
  89 ### Sleeping
  90 To simulate sleeping by preventing all player movement, this can be done with this easy trick:
  91
  92 ```
  93 playerphysics.add_physics_factor(player, "speed", "sleeping", 0)
  94 playerphysics.add_physics_factor(player, "jump", "sleeping", 0)
  95 ```
  96
  97 This works regardless of the other factors because 0 times anything equals 0.