toxicity188 · toxicity188 · May 11, 2026 · May 14, 2026 · May 14, 2026 · May 14, 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/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -2,23 +2,22 @@
 
 Thanks for considering contributing!
 
-* **Step 1.** Forks BetterModel to your repository.
-* **Step 2.** Commits your change.
-* **Step 3.** Opens pull request at 'dev' branch.
-* **Step 4.** Waits for merging or reviewing
+* **Step 1.** Fork BetterModel to your repository.
+* **Step 2.** Commit your changes.
+* **Step 3.** Open a pull request against the `v3-dev` branch.
+* **Step 4.** Wait for review and merging.
 
-## Rule
-* I can't handle a huge change about API module.  
-* You should note that type of your PR. (e.g., `Bug fix` / `API update`)   
-* You should inform your features that what you want to merge by this way.
-```
-Document
-Image
-Video
-```
+## Rules
+* **No AI-generated code:** Pull requests containing fully or primarily AI-generated code will not be accepted. Contributions must be written by human contributors.
+* I can't handle huge changes to the API module.
+* Specify the type of your PR in the description (e.g., `Bug fix`, `API update`).
+* Clearly demonstrate your changes using one of the following:
+    * Documentation
+    * Images / Screenshots
+    * Video demonstrations
 
 ## 📄 Commit Message Format
-Use present tense: `fix:`, `feat:`, `docs:`, etc.
+Use present tense conventional commits: `fix:`, `feat:`, `docs:`, etc.
 
 ## 📜 License
-Contributions are under the MIT License.
+Contributions are licensed under the MIT License.
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/setup-java@v5
+      - uses: actions/checkout@v7
+      - name: Set up JDK 25
+        uses: actions/setup-java@v6
         with:
-          java-version: '21'
+          java-version: '25'
           distribution: 'temurin'
       - name: Grant execute permission for gradlew
         run: chmod +x gradlew
@@ -35,7 +35,7 @@ jobs:
             -H "Accept: application/vnd.github+json" \
             https://api.github.com/repos/${{ github.repository }}/deployments \
             -d '{
-              "ref": "master",
+              "ref": "v3",
               "auto_merge": false,
               "required_contexts": [],
               "payload": "{ \"timestamp\": \"'$(date +%s)'\" }",

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
-        uses: actions/setup-java@v5
+      - name: Set up JDK 25
+        uses: actions/setup-java@v6
         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/setup-java@v5
+      - uses: actions/checkout@v7
+      - name: Set up JDK 25
+        uses: actions/setup-java@v6
         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,11 +67,11 @@ 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.3.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)
+[![](https://img.shields.io/badge/folia-✔-blue?style=for-the-badge)](https://papermc.io/downloads/folia)
 
 [![](https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/supported/paper_vector.svg)](https://papermc.io/downloads/paper)
 [![](https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/supported/purpur_vector.svg)](https://purpurmc.org/download/purpur)

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
@@ -9,6 +9,7 @@
 [![](https://img.shields.io/github/actions/workflow/status/toxicity188/BetterModel/publish.yml?style=flat-square)](https://modrinth.com/plugin/bettermodel/versions)
 [![](https://img.shields.io/github/issues/toxicity188/BetterModel?style=flat-square&logo=github)](https://github.com/toxicity188/BetterModel/issues)
 [![](https://img.shields.io/bstats/servers/24237?style=flat-square)](https://bstats.org/plugin/bukkit/BetterModel/24237)
+[![](https://www.codefactor.io/repository/github/toxicity188/bettermodel/badge?style=flat-square)](https://www.codefactor.io/repository/github/toxicity188/bettermodel)
 
 </div>
 
@@ -21,16 +22,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 +56,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.3.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 +110,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 +129,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 +147,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 +167,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;
@@ -21,6 +22,15 @@
  * for scheduling and entity adaptation.
  * </p>
  *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * BetterModelBukkit platform = BetterModelBukkit.platform();
+ * BukkitModelScheduler scheduler = platform.scheduler();
+ * if (BetterModelBukkit.IS_FOLIA) {
+ *     // Folia region-aware scheduling
+ * }
+ * }</pre>
+ *
  * @since 2.0.0
  */
 public interface BetterModelBukkit extends BetterModelPlatform {

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;
@@ -21,6 +22,14 @@
  * This interface provides convenience methods for subscribing to events using a Bukkit {@link Plugin} instance.
  * </p>
  *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * BukkitModelEventBus eventBus = BetterModelBukkit.platform().eventBus();
+ * eventBus.subscribe(plugin, ModelEvent.class, event -> {
+ *     // Handle Bukkit event
+ * });
+ * }</pre>
+ *
  * @since 2.0.0
  */
 public interface BukkitModelEventBus extends BetterModelEventBus {