mods/PLAYER/mcl_hunger/API.md

   1 # API information (WIP)
   2 This API information is not complete yet.
   3 The mod API is still pretty much unofficial; this mod is mostly seen
   4 as standalone for now.
   5
   6 This may change in the future development of MineClone 2. Hopefully.
   7
   8 ## Mod state
   9 The hunger mechanic is disabled when damage is disabled
  10 (setting `enable_damage=false`).
  11 You can check the hunger state with `mcl_hunger.active`. If it's true,
  12 then hunger is active.
  13
  14 If the hunger is disabled, most of the functions are no-ops or return
  15 default values.
  16
  17 ## Player values
  18 ### Hunger level
  19 The hunger level of the player is a whole number between 0 and 20 inclusive.
  20 0 is starving and 20 is full. The hunger level is represented in
  21 the HUD by a statbar with 20 half-icons.
  22
  23 ### Saturation
  24 To be written ...
  25
  26 ### Exhaustion
  27 To be written ...
  28
  29 ## Functions
  30 This API documentation is not complete yet, more documentation will
  31 come.
  32
  33 ### `mcl_hunger.get_hunger(player)`
  34 Returns the current hunger level of `player` (ObjectRef).
  35
  36 ### `mcl_hunger.set_hunger(player, hunger)`
  37 Sets the hunger level of `player` (ObjectRef) to `hunger` immediately.
  38 `hunger` ***must*** be between 0 and 20 inclusive.
  39
  40 ### `mcl_hunger.exhaust(player, exhaust)`
  41 Increase exhaustion of player by `exhaust`.
  42
  43 ### `mcl_hunger.stop_poison(player)`
  44 Immediately stops food poisoning for player.
  45
  46 ### More functions ...
  47 There are more functions (of less importance) available, see `api.lua`.
  48
  49 ## Groups
  50 Items in group `food=3` will make a drinking sound and no particles.
  51 Items in group `food` with any other rating will make an eating sound and particles,
  52 based on the inventory image or wield image (whatever is available first).
  53
  54 ## Suppressing food particles
  55 Normally, all food items considered food (not drinks) make food particles.
  56 You can suppress the food particles by adding the field
  57 `_food_particles=false` to the item definition.