mods/emote/README.md

   1 Emote - a player emote API
   2 ##########################
   3
   4 This mod aims to provide an API for player model animations such
   5 as sitting, waving, lying down, as well as some providing chat
   6 commands for the player to use these "emotes".
   7
   8 ## API
   9
  10 The emote API consists of several functions that allow mods to
  11 manipulate the emote state of each player.
  12
  13 `bool emote.start(player, emotestring)`
  14
  15 Start the named emote for the named player. Returns false if
  16 the emote is unknown or the emote could not be started. Returns
  17 true otherwise.
  18
  19 `emote.stop(player)`
  20
  21 Stops any emote for the named player.
  22
  23 `emote.list()`
  24
  25 Lists known emotestring values.
  26
  27 `emote.attach_to_node(player, pos, locked)`
  28
  29 Attach the player to the node at pos. The attachment will be made using the
  30 parameters provided in the `emote` table in the nodedef:
  31 ```
  32 nodedef.emote = {
  33         emotestring = "sit",
  34         eye_offset = {x = 0, y = 0, z = 0},
  35         player_offset = {x = 0, y = 1/2, z = 0},
  36         look_horizontal_offset = 0,
  37 }
  38 ```
  39
  40 if `locked` is `true`, then the player is fixed to the node and can only
  41 move until he presses `jump`. While sitting the player can look around but
  42 his character does not turn.
  43
  44 The player offset vector will be rotated to account for the node facedir.
  45
  46 ## Commands
  47
  48 The emotes are all usable by players using chat commands:
  49 /lay, /sleep, /sit, /point, /freeze, etc.
  50
  51 ## TODO
  52
  53 The API currently only allows unattached emotes (ones where the
  54 player can just move and cancel the emote). The API needs to
  55 provide an additional function to allow attached emotes with
  56 rotation and offset so that players can easily sit on chairs,
  57 lie on beds or emote-interact with machines (e.g. point emote
  58 when interacting with a node).
  59
  60 ## Can I sit on stair blocks with this?
  61
  62 The patch file `sit-on-stairs.patch` in this project is an example
  63 patch for minetest_game that will allow a player to right-click stair
  64 nodes and sit on them as if they were seats.
  65
  66 ## License
  67
  68 LGPL-2.1