> For the complete documentation index, see [llms.txt](https://kbanimation.gitbook.io/kbanimation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kbanimation.gitbook.io/kbanimation/home.md).

# HOME

{% tabs %}
{% tab title="EN" %}

## 🎯 KbAnimation Wiki

**First-Person 3D Weapon Animation & Dynamic 3D Camera Addon for WeaponMechanics**

KbAnimation is an all-in-one Minecraft plugin that brings AAA FPS-style (Call of Duty / Modern Warfare) first-person 3D weapon animations, dynamic 3D camera animations, and a fully-featured HUD system to servers running WeaponMechanics. It utilizes BetterModel for rendering Blockbench models in-game, Vanilla Multi-Version CoreShaders for wall-clipping prevention and true 3D camera rotations, pure Java NMS shader markers for realistic 3D camera recoil/sway, and BetterHud for displaying ammo counters, crosshairs, fire mode indicators, damage direction arrows, hit markers, kill feed, and weapon stat bars.

{% hint style="info" %}
⚡ **Version:** 1.1.8 | **API:** 1.21.4+ (1.21.4, 1.21.11 format 75, 26.x / Folia format 76+) | **Author:** koome
{% endhint %}

### ✨ Core Features

* **3D Animation System:** Handles equip, standing (idle), sprint, reload, hip-fire, ADS-aiming, ADS-shoot, inspect, melee, and unequip animations directly from Blockbench Generic Models.
* **Cinematic 3D 3D Camera Engine:** Pure Java 3D camera engine that automatically extracts camera rotation keyframes (`camera`, `camera_roll`, `cam`, `view`) from `.bbmodel` animations and renders cinematic roll, pitch, and yaw movement in-game with zero lag.
* **Zero Black Borders Overscan Compensation:** Mathematical dynamic crop scaling (`cropScale`) and Catmull-Rom subpixel texture sampling eliminate black border cutoffs when the camera rolls or pitches.
* **Strict Motion Detection:** Only animations that explicitly contain motion keyframes in their camera bone will move the player's camera; weapons and animations without camera keyframes remain perfectly steady.
* **Multi-Version No-Clip CoreShaders:** Automatically generates and installs GLSL core shaders across `assets/`, `overlay_1_21_4`, `overlay_1_21_11`, and `overlay_26_2` to compress viewmodel depth (`0.001` depth factor with 70.0° fixed FOV), preventing weapons and arms from clipping into solid blocks and walls.
* **Full Folia & Paper Compatibility:** Fully threaded and native support for Folia Regionized Server, Paper, Purpur, and Spigot on 1.21.4+.
* **Attachment System:** Visual attachment toggling (shows/hides model bones), conflict groups, and an in-game customization overlay.
* **BetterHud & PAPI:** Custom native HUD overlays, crosshairs, direction indicators, damage direction markers, and PvP/PvE Kill Feeds.

### 📖 Wiki Sections

1. [Requirements & Installation](broken://pages/186d14f36159e6045969183782de518472fe75b4) - Server setup, required dependencies, and multi-version shader sync.
2. [3D Model Creation Workflow](broken://pages/4cd5bfd7087b34c2903c31c6e308dff3dab64bd6) - Designing weapons, arm skins, and 3D camera animations in Blockbench.
3. [Weapon Model Configuration](broken://pages/e31eb53ffe338bca3a90f3a970376b4fe27a85f8) - Configuring animations, camera bones, and scales in YML files.
4. [Attachment System](broken://pages/dc240169810d4b4653d7104575f1be39ffb4c961) - Attachment bone maps, speed scaling, customization screen.
5. [Visual Effects & Shaders](broken://pages/1a9d1a9c9d955a45d3515a1a27346016e7c31b46) - Multi-version CoreShaders, 3D camera ray reprojection, muzzle flashes, and bullet holes.
6. [Main Configuration](broken://pages/3e53c3252df9ccbfba9430f680511936b688d488) - Main plugin config.yml reference.
7. [BetterHud Integration](broken://pages/40a0ccf9cc80a5e14b0590e0240cb9eeaf291fe9) - Native placeholders, layout parameters, UI variables.
8. [Commands & Permissions](broken://pages/decc94fd53be2417d7e2f5457ee50ff07f5a1895) - Administrator commands and permission node map.
9. [Language & Translation](broken://pages/f4f8c072d7fe0ab73611d5bd8a099bb5b8ce3837) - Setting up custom translations and message keys.
10. [FAQ & Troubleshooting](broken://pages/b9e863a86195d09766488fb232e600f777ba0bf3) - Solution guide for common issues and shader troubleshooting.
11. [Developer API Guide](broken://pages/a9d94cfe4643987f8da4964979e1e9086eff2386) - Integrating other plugins with KbAnimation.
    {% endtab %}

{% tab title="TH" %}

## 🎯 ยินดีต้อนรับสู่คู่มือ KbAnimation

**ปลั๊กอินแอนิเมชันอาวุธ 3 มิติมุมมองบุคคลที่หนึ่ง, มุมกล้อง 3 มิติ (Cinematic 3D) และระบบ HUD สำหรับ WeaponMechanics**

KbAnimation เป็นปลั๊กอิน Minecraft ตัวช่วยอัปเกรดเซิร์ฟเวอร์แนวปืน ให้มีแอนิเมชันระดับเกมยิงปืนชั้นนำ (สไตล์ Call of Duty / Modern Warfare) พร้อมระบบมุมกล้อง 3 มิติแบบ Cinematic และระบบ HUD เต็มรูปแบบ โดยปลั๊กอินใช้ **BetterModel** ในการเรนเดอร์โมเดลจาก Blockbench, ใช้ระบบ **Multi-Version CoreShader** ป้องกันปืนทะลุกำแพงและคำนวณการหมุนมุมมองกล้อง 3 มิติ (Roll, Pitch, Yaw), ระบบสตรีมมุมกล้อง 3D จากกระดูกโมเดลอัตโนมัติ และใช้งานร่วมกับ **BetterHud** ในการโชว์จำนวนกระสุน, เป้าเล็งปืน (Crosshair), แสดงโหมดการยิง, แสดงทิศทางที่โดนยิง, เป้ากระพริบเวลายิงโดน (Hit Marker), การแจ้งเตือนฆ่า (Kill Feed) และแถบพลังความแรงปืนขณะแต่งปืน

{% hint style="info" %}
⚡ **เวอร์ชัน:** 1.1.8 | **รองรับ Minecraft:** 1.21.4+ (1.21.4, 1.21.11 format 75, 26.x / Folia format 76+) | **ผู้พัฒนา:** koome
{% endhint %}

### ✨ คุณสมบัติหลัก (Core Features)

* **ระบบแอนิเมชัน 3 มิติ:** รองรับท่าดึงปืน (equip), ท่ายืนถือปืน (standing), ท่าวิ่ง (sprint), ท่าบรรจุกระสุน (reload), ท่ายิงปกติ, ท่าเล็งยิง (ADS), ท่าตรวจสอบปืน (inspect), ท่าฟันมีด (melee) และท่าเก็บปืน (unequip)
* **ระบบมุมกล้อง 3 มิติแบบ Cinematic 3D (3D Camera CoreShader Engine):** ตรวจจับกระดูกกล้อง (`camera`, `camera_roll`, `cam`, `view`) ในไฟล์ Blockbench `.bbmodel` และสตรีมมุมเอียงกล้อง (Roll, Pitch, Yaw) ให้มุมมองผู้เล่นขยับตามท่าทางอย่างสมจริงและลื่นไหล 20Hz โดยผู้เล่นไม่ต้องลงม็อดใดๆ
* **ไร้ขอบดำที่ขอบจอ (Zero Black Borders):** ใช้ระบบ Mathematical Dynamic Crop Scaling (`cropScale`) ขยายชดเชยการเอียงมุมกล้องอัตโนมัติ ร่วมกับ Catmull-Rom Subpixel Filtering ทำให้ไม่มีขอบดำหรือแถบตัดที่ขอบจอ
* **ระบบตรวจจับกระดูกแบบแม่นยำ (Strict Motion Detection):** เล่นมุมกล้องเฉพาะปืนและท่าทางที่มีการขยับ Keyframe ในกระดูกกล้องจริงเท่านั้น หากปืนไหนไม่มีกระดูกกล้อง หรือมีค่าเป็น 0 มุมมองจะนิ่งสนิทตามปกติ
* **ระบบป้องกันปืนทะลุกำแพงแบบหลายเวอร์ชัน (Multi-Version No-Clip CoreShaders):** สร้างและติดตั้ง Core Shader จัดการ Depth Buffer (`0.001` factor) และล็อก FOV 70.0° อัตโนมัติ ครอบคลุมทั้ง 1.21.4, 1.21.11 และ 26.x ป้องกันไม่ให้ปืนและแขน 3D ทะลุเข้าไปในบล็อกหรือกำแพง
* **รองรับ Folia & Paper 100%:** รองรับเซิร์ฟเวอร์ Folia (Regionized Threading), Paper, Purpur และ Spigot ทำงานได้อย่างสมบูรณ์แบบ
* **ระบบแต่งปืนแบบสมจริง (Attachment System):** ซ่อนหรือแสดงชิ้นส่วนกระดูก (Bones) บนปืนตามของแต่งที่ใส่จริง, มีโหมดแต่งปืนกลางหน้าจอ (Customization mode) พร้อมระบบล็อกการเคลื่อนที่
* **ระบบแสดงผล HUD (BetterHud & PAPI):** เป้าเล็งแบบเงื่อนไข (ซ่อนเมื่อเล็งซูม), แสดงทิศทางกระสุนที่ยิงโดนตัวเรา, แสดงไอคอนโหมดการยิง Auto/Burst/Semi, ระบบแจ้งเตือนการคิล

### 📖 สารบัญคู่มือการใช้งาน

1. [การติดตั้งและสิ่งที่จำเป็น (Installation)](broken://pages/186d14f36159e6045969183782de518472fe75b4) - ตรวจสอบความต้องการระบบ, ปลั๊กอินที่ต้องใช้ และการซิงก์ CoreShader หลายเวอร์ชัน
2. [การทำโมเดล 3 มิติ (Model Creation)](broken://pages/4cd5bfd7087b34c2903c31c6e308dff3dab64bd6) - การสร้างปืน, สกินแขนผู้เล่น และการอนิเมตมุมกล้อง 3D ใน Blockbench
3. [การตั้งค่าโมเดลอาวุธ (Model Config)](broken://pages/e31eb53ffe338bca3a90f3a970376b4fe27a85f8) - อธิบายไฟล์ตั้งค่าปืนแต่ละกระบอกในโฟลเดอร์ models
4. [ระบบแต่งปืน (Attachment System)](broken://pages/dc240169810d4b4653d7104575f1be39ffb4c961) - วิธีกำหนดชิ้นส่วนของแต่ง, ความเร็วแอนิเมชัน และปุ่มควบคุมโหมดแต่งปืน
5. [เอฟเฟกต์ภาพและ Shaders (Visual Effects)](broken://pages/1a9d1a9c9d955a45d3515a1a27346016e7c31b46) - รายละเอียด CoreShader 3 มิติ, ระบบป้องกันปืนทะลุกำแพง, แสงไฟปากกระบอกปืน และรอยกระสุน
6. [การตั้งค่าหลัก (Main Config)](broken://pages/3e53c3252df9ccbfba9430f680511936b688d488) - รายละเอียดในไฟล์ config.yml ของปลั๊กอินหลัก
7. [การเชื่อมโยงกับ BetterHud (HUD Setup)](broken://pages/40a0ccf9cc80a5e14b0590e0240cb9eeaf291fe9) - ตัวแปร (Placeholders) ทั้งหมดที่นำไปแต่ง UI รวมถึงตัวอย่างไฟล์ HUD
8. [คำสั่งและสิทธิ์การใช้งาน (Commands & Perms)](broken://pages/decc94fd53be2417d7e2f5457ee50ff07f5a1895) - รายชื่อคำสั่งแอดมินและการจำกัดสิทธิ์ผู้เล่น
9. [ระบบภาษาไทย/EN (Language System)](broken://pages/f4f8c072d7fe0ab73611d5bd8a099bb5b8ce3837) - วิธีแก้ไขข้อความแจ้งเตือนต่างๆ ให้รองรับหลายภาษา
10. [คำถามที่พบบ่อยและวิธีแก้ไข (FAQ)](broken://pages/b9e863a86195d09766488fb232e600f777ba0bf3) - รวบรวมแนวทางแก้ไขปัญหาต่างๆ เช่น มุมกล้อง 3D, การรองรับ Folia, บั๊กโหมดไฟ เป็นต้น
11. [คู่มือพัฒนาโปรแกรมด้วย Developer API](broken://pages/a9d94cfe4643987f8da4964979e1e9086eff2386) - แนะนำการนำ API ไปเขียนเชื่อมกับปลั๊กอินอื่นๆ
    {% endtab %}
    {% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://kbanimation.gitbook.io/kbanimation/home.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.