Animotions

Current version: Animotions 1.0.10-Dev28. Use Personas 1.2.5 if you install the optional NPC addon separately.
Install the released PacketEvents 2.14.0 Spigot plugin. Paper 26.3 requires
Java 25. Follow the current update guide (see UPDATES-DEV28.md in the download), including the
explicit ItemsAdder rebuild after loading finishes. Recent movement, camera, NPC
performance and legacy-pack repairs from Dev25–27 are all retained. Automated
compatibility checks are recorded separately from live client/provider acceptance.

Give players a quick way to express themselves with solo emotes, shared animations, and a choice of menus. The supplied library preserves 36 original solo emotes and 19 original duo emotes, and now adds three solo and two duo extras for a default total of 60.

Open /animotions settings to edit menu, preview, movement and first-person options in game. Changes remain in a draft until Apply; Discard keeps the previous settings. The editor backs up changed files. Current upgrade instructions are in UPDATES-DEV28.md in the server download.

Installation and requirements

1. Back up the plugin and provider folders, then stop the server. Keep your existing data and license.
2. Replace the previous Animotions JAR with Animotions-1.0.10-Dev28.jar. Install the official PacketEvents 2.14.0 Spigot plugin separately. Use Personas 1.2.5 only if you need the NPC addon; neither dependency is bundled in the Animotions server ZIP.
3. Start the Paper server normally. The declared target is Paper 1.21.5 through 26.3; use Java 21 for 1.21.x or Java 25 for 26.1 onward. Folia is unsupported. Check /animotions status.
4. Wait for asset export and your pack provider to finish loading. For ItemsAdder, run /iazip, wait for generation and hosting publication, then reconnect and accept the new pack. PACK-REBUILD-REQUESTED alone does not confirm delivery; PACK-VERIFIED confirms the checked downloaded revision.
5. Try a wheel selection, a solo and duo emote, movement return and first-person hands. Test /personas studio separately if using the addon.

The supplied Animotions-ResourcePack.zip matches the default assets. Custom emotes, props or settings require your server’s complete regenerated pack. Keep merge-pack.allow-shader-conflicts: false; do not overwrite another provider’s pack or delete your existing data folder.

Updating your server

This update repairs pack upgrades that were blocked by a changed generated model texture. Animotions saves the conflicting copy in plugins/Animotions/pack-recovery/ before replacing it from the original model. Shared shaders and unrelated files remain protected. ItemsAdder rebuilds wait until its content is ready.

The same recovery now covers verified bundled Personas interface assets. Pack protection can change a PNG’s bytes without changing its pixels; those older copies no longer block the entire studio update. Animotions saves the previous files before restoring the current bundled artwork. Your separately named custom assets remain protected.

Native player heads now meet the torso when resting or turning. Elbow, knee and waist cut faces use neighbouring skin pixels instead of empty texture space. Clothing overlays keep their transparency. Older processed body textures regenerate once after upgrading, for both classic and slim skins; existing cache files remain on disk. NPCs retain their ordinary appearance while replacement body textures are prepared.

The wheel keeps its pixel ring and animated previews. Animotions now checks the provider pack actually sent to each player, so compatible providers no longer need a manually entered pack UUID. NPCs keep their ordinary appearance while body textures are prepared. Classic and slim skins have separate body textures and arm shapes, including when a skin changes during playback. The earlier disconnect and head-transform fixes remain included.

Replace the plugin JAR and restart normally. Missing config.yml settings are now added on startup and /animotions reload, including the wheel, previews and provider options. Your existing values, comments, API keys and custom sections stay intact. Each change creates an exact .bak copy beside the config. A config already at the current version is still checked for missing settings.

Invalid YAML is left untouched. Fix the reported line and reload; the console does not print config values. The current config version is 5.

Existing sequences.yml files also receive missing bundled settings with a backup. Your explicit timings, disabled features and custom clip settings are retained.

Servers with large ItemsAdder packs no longer hit the old 20,000-entry shader-scan limit just because they contain many models or textures. Conflicting shared shaders are still checked.

Personas contributes its scene studio to the same pack. It uses vanilla-grey panels, recessed item slots and labelled pixel buttons. The original supplied layout remains available as the supplied theme. Close stays at the far right; removing an actor or placement uses a separate confirmation. Install both matching plugins, rebuild your pack, then open /personas studio.

Choose your menu

Use /animotions menu list for the familiar list or /animotions menu wheel for a circular display menu. Your choice is saved for the next time you open it.

