Emote v2.3.0 Update

v2.3.0 includes major changes to the playback engine and Mod API, including breaking changes to existing APIs and several Emote format features.

Emote Mod

Added

• Added Marker mannequins, allowing Emotes to be played in the world without requiring an online player.
• Marker mannequins use minecraft:marker.
  • Use the emote field in CustomData to specify the Emote to play.
  • Use emote_skin to specify the skin displayed by the mannequin.
• Added default_skin to config.json. The default skin can be specified using a Minecraft player name.
• The default skin is prepared during server startup and reload. The prepared result is cached and reused after server restarts.
• Replaced the previous hexagonal Emote wheel with a circular design.

Removed

• Removed two-player Emotes.
  • Sequences using participants or await_partner are no longer supported.
  • The handshake sample has also been removed.
• Removed per-node space and the skin participant distinction.
  • All nodes are now processed relative to a single playback root.
• Removed outro.
  • Stopping playback now ends the Emote immediately without an outro animation.
• Removed loop_end.
  • Loops now repeat from loop_start to the end of the timeline.
• Removed automatic conversion support for legacy Emote Animation schemas 1 and 3.

---

Mod API

Playback Sessions and Session IDs

Each Emote playback creates a separate playback session. Every session is assigned a unique UUID session ID, so multiple playbacks of the same Emote still receive different IDs.

• After playback starts successfully, the session ID can be obtained from PlayResult.Success.playback().sessionId().
• By storing the session ID, integrations can later query or stop that playback, seek within its timeline, or change its placement.
• Use getPlayback(player) to retrieve the player's current playback.
• Use getPlayback(sessionId) to retrieve a specific playback session.

Playback State

PlaybackInfo now provides more detailed information about the current playback state.

• state() reports whether the session is running, closing, or fully closed.
• elapsedTicks() reports the total number of playback ticks elapsed since the session started.
• timelineTick() reports the current position within the playback timeline.
• position() provides the current animation, sequence step and repeat position, playback segment, and position within that segment.
• placement() provides the current playback root position, rotation, and placement mode.

Elapsed time and timeline position are intentionally separate.

When a loop repeats or the playback position is changed, the timeline position may move backward or forward, while elapsed time continues to represent how long the session itself has been running.

Timeline Inspection

Use getTimeline(sessionId) to inspect the order and duration of a playback session.

• The total playback duration and loop configuration can be inspected.
• segments() includes animation, transition, wait, loop-delay, and hold segments.
• Random selections and repetitions in Sequences return the results already resolved for that specific session.
• Each segment includes its start tick. The end tick is exclusive.

Seeking

Running playback sessions can be moved to another playback position without restarting the session.

• setTick(sessionId, tick) moves playback to a specific tick in the full timeline, including Sequence transitions and wait segments.
• setAnimationTick(sessionId, tick) moves to a specific tick within the currently active Animation.
  • Returns false if playback is not currently inside an Animation segment.
• setStep(sessionId, stepIndex, repeatIndex, tick) moves to the selected Animation of a specific Sequence step and repetition.
  • tick specifies the position within that Animation.
  • Step and repeat indexes are zero-based.

When seeking, the pose and timeline state required at the destination are applied. Events and commands from skipped portions of the timeline are not replayed sequentially.

When seeking into a different Animation segment, the previous segment is closed and the destination segment is started.

Seek requests made from inside a callback are applied after the current callback processing finishes.

server_sync playback does not support seeking.

Playback Position and Rotation

The playback root can either follow the player or remain fixed at an external world position.

• PlaybackPlacement.actor() uses the existing player-based placement behavior.
  • Position tracking follows the configured movement behavior.
  • Rotation follows the player's rotation.
• PlaybackPlacement.external(position, yaw) fixes the playback root to the specified world position and rotation.
• Use play(player, emoteId, placement) to specify placement when starting playback.
• Use setPlacement(sessionId, placement) to change placement without restarting playback.

External placement still uses the player's current world. Player hiding behavior and playback cancellation conditions continue to apply.

Node Position Queries

Use getNodeWorldPosition(sessionId, nodeId) to retrieve the world-space origin of a node based on the current pose and playback root position and rotation.

• Both Display nodes and Anchor nodes are supported.
• If the session or node does not exist, Optional.empty() is returned.
• This can be used to attach particles, custom entities, or other effects to Emote nodes.

Animation and Sequence Registration

In addition to runtime Animation registration, Sequences can now also be registered at runtime.

• Use register(animation) to register an Animation.
• Use register(sequence) to register a Sequence.
  • Referenced Animations must already be registered or loaded from files.
• The returned Registration can be used to inspect the registration ID and state or unregister the entry.
• Runtime registrations remain available after an Emote reload.
• Use get(emoteId) and getAll() to query registered Emotes.

EmoteInfo now includes whether the Emote is an Animation or Sequence and whether it can be played directly.

For Sequences whose duration cannot be determined in advance, such as those using random selection, durationTicks() may return null.

Lifecycle Callbacks

The previous event-specific named callback system has been replaced with playback lifecycle callbacks.

• Use registerCallbacks to register callback names and their Java implementations.
• Animations and Sequences can define callback names and string payloads in their top-level callbacks array.
• Supported lifecycle callbacks:
  • onStart
  • onTick
  • onLoop
  • onClose
• Sequence-level callbacks and callbacks for individual Animation segments are executed independently.

The PlaybackContext passed to callbacks provides access to:

• Session ID
• Server and world
• Playback actor
• Node entities and their world positions
• Current playback position
• Playback close reason

getUserState() and setUserState() can be used to store per-playback state for each callback.

API operations that modify playback state or query playback information must be performed on the server thread.

Migration Notes

• Two-player Emote matching has been removed.
  • Existing Sequences using participants or await_partner are no longer supported.
  • The handshake sample has also been removed.
• Event-level callbacks must be migrated to the new top-level callbacks and Java lifecycle callback system.
• Several public API names and types have changed:
  • find → get
  • EmoteRegistration → Registration
• Integrations that directly use PlayResult, PlaybackInfo, EmoteInfo, Animation model classes, or callback types must also be updated.