https://github.com/soldadohumano/vportrait
vPortrait is a high-performance Minecraft plugin dedicated to visual identity and immersion. It redefines player interaction by introducing dynamic portraits designed with meticulous attention and system performace.
https://github.com/soldadohumano/vportrait
java minecraft minecraft-plugin
Last synced: 4 months ago
JSON representation
vPortrait is a high-performance Minecraft plugin dedicated to visual identity and immersion. It redefines player interaction by introducing dynamic portraits designed with meticulous attention and system performace.
- Host: GitHub
- URL: https://github.com/soldadohumano/vportrait
- Owner: SoldadoHumano
- License: agpl-3.0
- Created: 2025-12-21T05:33:13.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-21T15:32:23.000Z (5 months ago)
- Last Synced: 2026-01-22T03:30:50.237Z (5 months ago)
- Topics: java, minecraft, minecraft-plugin
- Language: Java
- Homepage:
- Size: 104 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
vPortrait
High-performance image rendering for Minecraft frames via Netty.
## 1. Overview
**vPortrait** is a high-performance Spigot/Paper plugin designed to render external images into *Glow Item Frames* using custom maps. The project focuses on low-level packet manipulation and security to ensure a seamless and safe experience for large-scale servers.
## 2. Key Technical Features
### 🛡️ Security First
* **SSRF & DoS Mitigation:** The `PortraitManager` implements strict 5-second timeouts and `User-Agent` validation to prevent thread-locking or network exploitation.
* **High-Priority Protection:** Listeners registered at `HIGHEST` priority ensure that portrait entities are immutable and protected against accidental player interactions.
### ⚡ Performance & Fluidity
* **Netty Pipeline Injection:** Uses `PlayerJoinListener` to inject custom handlers into the server's Netty pipeline. It intercepts `ClientboundAddEntityPacket` to force-send map data immediately, eliminating visual flickering when a player approaches a portrait.
* **Optimized Rendering:** Features a 10-second per-player cooldown on map canvas updates to save CPU cycles.
* **Bicubic Interpolation:** Images are processed using `Graphics2D` with bicubic interpolation, ensuring high-fidelity downscaling.
### 🧩 Smart Logic
* **Auto-Facing Detection:** The `SelectionManager` calculates the `BlockFace` based on the player's `Yaw` and the selection axis (X or Z), making placement intuitive.
* **GSON Persistence:** Lightweight and efficient data storage for fast plugin startup and shutdown cycles.
## 3. Requirements
* **Java 21** or higher.
* **Spigot/Paper API** (Compatible with current stable versions).
* Tested on Paper 1.21.3
## 4. Commands & Permissions
| Command | Description | Permission |
| :--- | :--- | :--- |
| `/vportrait tool` | Gives the Portrait Wand (Golden Axe). | `vportrait.use` |
| `/vportrait upload ` | Renders the image in the selected area. | `vportrait.use` |
| `/vportrait remove` | Removes the portrait being looked at. | `vportrait.use` |
| `/vportrait reload` | Reload the system. | `vportrait.admin` |
| `/vportrait list` | Show count of active portraits. | `vportrait.admin` |
| `/vportrait sync` | Allows force sync images for yourself. | `vportrait.sync` |
Attention! For security reasons, all permissions are set to OP by default. Use a permissions management system of your choice to grant the appropriate permissions to the appropriate groups.
## 5. License
This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. Any modified version or network-deployed service using this software must make its full source code available under the same license, as required by the AGPL-3.0.
---
## Premium Version
Interested in more features, dedicated support, or advanced optimizations? Check out the paid version of our tools at our official Discord store:
👉 **[Join ByVitor Discord Store](https://discord.gg/YUbR6YDGwp)**
---
Developed with love by vitor1227_OP (SoldadoHumano)