The wheel surrounds its centre with a pixel ring and highlights the selected sector. The highlighted sector, selected label and centre name identify the same emote. Left click moves to the previous entry; right click moves to the next. Press F to select, or Shift+F to go back or close. A single category opens directly to its emotes. Categories and larger collections use pages. Existing duo invitations still use the usual accept and deny controls.

Operators can set the default in config.yml:

emote-ui:
  default-view: list
  wheel:
    enabled: true
    slots: 8
    distance: 3.5
    size: 1.0
    offset:
      x: 0.0
      y: 0.0
    skip-single-category: true
    preview-frame-ticks: 5

The list remains available when the wheel is disabled. Java players receive display menus; Bedrock players use the existing command menu.

Wheel placement is independent of the list. Adjust size to resize the ring, previews and labels together. Older wheel.radius values stay in the file but are no longer used.

See an emote before playing it

Animotions builds small animated previews when your emote library changes. Unchanged animations reuse their cached renders. Only the highlighted wheel card animates, keeping menu updates small. Other cards show a pose from their animation so they are easier to recognise while browsing.

The wheel uses Minecraft lettering and hard-edged pixel previews, without smooth HD menu artwork. As a display-entity menu, its apparent pixel size still changes with FOV and distance. The default preview uses eight 64 × 64 frames per emote. You can change the frame count, resolution, and total pack budget under previews in config.yml. Large collections keep readable text entries when they reach that budget.

Personas animation cards use small posed 3D models by default. Set previews.inventory-style: animated for moving 16 × 16 thumbnails, or model for the 3D miniatures. Rebuild and deliver the pack after changing this setting. Both styles use the same pack budget. A complex model can use the animated thumbnail when its geometry exceeds the miniature limits.

The included preview skin is ModelSteve. To choose another skin, save a 64 × 64 Minecraft skin PNG inside the Animotions folder and set its relative path:

previews:
  skin: previews/model-steve.png

Run /animotions reload after changing settings. /animotions previews reports the preview count and size; /animotions previews rebuild rebuilds the pack using the current loaded library. Clear skin to use each model’s own texture. Preview skins change menu images only. The first-person examples keep ModelSteve in their editable files and offline previews; their live arms use the player’s skin.

When updating an existing installation, set previews.skin to previews/model-steve.png yourself: existing configuration choices are preserved. Rebuild and deliver your pack after the change.

Previews appear after the player loads the matching resource pack. While the pack is unavailable, the wheel shows PACK NOT READY and readable labels. For external providers, Animotions observes the pack request, checks the advertised download against the current generated pack revision and head model, then waits for the client to finish loading it. It does not send a second pack.

Automatic checking supports HTTP(S) packs up to 64 MiB with an advertised SHA-1 hash. The server must be able to download its own pack address. A verified download is reused across players. If your provider uses a larger pack or cannot meet those requirements, set previews.provider-pack-id to its request UUID. previews.assume-pack-loaded remains an explicit guarantee that you are delivering the correct pack. Neither setting overrides a failed initial pack export.

If the first pack build fails, player and NPC emotes wait instead of spawning with missing model assets. Fix the reported build problem, rebuild the provider’s final pack and let players load it. A failed later reload retains the last successfully published library.

Starts, loops and endings

With the default plugins/Animotions/sequences.yml, emotes enter their first pose smoothly. Animations authored to play once finish with an exit; authored loops repeat after a single entry; authored holds keep their last pose. Original action keyframes and source files are retained.

Choose a complete playback mode by adding a suffix to the emote name:

/animotions Wave:once
/animotions Wave:loop
/animotions Wave:hold
/animotions stop

Once plays entry, action and exit. Loop plays the entry once and repeats the action, joining the end back to its beginning where needed. Hold plays the entry and action, then keeps the last pose. The same suffixes work with duo invitations; both actors share the phase timing. The menu catalogue keeps one entry per emote.

/animotions stop requests an exit from the current pose. Removing an NPC, disconnecting or emergency cleanup still stops immediately. In Personas, select Once, Loop or Hold beside the animation list; Clear removes that animation immediately.

Adjust entry, exit and loop-closure timing in sequences.yml, then reload. The default auto mode follows the original animation’s once/loop/hold setting. Set default-mode: original to retain original playback for names without an explicit suffix. Situp_Help includes a staged approach and seated transition; use transition: direct for that entry if replacing it with different choreography.

See docs/developers/ANIMATION-SEQUENCES.md in the download for configuration and phase APIs. Editable movement projects are supplied separately as Animotions-Editable-Vanilla-Movements.zip. Runtime :loop already includes its entry.

Try animated first-person models

The optional model viewer includes Asterline, a brass-and-enamel instrument with a hinged crystal chamber, Tidecaster, a teal twin-prong projector, and Embercoil, an orange ring-emitter tool. All three have their own model, pixel textures, and draw, idle, fire, reload, and inspect animations.

