Emote

Special thanks to Popular Vibe for allowing me to use their animation!

Emote is a server-side emote player that uses Minecraft display entities to play animations created with BD Engine and Animated Java.

The mod can be installed on the server only. Installing it on the client also adds an emote wheel and automatic third-person view while an emote is playing.

Compatible emotes can use the playing player’s skin. The web converter exports BD Engine projects, BD Engine datapacks, and Animated Java blueprints as Emote animation JSON files.

Want to share your emotes? Join the Discord server and share them with the community!

User Commands

Admin Commands

Server Configuration

The following files and directories are created in config/emote when the server starts for the first time:

config/emote/
├── config.json
├── emotes.json
└── animations/

config.json

{
  "schema_version": 1,
  "menu_page_size": 6,
  "mineskin_api_key": "",
  "mineskin_poll_interval_seconds": 3,
  "mineskin_cache_retention_days": 30,
  "mineskin_cache_max_mib": 256
}

Player Skin Support

To apply the playing player’s skin to compatible emotes, set mineskin_api_key in config/emote/config.json to an API key from MineSkin.

Skin parts and their order can be assigned in the web converter. If no API key is configured or MineSkin is unavailable, the textures stored in the animation JSON are used instead.

emotes.json

Controls emote availability and play permissions.

{
  "disabled": [
    "example:disabled"
  ],
  "permissions": [
    {
      "permission": "emote.vip",
      "emotes": [
        "example:dance",
        "example:cry"
      ],
      "idle": {
        "delay_seconds": 600,
        "emote": [
          "example:dance",
          "example:cry"
        ]
      }
    },
    {
      "permission": "emote.default",
      "emotes": [
        "example:hello",
        "example:yes",
        "example:no"
      ]
    },
    {
      "permission": "emote.admin",
      "emotes": [
        "*"
      ]
    }
  ]
}

• disabled contains the exact IDs of emotes that should not be loaded.
• permissions preserves the listed order, which determines idle emote selection.
• permission is the permission node for the entry. emote.default is granted to every player by default.
• emotes contains the emotes granted by the permission.
• idle is optional. The first matching permission entry with idle plays a randomly selected emote after delay_seconds of inactivity, then repeats at the same interval while the player remains idle. A new candidate is selected after each successful playback without immediately repeating the previous emote when alternatives are available.
• * grants access to every enabled emote.

Run /emote reload after editing the file manually.

Animation Files

Put .json files exported by the converter in config/emote/animations:

config/emote/animations/
├── hello.json
├── dance.json
└── another-emote.json

The file name is only used for storage. The root id field is the identifier used by commands, permissions, enable/disable settings, and the UI.

See the animation format and reference JSON for details.

Invalid files are skipped independently. If multiple files declare the same id, every file sharing that ID is rejected.

To protect server tick time when many players use emotes together, animations are limited to 8 MiB, 32 total nodes, 24 display nodes, 10 minutes, an average of 12 transforms and 4 visibility changes per tick, and 16 commands at one timeline boundary. These limits also apply to runtime API registrations.

Mod API

Emote provides a server-side API under io.github.hanhy06.emote.api.

Access it through EmoteApi.getInstance().

The API supports playback control, runtime emote registration, state queries, cancellable play listeners, and playback lifecycle listeners.

API mutations must run on the server thread. Runtime registrations survive /emote reload and are automatically removed when the server stops.

Troubleshooting

An emote does not appear

Run /emote reload and check the server log.

An emote may be skipped when:

• its animation JSON is invalid;
• its Minecraft version does not match the server;
• its exact ID is listed in disabled in emotes.json; or
• another file declares the same ID.

An emote cannot be played

Check that:

• the emote is granted in emotes.json;
• the player has the required permission; and
• the exact namespace:path ID is being used.

The player’s skin is not applied

Confirm that mineskin_api_key is configured and check the server log.

If MineSkin is unavailable, the textures stored in the animation JSON are used instead.

Configuration changes are ignored

Check that the JSON syntax is valid, then run /emote reload.

Invalid configuration is rejected and the previously loaded configuration remains active.

License

Apache License 2.0