Advanced Usage¶

Cooldowns¶

Base cooldowns are configured with settings.cooldown in each Emote file.

{
  "settings": {
    "cooldown": "5s"
  }
}

When playing a Sequence, only the Sequence's own settings.cooldown applies. Cooldowns of referenced Animations are not added.

Permission groups can adjust that base cooldown with cooldown in emotes.json:

{
  "permissions": [
    {
      "permission": "emote.vip",
      "emotes": ["*"],
      "cooldown": "x0.5"
    },
    {
      "permission": "emote.default",
      "emotes": ["*"],
      "cooldown": "5s"
    }
  ]
}

A Minecraft time value such as 5s is subtracted from the Emote's base cooldown. A value beginning with x multiplies it instead: x0.5 halves the cooldown, while x2 doubles it. The final cooldown cannot be less than zero.

Permission entries are checked from top to bottom. The first entry that matches the Emote, belongs to the player, and defines cooldown is used. Entries without cooldown are skipped, and the base cooldown is unchanged when no matching entry defines one.

Time units

Emote uses Minecraft time format. 1s equals 20t.

s: seconds
t or omitted: ticks
d: Minecraft days

Idle Emotes¶

Idle emotes play automatically after a specified time since the player's last action. Add idle to a permission entry in emotes.json.

{
  "permission": "emote.default",
  "emotes": ["emote:hello", "emote:backflip"],
  "idle": {
    "delay": "300s",
    "emote": ["sit:idle.sit"]
  }
}

To choose evenly among several emotes, list only their IDs:

"emote": ["sit:idle.sit", "handstand:idle.handstand"]

An entry that is a valid emote ID matches literally. Any other entry is a full Java regular expression, so an idle rule can select every currently available emote with a matching ID:

"emote": [".*:idle\\..*"]

Regular-expression entries can be used only with equal selection. They cannot be combined with explicit weights.

For weighted selection, alternate IDs and integer weights whose total must equal 100:

"emote": ["sit:idle.sit", 70, "handstand:idle.handstand", 30]

If a player has multiple permissions, entries are checked from top to bottom in emotes.json, and the first allowed entry with idle is used. Place higher-priority groups first.

"permissions": [
  {
    "permission": "emote.vip",
    "emotes": ["emote:(dance|cheer|clap)"],
    "idle": {
      "delay": "120s",
      "emote": ["handstand:idle.handstand"]
    }
  },
  {
    "permission": "emote.default",
    "emotes": ["emote:hello", "emote:backflip"],
    "idle": {
      "delay": "300s",
      "emote": ["sit:idle.sit"]
    }
  }
]

An idle emote does not start while another emote is playing. A failed attempt is retried after one second. When several candidates are available, Emote avoids selecting the most recently played emote twice in a row when possible.

Marker Mannequin¶

Marker mannequins are used to play emotes at a fixed position in the world without attaching them to a player.

They are created by summoning a Minecraft marker entity with the emote data:

summon minecraft:marker ~ ~ ~ {"data":{"emote":"emote id","emote_skin":"player name"}}

emote specifies the Emote ID to play, and emote_skin specifies the player name whose skin is used for the mannequin.

The mannequin remains at the marker's position and plays the specified emote independently of any player.

Sequences¶

A Sequence connects multiple Animations in order and presents them to the player as one emote. Server operators must install both the Sequence JSON and every Animation JSON it references.

Example file layout¶

config/emote/emote/sit/
├── sit.idle_butterfly.json
├── sit.idle_flower.json
├── sit.idle_sky.json
├── sit.sit_down.json
├── sit.stand_up1.json
├── sit.stand_up2.json
└── sit.sit.json

sit.sit.json:

{
  "type": "sequence",
  "schema_version": 4,
  "id": "sit:idle.sit",
  "metadata": {
    "name": "Sit",
    "description": "Sit down and relax."
  },
  "settings": {
    "cooldown": "0t",
    "player": {
      "hidden": true,
      "stop_conditions": {
        "movement_distance": 0.1,
        "jump": true,
        "submerge": true,
        "ride": true,
        "damage": true,
        "attack": true,
        "game_mode_change": true
      }
    }
  },
  "steps": [
    {"emote": "sit:sit_down"},
    {
      "emote": ["sit:idle_sky", 40, "sit:idle_butterfly", 35, "sit:idle_flower", 25],
      "transition": "2t",
      "repeat": 2
    },
    {"emote": ["sit:stand_up1", 60, "sit:stand_up2", 40]}
  ]
}

Intermediate Animations referenced by a Sequence are usually hidden from direct selection:

{
  "settings": {
    "standalone": false
  }
}

Verifying the installation¶

Place all JSON files under emote/ on the same server.
After reloading the files, use /emote list to confirm that the Sequence and every referenced Animation loaded.
Run /emote play sit:idle.sit with normal player permissions.

If the Sequence does not load, check the server log for missing Animation IDs, incompatible nodes, unsupported playback modes, or invalid wait-step messages.

To create random selection, waits, or repeat control, see the Sequence format specification.