toxicity188 · toxicity188 · Mar 22, 2026 · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026
diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore
@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -35,7 +35,7 @@ Upload the model, resource pack, or test code that can reproduce the issue if po
 
 ### 🌍 Environment
 - OS: (Windows, Linux, etc.)
-- Server software & version: (Paper 1.21.1, etc.)
+- Server software & version: (Paper 26.2, etc.)
 
 ---
 

diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -33,7 +33,7 @@ The following environments are not supported, and feature requests relying on th
 - Informal / modified launchers (e.g., Feather Client)
 - Closed-source mods/plugins (Optifine, ItemsAdder, Nexo, etc.)
 - Hybrid server platforms (e.g., Arclight)
-- Legacy server versions (1.20.1 or lower)
+- Legacy server versions (1.21.1 or lower)
 - Bedrock Edition
 - Extremely outdated CPU / hardware
 - Features fundamentally **impossible on server-side** due to engine or protocol limitations

diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
@@ -2,7 +2,7 @@ name: Package plugin
 
 on:
   push:
-    branches: [ "master", "v2" ]
+    branches: [ "master", "v2", "v3" ]
 
 permissions:
   contents: read
@@ -19,11 +19,11 @@ jobs:
       BUILD_NUMBER: ${{ github.run_number }}
       COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
     steps:
-      - uses: actions/checkout@v6
-      - name: Set up JDK 21
+      - uses: actions/checkout@v7
+      - name: Set up JDK 25
         uses: actions/setup-java@v5
         with:
-          java-version: '21'
+          java-version: '25'
           distribution: 'temurin'
       - name: Grant execute permission for gradlew
         run: chmod +x gradlew

diff --git a/.github/workflows/pr-test.yml b/.github/workflows/pr-test.yml
@@ -2,7 +2,7 @@ name: PR Test
 
 on:
   pull_request:
-    branches: [ "dev", "v2-dev" ]
+    branches: [ "dev", "v2-dev", "v3-dev" ]
 
 permissions:
   contents: read
@@ -11,19 +11,16 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
-      - name: Set up JDK 21
+      - name: Set up JDK 25
         uses: actions/setup-java@v5
         with:
-          java-version: '21'
+          java-version: '25'
           distribution: 'temurin'
 
       - name: Grant execute permission for gradlew
         run: chmod +x gradlew
 
-      - name: Build with Gradle
+      - name: Test build
         run: ./gradlew build --stacktrace
-
-      - name: Run Tests
-        run: ./gradlew test --stacktrace
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -2,7 +2,7 @@ name: Publish plugin
 
 on:
   push:
-    branches: [ "master", "v2" ]
+    branches: [ "master", "v2", "v3" ]
 
 permissions:
   contents: read
@@ -16,12 +16,13 @@ jobs:
       MODRINTH_API_TOKEN: ${{ secrets.MODRINTH_API_TOKEN }}
       BUILD_NUMBER: ${{ github.run_number }}
       COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
+      COMMIT_HASH: ${{ github.sha }}
     steps:
-      - uses: actions/checkout@v6
-      - name: Set up JDK 21
+      - uses: actions/checkout@v7
+      - name: Set up JDK 25
         uses: actions/setup-java@v5
         with:
-          java-version: '21'
+          java-version: '25'
           distribution: 'temurin'
       - name: Grant execute permission for gradlew
         run: chmod +x gradlew

diff --git a/AGENTS.md b/AGENTS.md
@@ -33,7 +33,7 @@ Scope: entire repository unless a deeper AGENTS.md overrides this file.
 ## 2) Language and File Placement Rules
 
 ### MUST
-- Use Modern Java (language level 21) and Kotlin.
+- Use Modern Java (language level 25) and Kotlin.
 - `api` module is Java-only for production code (Kotlin DSL build scripts are allowed).
 - Non-`api` modules should be Kotlin-first unless existing local code is explicitly Java-bound (e.g., mixin/accessor interop).
 - Follow existing package root `kr.toxicity.model...` and module-specific suffixes.

diff --git a/BANNER.md b/BANNER.md
@@ -1,9 +1,8 @@
 <div align="center">  
 
