Better Player Model - Paper Plugin

A server-side companion plugin designed specifically for the Better Player Model mod.

This plugin acts as a lightweight synchronization bridge, allowing players on your server to seamlessly see each other's custom 3D player models without forcing you to install any Fabric/Forge mods on the server side.

Key Features

Zero Server-Side Mod Requirements: Keep your server strictly running on Paper/Purpur. No hybrid server software or mods are required on the server side.
Full Model Synchronization: Automatically handles and syncs custom 3D player models between all connected clients who have the Better Player Model mod installed.
Model Management: Fully supports player model uploads, data synchronization, and saved model selections.
Universal Compatibility: Designed to be compatible with all modern builds of the Better Player Model client mod.

How to Install

Download the latest .jar file from the Files tab.
Drop the file into your server's plugins folder.
Restart or reload your server.
Ensure your players have the client-side Better Player Model mod installed to enjoy their custom models!

Configuration & Model Installation

Plugin Config: The configuration file is generated automatically at plugins/PaperBPM/config.toml after the first server boot.
Installing Models: Drop your custom 3D models directly into the plugins/PaperBPM/models/ directory on your server.

Network Troubleshooting Guide: Model Sync Timeouts and Disconnections

If players are experiencing disconnections (e.g., getting kicked with a Timed Out or Connection Lost message) or if models fail to sync when joining the server, it is usually caused by heavy network packets during the initial model handshake.

How to fix this on your Paper server:

Increase Server Timeout Thresholds: Large 3D models require more time to process and transmit over the network. By default, vanilla Minecraft and Paper kick players if they don't respond quickly enough during packet bursts.
- Open your server's server.properties file.
- Locate the max-tick-time setting and increase it (or set it to -1 to disable it entirely for testing).
- If you are using Paper-specific performance forks or proxy setups (like Velocity/BungeeCord), ensure their respective connection timeout settings are scaled up to allow model transfers.
Check Plugin Configuration:
- Go to plugins/PaperBPM/config.yml.
- Look for any network/buffer adjustment settings if you have modified them. Keeping them at default values is recommended for the initial beta tests.
Optimize Model Sizes:
- If a specific player causes the server or other clients to lag/timeout during synchronization, check the size of their model file inside the server's plugins/PaperBPM/models/ folder.
- Extremely unoptimized models with massive texture sheets or high polygon counts can choke the server's outbound network buffer.

Links & Resources

Required Client-Side Mod: Better Player Model on CurseForge
Source Code & Bug Tracker: GitHub Repository

Better Player Model Plugin