> 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/model-workflow.md).

# model workflow

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

## 🎨 3D Model Creation Workflow

Creating visual 3D weapon assets for KbAnimation requires modeling and animating within Blockbench, exporting, and compiling config variables.

{% stepper %}
{% step %}

### Step 1: Setup Blockbench Project

1. Open [**Blockbench**](https://www.blockbench.net/).
2. Choose the **Generic Model** format.
3. Set project properties and begin building your weapon mesh.
   {% endstep %}

{% step %}

### Step 2: Naming Bones & Groups

Bone organization is critical since KbAnimation targets individual bones for toggling attachments and firing muzzle flash meshes. Design guidelines:

* Create specific bones for attachments you want to show or hide dynamically (e.g. `optic.reflex`, `suppressor.tgp_a`, `grip.vertical`, `mag_extended`).
* Define a dedicated mesh bone for muzzle flashes (usually named `aim`, `muzzle_flash`, or similar).
* Keep left and right hands grouped independently to enable separate recoil translation effects.

#### Using Custom Player Arm Skins (Dynamic Arms)

KbAnimation supports rendering the player's own skin on the 3D model's arms. To enable this, apply the following bone tags to the corresponding bone groups in Blockbench:

* **`fpra` (Full Player Right Arm)**: Renders the player's custom right arm skin (automatically switches width for normal or slim skin profiles).
* **`fpla` (Full Player Left Arm)**: Renders the player's custom left arm skin.
* **`gpra` (Gun Player Right Arm)**: Renders the right arm skin scaled at `1.5` times height (optimized for holding weapon models).
* **`gpla` (Gun Player Left Arm)**: Renders the left arm skin scaled at `1.5` times height.
* **`fh` (Head)**: Renders the player's head.
* **`air` or `emp`**: Hides the bone entirely.

When BetterModel parses these bone tags, it dynamically wraps the player's active skin on the 3D meshes at runtime.\
\
[`Hands.bbmodel`](https://www.dropbox.com/scl/fi/bqi12iro11k5uan9tyuvg/wikihands.bbmodel?rlkey=p11y11wcijot3h2scy9h55eys\&st=ng0nvffn\&dl=0)
{% endstep %}

{% step %}

### Step 3: Creating Keyframe Animations

Animations are generated using keyframes in the Blockbench Animation workspace. The following animation names are parsed by the plugin:

| Animation Name      | Trigger Action                               | Type       | Suggested Loop           |
| ------------------- | -------------------------------------------- | ---------- | ------------------------ |
| `equip`             | Triggered when player swaps to the item      | One-time   | No                       |
| `standing`          | Default idle position while holding gun      | Continuous | Yes                      |
| `sprint`            | Triggered when player sprints                | Continuous | Yes                      |
| `reload`            | Weapon reloading sequence                    | One-time   | No (Plugin scales speed) |
| `shoot`             | Hip-fire recoil kickback                     | One-time   | No                       |
| `aiming` / `zoom`   | Aim Down Sights (ADS) idle stance            | Continuous | Yes                      |
| `aiming_shoot`      | Recoil kickback while scoped in ADS          | One-time   | No                       |
| `check` / `inspect` | Weapon check (triggered by drop at full mag) | One-time   | No                       |
| `unequip`           | Put away weapon animation (see warning)      | One-time   | No                       |
| `slash`             | Attack animation (Melee weapons only)        | One-time   | No                       |

{% hint style="warning" %}
⚠️ **Unequip Animation Note:** If your configuration does NOT specify an `unequip` animation, the weapon model will vanish instantly when swapped. If defined, the plugin delays item switching slightly (default 10 ticks) to play the full put-away movement before removing the entity.
{% endhint %}
{% endstep %}

{% step %}

### Step 4: Exporting and Registering

1. Save and export your model file (`.bbmodel`).
2. Upload your model folder to BetterModel's directory.
3. Run `/bettermodel reload` in-game to compile the new model ID.
4. Map this model ID in your KbAnimation model configuration (detailed on the next page).

> 📸 **📸 \[Insert Blockbench modeling and animation hierarchy screenshot here]** *Displays bone groups and timeline channels for equip/reload keyframes*
> {% endstep %}
> {% endstepper %}
> {% endtab %}

{% tab title="TH" %}

## 🎨 ขั้นตอนการทำโมเดล 3 มิติ

การสร้างไฟล์โมเดลปืน 3 มิติเพื่อไปใช้กับแอนิเมชันในเกม จะดำเนินการผ่านโปรแกรม Blockbench โดยแบ่งเป็นขั้นตอนการแบ่งโครงกระดูกปืน และการทำแอนิเมชันดังนี้:

{% stepper %}
{% step %}

### ขั้นตอนที่ 1: ตั้งค่าโปรเจกต์ใน Blockbench

1. เปิดโปรแกรม [**Blockbench**](https://www.blockbench.net/)
2. สร้างโปรเจกต์ใหม่แบบ **Generic Model**
3. กำหนดขนาดโปรเจกต์และเริ่มสร้างโมเดลรูปทรงปืนของคุณ
   {% endstep %}

{% step %}

### ขั้นตอนที่ 2: การแยกชิ้นส่วนโครงกระดูก (Bones & Groups)

การจัดชื่อกลุ่มกระดูก (Bones) เป็นเรื่องสำคัญมาก เพราะ KbAnimation จะสั่งซ่อน/แสดงกระดูกตามระดับของแต่งปืนที่เรากดสวมใส่:

* แยกชิ้นส่วนของแต่งปืน เช่น ลำกล้องเก็บเสียง (`suppressor.tgp_a`), กล้องเล็ง (`optic.1p87`), ด้ามจับ (`grip.rk_0`) และแม็กกาซีนปืน ออกมาเป็นกระดูกต่างหาก เพื่อใช้ปิด/เปิดเวลากดแต่งปืน
* สร้างกระดูกเปล่าหรือวัตถุตรงปลายกระบอกปืนเพื่อทำเป็นช่องไฟปากกระบอกปืน (มักจะตั้งชื่อว่า `aim` หรือ `muzzle_flash`)
* แบ่งโมเดลของมือซ้ายและมือขวาแยกออกจากตัวปืน เพื่อจำลองท่าทางการจับและการถอดแม็กกาซีน

#### การแสดงผลสกินแขนของผู้เล่นจริง (Dynamic Player Arms)

หากต้องการให้โมเดลปืน 3 มิติแสดงส่วนแขนที่เป็นสกินของตัวผู้เล่นที่กำลังถือปืนจริง ๆ คุณสามารถตั้งชื่อหรือติดแท็กกระดูก (Bone Tags) ชิ้นส่วนแขนใน Blockbench ด้วยรหัสดังต่อไปนี้:

* **`fpra` (Full Player Right Arm)**: แสดงสกินแขนขวาของผู้เล่น (รองรับการสลับขนาดอัตโนมัติหากผู้เล่นใช้สกินแบบปกติหรือแบบเรียว/Slim)
* **`fpla` (Full Player Left Arm)**: แสดงสกินแขนซ้ายของผู้เล่น
* **`gpra` (Gun Player Right Arm)**: แสดงสกินแขนขวาของผู้เล่นแบบขยายสเกลความยาว `1.5` เท่า (ปรับสัดส่วนให้เหมาะสมกับท่าทางตอนถือปืน)
* **`gpla` (Gun Player Left Arm)**: แสดงสกินแขนซ้ายของผู้เล่นแบบขยายสเกลความยาว `1.5` เท่า
* **`fh` (Head)**: แสดงสกินหัวของผู้เล่น
* **`air` หรือ `emp`**: ซ่อนชิ้นส่วนกระดูกชิ้นนั้น ๆ ให้โปร่งใส

เมื่อปลั๊กอินตรวจพบแท็กเหล่านี้ ระบบจะดึงภาพสกินที่แท้จริงของผู้เล่นมาหุ้มลงบนโมเดลแขน 3 มิติโดยอัตโนมัติในทันที\
\
[`Hands.bbmodel`](https://www.dropbox.com/scl/fi/bqi12iro11k5uan9tyuvg/wikihands.bbmodel?rlkey=p11y11wcijot3h2scy9h55eys\&st=ng0nvffn\&dl=0)
{% endstep %}

{% step %}

### ขั้นตอนที่ 3: การทำแอนิเมชันใน Blockbench

คุณต้องไปที่หน้าต่าง Animation และสร้างคีย์เฟรมจำลองท่าทางปืนตามชื่อที่ปลั๊กอินกำหนดไว้ ดังนี้:

| ชื่อแอนิเมชันในโปรแกรม | เหตุการณ์ที่แอนิเมชันทำงาน                       | ประเภทการเล่น  | คำแนะนำการลูป                          |
| ---------------------- | ------------------------------------------------ | -------------- | -------------------------------------- |
| `equip`                | เล่นตอนดึงปืนขึ้นมาถือ                           | เล่นครั้งเดียว | ไม่ต้องลูป (No)                        |
| `standing`             | ท่าส่ายปืนเบาๆ ตอนยืนนิ่งๆ                       | เล่นวนซ้ำ      | **ต้องลูป (Yes)**                      |
| `sprint`               | แอนิเมชันกดปืนลงต่ำตอนวิ่ง                       | เล่นวนซ้ำ      | **ต้องลูป (Yes)**                      |
| `reload`               | ท่าเปลี่ยนซองกระสุน                              | เล่นครั้งเดียว | ไม่ต้องลูป (ความเร็วถูกคำนวณอัตโนมัติ) |
| `shoot`                | ปืนถีบ/ถอยหลังเวลายิงปกติ (Hip-fire)             | เล่นครั้งเดียว | ไม่ต้องลูป (No)                        |
| `aiming` / `zoom`      | ท่านิ่งๆ ขณะกดเล็งซูม (ADS)                      | เล่นวนซ้ำ      | **ต้องลูป (Yes)**                      |
| `aiming_shoot`         | ปืนถีบรีคอยล์ตอนเล็งซูมยิง                       | เล่นครั้งเดียว | ไม่ต้องลูป (No)                        |
| `check` / `inspect`    | ท่าเช็กปืน (เกิดจากการกดปุ่ม Drop ตอนกระสุนเต็ม) | เล่นครั้งเดียว | ไม่ต้องลูป (No)                        |
| `unequip`              | ท่าเอาปืนเก็บลง (อ่านคำเตือนด้านล่าง)            | เล่นครั้งเดียว | ไม่ต้องลูป (No)                        |
| `slash`                | ท่าฟันมีด (ใช้กับหมวดมีดระยะประชิด MELEE)        | เล่นครั้งเดียว | ไม่ต้องลูป (No)                        |

{% hint style="warning" %}
⚠️ **คำเตือนเรื่องแอนิเมชัน Unequip (เก็บปืน):** หากคุณไม่กำหนดแอนิเมชัน `unequip` ไว้ในไฟล์ตั้งค่า ตัวโมเดล 3D จะหายวับไปทันทีเมื่อสลับช่องไปถือของชิ้นอื่น แต่หากเขียนกำหนดไว้ ปลั๊กอินจะหน่วงเวลาการสลับของ (เริ่มต้นที่ 10 ticks) เพื่อปล่อยให้แอนิเมชันเอาปืนลงล่างเล่นจนเสร็จก่อนจะนำโมเดลออก
{% endhint %}
{% endstep %}

{% step %}

### ขั้นตอนที่ 4: การส่งออกไฟล์และนำเข้าเกิม

1. บันทึกและส่งออกไฟล์ของคุณเป็น `.bbmodel`
2. นำไฟล์โมเดลไปใส่ในโฟลเดอร์โมเดลของปลั๊กอิน BetterModel
3. เข้าเกมแล้วพิมพ์คำสั่ง `/bettermodel reload` เพื่อโหลดข้อมูลโมเดลใหม่
4. จดจำ Model ID ของปืนนั้นๆ เพื่อนำไปผูกค่าในไฟล์ตั้งค่าของ KbAnimation ในบทถัดไป

> 📸 **📸 \[รูปสกรีนช็อตหน้าจอโปรแกรม Blockbench แสดงกลุ่มกระดูกและแกน Timeline ต่างๆ]** *ตัวอย่างการจัดโครงกระดูกของแต่งและคีย์เฟรมการดึงลำกล้องยิง*
> {% endstep %}
> {% endstepper %}
> {% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://kbanimation.gitbook.io/kbanimation/model-workflow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.