-![](https://github.com/user-attachments/assets/89e191ba-ed4f-44ab-bb98-634cfe568dca)
+![](https://github.com/user-attachments/assets/ecd13a35-e897-44c2-b12f-8d465f33dab5)
 
-# BetterModel
-*- Modern Bedrock model engine for Minecraft Java Edition -*
+---
 
 [![](https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/available/modrinth_vector.svg)](https://modrinth.com/plugin/bettermodel)
 [![](https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/available/hangar_vector.svg)](https://hangar.papermc.io/toxicity188/BetterModel)
@@ -20,16 +19,15 @@
 
 # ✨ What is BetterModel?
 
-**BetterModel** is a server-based engine that provides runtime BlockBench model rendering & animating for Minecraft Java Edition.  
+**BetterModel** is a server-based engine that provides runtime [BlockBench](https://www.blockbench.net/) model rendering & animating for Minecraft Java Edition.  
 
-It implements **fully server-side 3D models** by using an item display entity packet.
-
-- Importing Generic BlockBench model `.bbmodel`
-- Auto-generating resource pack
-- Playing animation
-- Syncing with base entity
-- Custom hit box
-- 12-limb player animation
+- Built on the `item-display` packet.
+- Implements **essential BlockBench elements**, including `cubes`, `meshes`, `null objects`, and `locators`.
+- Support for **model animations**, `Molang` expressions, and **IK** (Inverse Kinematics) rigging.
+- Supports **player skin models** and **custom armor**.
+- **Automated resource pack generation** with **zero reliance on core shaders**.
+- Provides support for **entity syncing**.
+- **Extensible API** available for integration.
 
 ## 🚀 Comparison with ModelEngine
 The main reason I created it is:
@@ -69,8 +67,8 @@ BetterModel supports **player model with using user's custom skin without textur
 
 ## 🏗️ Supported environment
 
-[![](https://img.shields.io/badge/minecraft-1.21%7E1.21.11-8FCA5C?style=for-the-badge)](https://www.minecraft.net/en-us/download/server)
-[![](https://img.shields.io/badge/java-21%7E-ED8B00?style=for-the-badge)](https://adoptium.net/)
+[![](https://img.shields.io/badge/minecraft-1.21.4%7E26.2.x-8FCA5C?style=for-the-badge)](https://www.minecraft.net/en-us/download/server)
+[![](https://img.shields.io/badge/java-25%7E-ED8B00?style=for-the-badge)](https://adoptium.net/)
 
 ### Bukkit
 [![](https://img.shields.io/badge/folia-supported-blue?style=for-the-badge)](https://papermc.io/downloads/folia)

diff --git a/LICENSE_HEADER b/LICENSE_HEADER
@@ -1,4 +1,6 @@
 This source file is part of BetterModel.
-Copyright (c) 2024–2026 toxicity188
+Copyright (c) ${CREATION_YEAR} toxicity188
 Licensed under the MIT License.
 See LICENSE.md file for full license text.
+
+#year_selection file
diff --git a/README.md b/README.md
@@ -21,16 +21,15 @@
 
 # ✨ Introduction
 
-**BetterModel** is a server-based engine that provides runtime BlockBench model rendering & animating for Minecraft Java Edition.
+**BetterModel** is a server-based engine that provides runtime [BlockBench](https://www.blockbench.net/) model rendering & animating for Minecraft Java Edition.
 
-It implements **fully server-side 3D models** by using an item display entity packet.
-
-- Importing Generic BlockBench model `.bbmodel`
-- Auto-generating resource pack
-- Playing animation
-- Syncing with base entity
-- Custom hit box
-- 12-limb player animation
+- Built on the `item-display` packet.
+- Implements **essential BlockBench elements**, including `cubes`, `meshes`, `null objects`, and `locators`.
+- Support for **model animations**, `Molang` expressions, and **IK** (Inverse Kinematics) rigging.
+- Supports **player skin models** and **custom armor**.
+- **Automated resource pack generation** with **zero reliance on core shaders**.
+- Provides support for **entity syncing**.
+- **Extensible API** available for integration.
 
 <details>
 <summary>In-Game Screenshots</summary>
@@ -56,26 +55,26 @@ BetterModel aims to be a reliable engine that provides stable, high-quality anim
 
 ## 🛠️ Build info
 
-[![](https://img.shields.io/badge/minecraft-1.21%7E1.21.11-8FCA5C)](https://www.minecraft.net/en-us/download/server)
-[![](https://img.shields.io/badge/java-21%7E-ED8B00)](https://adoptium.net/)
+[![](https://img.shields.io/badge/minecraft-1.21.4%7E26.2.x-8FCA5C)](https://www.minecraft.net/en-us/download/server)
+[![](https://img.shields.io/badge/java-25%7E-ED8B00)](https://adoptium.net/)
 
 #### Build
 [![](https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/built-with/gradle_vector.svg)](https://gradle.org/)
 
 `./gradlew build`: Builds all jars  
 `./gradlew shadowJar`: Builds plugin jar  
-`./gradlew javadocJar`: Builds javadoc jar  
+`./gradlew javadocJar`: Builds Javadoc jar  
 `./gradlew runServer`: Runs Paper test server with test plugin
 
 #### Library
 - [Kotlin stdlib](https://github.com/JetBrains/kotlin): modern functional programming
-- [semver4j](https://github.com/vdurmont/semver4j): semver parser
+- [semver4j](https://github.com/semver4j/semver4j): semver parser
 - [cloud](https://github.com/Incendo/cloud-minecraft): command
-- [adventure](https://github.com/KyoriPowered/adventure): component
-- [stable player display](https://github.com/bradleyq/stable_player_display): player animation
+- [adventure](https://github.com/PaperMC/adventure): component
 - [caffeine](https://github.com/ben-manes/caffeine): concurrent map cache
 - [DynamicUV](https://github.com/toxicity188/DynamicUV): player model
 - [ArmorModel](https://github.com/toxicity188/ArmorModel): armor in player model
+- [java-mesh](https://github.com/toxicity188/java-mesh): mesh rendering
 - [molang-compiler](https://github.com/Ocelot5836/molang-compiler): compiling and evaluating molang expression
 - [libby](https://github.com/AlessioDP/libby): runtime library downloader
 
@@ -110,7 +109,7 @@ repositories {
 
 dependencies {
     compileOnly("io.github.toxicity188:bettermodel-bukkit-api:VERSION") // bukkit(spigot, paper, etc) api
-    //modApi("io.github.toxicity188:bettermodel-fabric:VERSION") // mod(fabric)
+    //api("io.github.toxicity188:bettermodel-fabric:VERSION") // mod(fabric)
 }
 ```
 
@@ -129,7 +128,7 @@ repositories {
 
 dependencies {
     compileOnly("io.github.toxicity188:bettermodel-bukkit-api:VERSION-SNAPSHOT") // bukkit(spigot, paper, etc) api
-    //modApi("io.github.toxicity188:bettermodel-fabric:VERSION-SNAPSHOT") // mod(fabric)
+    //api("io.github.toxicity188:bettermodel-fabric:VERSION-SNAPSHOT") // mod(fabric)
 }
 ```
 </details>
@@ -147,7 +146,7 @@ repositories {
 
 dependencies {
     compileOnly 'io.github.toxicity188:bettermodel-bukkit-api:VERSION' // bukkit(spigot, paper, etc) api
-    //modApi 'io.github.toxicity188:bettermodel-fabric:VERSION' // mod(fabric)
+    //api 'io.github.toxicity188:bettermodel-fabric:VERSION' // mod(fabric)
 }
 ```
 
@@ -167,7 +166,7 @@ repositories {
 
 dependencies {
     compileOnly 'io.github.toxicity188:bettermodel-bukkit-api:VERSION-SNAPSHOT' // bukkit(spigot, paper, etc) api
-    //modApi 'io.github.toxicity188:bettermodel-fabric:VERSION-SNAPSHOT' // mod(fabric)
+    //api 'io.github.toxicity188:bettermodel-fabric:VERSION-SNAPSHOT' // mod(fabric)
 }
 ```
 </details>

diff --git a/api/bukkit-api/build.gradle.kts b/api/bukkit-api/build.gradle.kts
@@ -4,5 +4,5 @@ plugins {
 }
 
 dependencies {
-    api(project(":api"))
+    api(project(":bettermodel-api"))
 }
diff --git a/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/BetterModelBukkit.java b/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/BetterModelBukkit.java
@@ -1,9 +1,10 @@
-/**
+/*
  * This source file is part of BetterModel.
- * Copyright (c) 2024–2026 toxicity188
+ * Copyright (c) 2026 toxicity188
  * Licensed under the MIT License.
  * See LICENSE.md file for full license text.
  */
+
 package kr.toxicity.model.api.bukkit;
 
 import kr.toxicity.model.api.BetterModel;

diff --git a/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/BukkitModelEventBus.java b/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/BukkitModelEventBus.java
@@ -1,9 +1,10 @@
-/**
+/*
  * This source file is part of BetterModel.
- * Copyright (c) 2024–2026 toxicity188
+ * Copyright (c) 2026 toxicity188
  * Licensed under the MIT License.
  * See LICENSE.md file for full license text.
  */
+
 package kr.toxicity.model.api.bukkit;
 
 import kr.toxicity.model.api.BetterModelEventBus;

diff --git a/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/entity/BaseBukkitEntity.java b/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/entity/BaseBukkitEntity.java
@@ -1,9 +1,10 @@
-/**
+/*
  * This source file is part of BetterModel.
- * Copyright (c) 2024–2026 toxicity188
+ * Copyright (c) 2026 toxicity188
  * Licensed under the MIT License.
  * See LICENSE.md file for full license text.
  */
+
 package kr.toxicity.model.api.bukkit.entity;
 
 import kr.toxicity.model.api.bukkit.platform.BukkitAdapter;

diff --git a/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/entity/BaseBukkitPlayer.java b/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/entity/BaseBukkitPlayer.java
@@ -1,9 +1,10 @@
-/**
+/*
  * This source file is part of BetterModel.
- * Copyright (c) 2024–2026 toxicity188
+ * Copyright (c) 2026 toxicity188
  * Licensed under the MIT License.
  * See LICENSE.md file for full license text.
  */
+
 package kr.toxicity.model.api.bukkit.entity;
 
 import kr.toxicity.model.api.bukkit.platform.BukkitPlayer;

diff --git a/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/entity/package-info.java b/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/entity/package-info.java
@@ -0,0 +1,25 @@
+/*
+ * This source file is part of BetterModel.
+ * Copyright (c) 2024 toxicity188
+ * Licensed under the MIT License.
+ * See LICENSE.md file for full license text.
+ */
+
+/**
+ * Contains Bukkit-backed entity wrappers for BetterModel.
+ * <p>
+ * The wrappers in this package adapt Bukkit entities and players to the
+ * platform-neutral entity contracts from the base API module. They let model
+ * trackers, renderers, and managers work with Bukkit runtime objects through the
+ * shared {@code BaseEntity} and {@code BasePlayer} abstractions.
+ * </p>
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * BaseBukkitEntity entity = ...;
+ * var bukkitEntity = entity.entity();
+ * }</pre>
+ *
+ * @since 3.2.0
+ */
+package kr.toxicity.model.api.bukkit.entity;
diff --git a/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/event/BetterModelBukkitEvent.java b/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/event/BetterModelBukkitEvent.java
@@ -1,9 +1,10 @@
-/**
+/*
  * This source file is part of BetterModel.
- * Copyright (c) 2024–2026 toxicity188
+ * Copyright (c) 2026 toxicity188
  * Licensed under the MIT License.
  * See LICENSE.md file for full license text.
  */
+
 package kr.toxicity.model.api.bukkit.event;
 
 import kr.toxicity.model.api.event.ModelEvent;

diff --git a/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/event/BukkitEventApplication.java b/api/bukkit-api/src/main/java/kr/toxicity/model/api/bukkit/event/BukkitEventApplication.java
@@ -1,9 +1,10 @@
-/**
+/*
  * This source file is part of BetterModel.
- * Copyright (c) 2024–2026 toxicity188
+ * Copyright (c) 2026 toxicity188
  * Licensed under the MIT License.
  * See LICENSE.md file for full license text.
  */
+
 package kr.toxicity.model.api.bukkit.event;
 
 import kr.toxicity.model.api.event.ModelEventApplication;