🎭 Animotions V1.0.3

━━━━━━━━━━━━━━━━━━
Built by roleplayers, for roleplay servers

1.21.4+ • Paper

Support ViaVersion from 1.21.4+

━━━━━━━━━━━━━━━━━━

Requirements: PacketEvents, MineskinAPI key

✨ Features

• UI-Based Emoting — Shift+F opens a clean TextDisplay emote menu
• Duo Emotes — Shift+Q to share emotes (handshakes, hugs, daps)
• RP Chat — Type *{wave}* in chat to trigger emotes inline
• Blockbench Workflow — Create custom emotes with full bone animation
• Auto Resource Pack — Built-in HTTP server delivers shaders automatically
• Pack Merging — Works with Nexo, ItemsAdder, Oraxen, or a custom folder
• Shader Compatible — Detects OptiFine/Iris with graceful fallback + MineSkin body-part textures
• PlaceholderAPI — %animotions_current_emote% and more
• Per-Emote & Per-Category Permissions — Fine-grained LuckPerms-ready access control
• Animated Open/Close UI — SCALE_UP, ELASTIC, SLIDE, GROW and more animation styles

📋 Requirements

🚀 Installation

1. Install PacketEvents in plugins/
2. Place Animotions.jar in plugins/
3. Start the server — config files generate automatically
4. Stop the server
5. Paste your license key in (acquired through Discord ticket) plugins/Animotion/anim-license.txt:

   ANMT-XXXX-XXXX-XXXX-XXXX

1. Set your MineSkin API key in config.yml → mineskin.api-key
2. Set resource-pack.host to your server's public IP or domain
3. Open the resource-pack.port (default 50021) in your firewall
4. Start the server — you're ready!

Adding Emotes

Drop .bbmodel files into plugins/Animotion/emotes/ and run /animotions reload.

You can have multiple .bbmodel files — each with their own animations and bone hierarchies. Name them whatever you want:

plugins/Animotion/emotes/
├── social.bbmodel        ← wave, bow, shrug, etc.
├── sitting.bbmodel       ← sit, sit2, sit3, etc.
├── dance-pack.bbmodel    ← custom dance animations
├── duo-romantic.bbmodel  ← hug, kiss, bridal (duo)
└── duo-friendly.bbmodel  ← handshake, fistbump (duo)

• Solo vs Duo is auto-detected — if a .bbmodel contains player_root2, all its animations are duo emotes
• Each file keeps its own bone hierarchy and pivot points — no conflicts between packs
• Animation names must be unique across all files (duplicates are overwritten with a warning)

After adding new files, run /animotions cload to automatically add new emotes to category.yml without overwriting your existing configuration.

🎮 Controls

⚙️ Configuration

config.yml (key sections)

resource-pack:
  enabled: true
  port: 50021
  host: "your-server-ip"
  required: true
  prompt: "§eAnimotion §7requires a resource pack..."

shader-detection:
  enabled: true
  extra-brands: []
  log-detections: true

emote-ui:
  enabled: true
  auto-close-seconds: 30
  duo-target-distance: 5.0
  close-on-move: true
  close-on-damage: true
  display-distance: 6.5
  items-per-page: 8
  animation:
    open-style: SCALE_UP    # SCALE_UP / ELASTIC / SLIDE_UP / SLIDE_DOWN / SLIDE_LEFT / SLIDE_RIGHT / GROW_HORIZONTAL / GROW_VERTICAL
    close-style: SCALE_UP
    open-duration: 5
    close-duration: 4

mineskin:
  enabled: true
  api-key: "your-key"
  log-uploads: true

merge-pack:
  mode: none          # none / auto / nexo / itemsadder / oraxen / folder
  output-folder: ""   # Only used when mode: folder
  keep-self-host: false

rp-chat:
  enabled: false
  trigger-format: "*{name}*"
  format-emote-syntax: true
  format-pattern: "✦{name}✦"
  format-color: "GOLD"
  format-italic: true
  format-bold: false

permissions:
  per-emote: false    # Enable animotions.emote.<name>
  per-category: false # Enable animotions.category.<id>

category.yml (auto-generated)

Controls how emotes appear in the UI. Auto-generated on first run with defaults.

Adding new emotes to categories:

1. Drop new .bbmodel files into emotes/
2. Run /animotions cload — new emotes are appended to category.yml (existing entries untouched)
3. Edit category.yml to set custom display names, categories, and order
4. Run /animotions reload to apply changes

categories:
  general:
    display-name: "&a✦ General"
    order: 1
    colour: "55FF55"
    allow-movement: false

emotes:
  wave:
    display-name: Wave
    type: single
    category: general

📝 Commands

Aliases: /emote, /animate, /gesture, /e

🔒 Permissions

Core

Per-Emote (opt-in: permissions.per-emote: true)

Per-Category (opt-in: permissions.per-category: true)

LuckPerms Example

# Base access for everyone
/lp group default permission set animotions.use true
/lp group default permission set animotions.ui true
/lp group default permission set animotions.rpchat true

# VIP gets duo emotes
/lp group vip permission set animotions.duo true

# Per-emote (when per-emote: true)
/lp group default permission set animotions.emote.wave true
/lp group vip permission set animotions.emote.* true

# Per-category (when per-category: true)
/lp group default permission set animotions.category.general true
/lp group vip permission set animotions.category.* true

# Admin
/lp group admin permission set animotions.admin true

🔌 PlaceholderAPI

Use in scoreboards, tab lists, chat formats, or any PAPI-compatible plugin.

💬 RP Chat Integration

Bring chat to life with contextual emotes!

Enable in config:

rp-chat:
  enabled: true

Type emotes inline:

Yo, what's up? *{nod_up}*

Other players see: Yo, what's up? ✦nod_up✦

Trigger Syntax

Configure what players type to trigger emotes:

Display Format

Requires animotions.rpchat permission.

🖥️ Shader Detection

Animotion automatically detects OptiFine and Iris shader mods via client brand.
When detected, body parts render at their real position so they stay visible and animated.

For the best experience with shader users, enable MineSkin — this generates per-body-part skin textures so every body part shows the correct skin region instead of repeating the head texture.

shader-detection:
  enabled: true
  extra-brands: []      # Add custom brand strings if needed
  log-detections: true

mineskin:
  enabled: true
  api-key: "your-key"

Note: MineSkin free tier allows ~2 req/min. Initial processing takes ~2-3 minutes per player (5 uploads). Results are cached to disk — no further API calls until skin changes.

🎨 Creating Emotes in Blockbench

Setup

1. Download Blockbench (free)
2. File → New → Generic Model

(Or simply add the given steve.bbmodel)

Required Bone Hierarchy

player_root
├── hip
│   ├── chest
│   │   ├── head
│   │   ├── left_arm
│   │   │   └── left_forearm
│   │   └── right_arm
│   │       └── right_forearm
│   ├── left_leg
│   │   └── left_foreleg
│   └── right_leg
│       └── right_foreleg

Steps

1. Create the bone hierarchy (bones only — no visible cubes needed)
2. Set pivot points matching Minecraft player joints
3. Animation tab → New Animation (name = emote name)
4. Add rotation/position/scale keyframes to each bone
5. Set loop mode: Once, Loop, or Hold
6. Save as .bbmodel

Duo Emotes

Use two skeletons in one model:
(Or simply add the given duo.bbmodel)

player_root           ← Player 1
├── body / head / arms / legs
player_root2          ← Player 2
├── body2 / head2 / left_arm2 / right_arm2 / left_leg2 / right_leg2

• player_root2 origin = offset between players
• All second-player bones end with 2

Loop Modes

📦 Resource Pack

Self-Hosting (default)

resource-pack:
  enabled: true
  port: 50021
  host: "your-public-ip"
  required: true

Make sure the port is open/forwarded if players connect from outside.

Merge Mode

Merge the Animotion resource pack into another plugin's pack pipeline:

merge-pack:
  mode: auto  # Detects Nexo > ItemsAdder > Oraxen

When merge mode is active, the built-in HTTP server is automatically disabled.

🐛 Troubleshooting

🔑 License

On startup the plugin validates your key against our license system. On success it's cached locally. Periodic heartbeats confirm status.

📬 Support

• Discord: discord.gg/anonventions
• Documentation: anonventions.org
• Purchase: anonventions.org/store

<p align="center">
<strong>More expression. More immersion. More roleplay.</strong>
</p>