/animotions firstperson list
/animotions firstperson asterline
/animotions firstperson action fire
/animotions firstperson action reload
/animotions firstperson hide

Access requires animotions.firstperson, granted to operators by default. Models are shown only to the player using them. Your real inventory, ammunition and damage remain controlled by the server and your weapon plugin. With replace-hands: true, the ready model replaces the visible vanilla hands and held items. The held hotbar icons can appear empty while it is active; hiding the model restores current items. Inventory interaction safely closes it. Hand replacement does not make your player invisible.

The three examples use your current arm and sleeve textures, including classic and slim skin widths. Skin changes are checked during playback. If matching arm textures are still being prepared, the custom arms stay hidden and your vanilla hands remain visible; the model’s tool can remain on screen. Prepared textures are reused, and temporary preparation failures retry without requiring /animotions reload. Clients whose shaders cannot use the immediate skin rendering path need matching prepared textures and a working MineSkin setup. Custom models can map their own arm sections or keep authored gloves and mechanical hands; see player skin arms (see docs/developers/FIRST-PERSON-MODELS.md#player-skin-arms in the download).

These are camera-relative display models on Java clients. They follow the player’s view, but remain objects in the world: nearby walls, latency, and field of view can affect their appearance. Your avatar remains visible in third person, but the model does not automatically disappear when you press F5. Use /animotions firstperson hide when switching perspective; the server cannot detect F5 camera changes.

The examples use left click to fire, right click or F to inspect, and Q to reload. Sneak combinations are available. Change inputs.bindings in the model profile; inputs.enabled: false leaves control to an integration. Sneak, sprint and jump events are supported, including sneak/sprint modifiers. These follow Minecraft’s configured action keys; unreported keys such as R or Alt require a client integration. Only configured consumed actions replace their normal effect.

To add a model, put its .bbmodel file in plugins/Animotions/firstperson/, add its model and action names to firstperson/models.yml, and reload. The example entries show the format. Position, rotation, scale, and transition time are configurable per model. The service limits model complexity and simultaneous viewers; invalid files leave the working registry active.

The Asterline update adds its missing example profile once and backs up the previous firstperson/models.yml. Existing custom model settings and edited model files are preserved. Removing the example after this update is respected on later reloads.

All three examples support action inspect:loop and action inspect:end. The first repeats the inspection; the second returns smoothly to the ready grip. Every action also has :start, :once and :hold variants. Ordinary action timing stays the same, and transitions keep connected parts together.

First-person configuration version 4 adds controls and hand replacement to recognized stock examples with a backup. Earlier stock migrations remain available. Explicit settings, custom models and deliberately removed profiles are preserved. If FP-EXAMPLES-PRESERVED appears, follow its file and reload instructions to merge the examples manually. The plugin installs its bundled first-person models under plugins/Animotions/firstperson/ when missing and preserves custom files. See the first-person model guide (see docs/developers/FIRST-PERSON-MODELS.md#start-end-and-loop-variants in the download) for transition settings and custom profiles.

Movement and camera options

Open /animotions movements or /animotions movements packs to choose a movement pack. Click a pack, press Select, then use Body to turn the animated body on or off. The saved choice survives restarts. Choosing a pack does not enable it or open a first-person model. You can also select directly with /animotions movements pack relaxed.

/animotions movements on enables the optional animated body. It includes idle, walking, running, crouching, jumping, falling, swimming, creative flight, elytra glide, climbing, attack, mining, hurt, item-use and sleep examples. /animotions movements sit or /animotions movements lay selects a pose; /animotions movements auto resumes detection and /animotions movements off restores the vanilla body. Explicit emotes temporarily take priority. Physics, collision and the normal movement camera stay unchanged.

To create a pack in game, open /animotions settings, choose Movement packs, then Create movement pack. Give it an ID, edit its display name, permission, playback speed and state animations, then press Apply. Shared movement states supplies the defaults; each pack can inherit a state, assign a loaded solo animation, or use off to show the vanilla body for that state. Classic and Relaxed are included. Relaxed requires animotions.movementpack.relaxed as well as the base movement permission.

The same settings are stored in plugins/Animotions/movements.yml: states contains shared assignments, packs.<id> contains named packs, and default-pack chooses the fallback. Player choices are stored separately in movement-selections.yml. Missing or inaccessible selected packs fall back to the configured default; if that cannot be used, the vanilla body remains visible. Placeholder conditions and custom states are configured in the file; see the movement pack guide (see docs/developers/MOVEMENT-PACKS.md in the download).

Camera modes are separate from movement packs:

first and third do not press F5 or detect your perspective. Switch the mode yourself when using that fallback; normal clears it. Other players keep seeing the complete animated head. First-person models follow the head camera’s view origin when it is active. Ending playback restores the camera; another plugin’s camera takes priority. Camera roll is not supported. The camera and movement permissions are animotions.camera and animotions.movements, both operator-only by default.

Equipped armor and custom gear

Leather, chainmail, copper, iron, gold, diamond and netherite armor, plus turtle helmets, follow the animated bones with worn meshes. Leather colors are preserved. Copper uses Minecraft’s copper equipment textures and requires a client that includes them. Elytra, trim patterns and foreign equipment meshes still need explicit custom attachments. Integrations can supply bone-attached item models through the equipment API (see docs/developers/ANIMATED-EQUIPMENT.md in the download). While first-person hand replacement is ready and active, it hides the owner’s duplicate animated arms and attached hand gear; other players continue to see them.

Add props to emotes

Props let a character carry a lantern, hold a tool, or animate another model as part of a solo or duo emote. Their cubes and textures join the same generated resource pack.

1. Copy an embedded-texture .bbmodel into plugins/Animotions/models/.
2. Add an entry in attachments.yml using the exact emote and bone names.
3. Run /animotions reload and load the rebuilt pack.

For a custom model named lantern with a sway animation, an attachment can use:

enabled: true
emotes:
  Speech:
    - model: lantern
      bone: right_forearm
      offset: [0, -5, 0]
      rotation: [0, 0, 0]
      scale: 0.6
      animation: sway

Place your matching lantern.bbmodel in plugins/Animotions/models/ before using that example configuration. Offset values are model pixels; 16 pixels equal one block. The model’s root pivot is placed at the selected bone plus this offset. Its own animation is fitted to the emote’s duration. Leave out animation for a static prop that follows the bone.

Up to four attachment entries and 128 visible prop cubes can be assigned to an emote across both actors. Each prop requires one connected bone hierarchy, local bone rotations, and embedded PNG textures. For a duo, add actor: initiator, target or both to each entry. Props are disabled until enabled in attachments.yml.

Use Animotions with Personas

Personas actors use the same emote models and props as players. Assign the emote ID to a Persona or a scene member. A prop attached to Speech, for example, also appears when that emote plays on a Persona.

NPC animations use prepared body-part skin textures. Keep MineSkin enabled with a valid key when preparing new skins. The ordinary NPC remains visible during preparation and starts the requested animation once every part is ready. A failed request leaves that NPC visible; it does not display head textures on its limbs. Changing or removing the animation cancels a queued start. Prepared skins are reused between actors.

After updating, rebuild and deliver the provider’s final pack. The correct head transform is needed even when body textures are cached. Shader conflicts in another plugin’s generated overlays still require a compatible final pack; the exporter does not replace another plugin’s shaders. Mixed client versions through ViaVersion need the provider to preserve the appropriate version overlays.

For groups of characters, saved scene layouts, skin selection, and placement controls, see the Personas guide supplied with the addon.

Add more emotes

Put supported models in plugins/Animotions/emotes/ or imports/. The file watcher waits for copied files to settle, loads them, updates the catalogue, and builds the previews. First-person models and prop libraries have their own folders and are kept out of the emote list.

Your existing emote files are kept during updates. The plugin installs its original steve.bbmodel and duo.bbmodel only when the emotes folder has no .bbmodel files. Back up any edited copies before deliberately replacing them; do not clear the emote folder to force an update.

Resource packs

Animotions detects supported ItemsAdder, Nexo, Oraxen, and CraftEngine installations and exports its assets to their configured pack locations. If more than one pack manager is enabled, select the owner explicitly in merge-pack.mode. Other pack managers can use a configured folder adapter.

Leave resource-pack.send-on-join: false when another manager handles delivery. Rebuild and distribute that manager’s final pack after importing Animotions assets.

Core shader conflicts stop the automatic export with a diagnostic instead of silently replacing another plugin’s shader. Combining shader-based plugins still requires a matching, validated shader pair for the client version.

Useful commands

Reload, model listing, pack management, and preview rebuilds require animotions.admin.

Release checks

Dev28 passed 785 automated tests, actual Paper 26.3 API linkage and shader compilation checks. On Paper 26.3 build 157 BETA with Java 25, the final JAR loaded its dependencies and reached its existing missing-license gate, then shut down cleanly. Licensed gameplay, a connected Minecraft client and live provider acceptance were not exercised in that smoke check. Test your actual pack, wheel input, camera and shader configuration with a player before rollout.