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

# attachments

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

## 🔩 Weapon Attachment System

The attachment system connects WeaponMechanics items to 3D bones inside your Blockbench model. When players equip attachment items, corresponding bones toggle visible, other bones hide, and animation speeds modify automatically.

### Attachment Section YAML

Define your attachments at the bottom of the weapon configuration file:

```yaml
attachments:
  "Suppressor":                        # Exact attachment name from WeaponMechanics
    bone: "suppressor.tgp_a"           # Model bone name to show
    hide-muzzle-flash: true            # Suppress muzzle lights
    hide-bones:                        # Hide default parts when this is equipped
      - "aim"                          # Hides default iron sight tip
    group: "MUZZLE"                    # Conflict group name
    offset-x: 0.0                      # Offset position translations when equipped
    offset-y: 0.0
    offset-z: 0.0
    speed: 1.0                         # Global animation speed multiplier
    animations:                        # Per-animation speed overrides
      reload: 1.25                     # Reload 25% faster when equipped
  "High_Capacity_Magazine":
    bone: "mag_extended_1"
    hide-bones:
      - "maggg"
    group: "MAG"
    speed: 0.9                         # Reload/actions slightly slower due to weight
```

### Attachment Fields Reference

| Variable Name       | Type    | Default   | Description                                                                       |
| ------------------- | ------- | --------- | --------------------------------------------------------------------------------- |
| `bone`              | String  | None      | Name of the bone in Blockbench to make visible when equipped.                     |
| `group`             | String  | `default` | Attachments with matching groups cannot be equipped at the same time.             |
| `hide-muzzle-flash` | Boolean | `false`   | Set to `true` to disable smoke particles and light flashes (e.g. Silencers).      |
| `hide-bones`        | List    | `[]`      | A list of standard weapon bones to hide when the attachment is active.            |
| `offset-x/y/z`      | Double  | `0.0`     | Offsets the entire model's viewing coordinates while this attachment is on.       |
| `speed`             | Double  | `1.0`     | The global speed multiplier for all animations (equip, standing, reloading, etc). |
| `animations.<type>` | Double  | None      | Specific animation speed modifier (takes precedence over global `speed`).         |

### Animation Speed Calculation

When playing an animation, the final playback speed is compiled as:

```yaml
finalSpeed = baseAnimSpeed × dynamicReloadMultiplier × attachmentMultiplier
```

Where the `attachmentMultiplier` priority behaves as follows:

1. If a specific speed is defined under `animations.<type>` (e.g. `animations.reload: 1.25`) → use that value.
2. Else if a global attachment `speed` is defined → use that value.
3. If neither is set → default to `1.0`.

If multiple attachments are equipped (e.g., Suppressor and Extended Mag), their speed modifiers are **multiplied together**.

### In-Game Customization Mode

Players can enter a visual gun customization screen using a configurable hotkey shortcut. Inside this screen:

* The player is frozen in place, and shooting/reloading is locked.
* **Controls:**
* `Hold attachment item + Left-Click`: Equip the attachment to the gun.
* `Press Swap key (F)`: Cycle through equipped scopes/groups.
* `Empty Hand + Left-Click`: Detach/unequip the selected attachment.

{% hint style="info" %}
ℹ️ **Session Exit Rule:** If the player takes damage or dies, Customization Mode is automatically cancelled/exited, unfreezing their movement instantly.
{% endhint %}
{% endtab %}

{% tab title="TH" %}

## 🔩 ระบบแต่งปืน (Attachment System)

ระบบแต่งปืนจะเชื่อมโยงไอเท็มของแต่งปืนจาก WeaponMechanics เข้ากับกระดูกชิ้นส่วนโมเดล 3D ใน Blockbench เมื่อผู้เล่นใส่ของแต่ง กระดูกชิ้นส่วนของแต่งจะปรากฏขึ้นโดยอัตโนมัติ และสามารถปรับอัตราความเร็วของแอนิเมชันตามน้ำหนักของแต่งได้ด้วย

### โครงสร้างไฟล์ YAML ส่วนของแต่ง

เขียนกำหนดชิ้นส่วนของแต่งปืนไว้ที่หมวดหมู่ `attachments` ด้านล่างสุดของไฟล์ตั้งค่าปืน:

```yaml
attachments:
  "Suppressor":                        # ชื่อไอเท็มของแต่งจาก WeaponMechanics ตรงตัว
    bone: "suppressor.tgp_a"           # ชื่อกระดูกโมเดลใน Blockbench ที่จะโชว์
    hide-muzzle-flash: true            # สั่งปิดไฟปลายกระบอกปืน (เพราะเป็นเก็บเสียง)
    hide-bones:                        # รายการกระดูกที่จะซ่อนเมื่อใส่ของแต่งชิ้นนี้
      - "aim"                          # ซ่อนศูนย์เล็งเหล็กดั้งเดิมเพื่อหลบกระบอกเก็บเสียง
    group: "MUZZLE"                    # กลุ่มประเภทของแต่งปืน (กลุ่มเดียวกันใส่พร้อมกันไม่ได้)
    offset-x: 0.0                      # ปรับตำแหน่งโมเดลปืนใหม่เมื่อสวมใส่ของแต่งนี้
    offset-y: 0.0
    offset-z: 0.0
    speed: 1.0                         # ตัวคูณความเร็วแอนิเมชันทั่วไป
    animations:                        # ปรับแต่งความเร็วเฉพาะแอนิเมชันที่ต้องการ
      reload: 1.25                     # ใส่ปลอกเก็บเสียงนี้แล้วให้เปลี่ยนกระสุนเร็วขึ้น 25%
  "High_Capacity_Magazine":
    bone: "mag_extended_1"             # โชว์กระดูกแม็กกาซีนขยายยาว
    hide-bones:
      - "maggg"                        # ซ่อนแม็กกาซีนอันสั้นปกติ
    group: "MAG"                       # จัดอยู่ในกลุ่มแม็กกาซีน
    speed: 0.9                         # ทำให้การเล่นแอนิเมชันช้าลง 10% เนื่องจากปืนหนักขึ้น
```

### รายละเอียดตารางตัวแปรแต่งปืน

| ชื่อตัวแปร          | ชนิดข้อมูล | ค่าเริ่มต้น | หน้าที่การทำงาน                                                                       |
| ------------------- | ---------- | ----------- | ------------------------------------------------------------------------------------- |
| `bone`              | String     | ไม่มี       | ชื่อกระดูกชิ้นส่วนใน Blockbench ที่ต้องการสั่งแสดงผลเมื่อสวมใส่ไอเท็มนี้.             |
| `group`             | String     | `default`   | รหัสกลุ่มของแต่งปืน ป้องกันบั๊กสวมใส่กล้องเล็งซ้อนกัน (ใส่ได้ชิ้นเดียวต่อหนึ่งกลุ่ม). |
| `hide-muzzle-flash` | Boolean    | `false`     | ตั้งเป็น `true` เพื่อซ่อนเอฟเฟกต์ไฟและควันปากกระบอกปืน (เหมาะสำหรับเก็บเสียง).        |
| `hide-bones`        | List       | `[]`        | รายชื่อกระดูกดั้งเดิมของปืนที่ต้องสั่งซ่อน เพื่อไม่ให้ชนทับกับของแต่งใหม่.            |
| `offset-x/y/z`      | Double     | `0.0`       | พิกัดปรับเลื่อนตำแหน่งปืนแบบละเอียดเมื่อมีการติดตั้งของแต่งนี้.                       |
| `speed`             | Double     | `1.0`       | ตัวคูณความเร็วของแอนิเมชันทุกท่า (ค่าครอบคลุมหากไม่มีตัวเลือกด่านล่าง).               |
| `animations.<type>` | Double     | ไม่มี       | ตัวคูณความเร็วเฉพาะแอนิเมชันนั้นๆ (จะยกเว้นและทับค่า `speed` ด้านบน).                 |

### สูตรการคำนวณความเร็วแอนิเมชัน

เมื่อผู้เล่นทำแอนิเมชัน ความเร็วสุดท้าย (finalSpeed) จะคำนวณดังนี้:

```yaml
finalSpeed = baseAnimSpeed × dynamicReloadMultiplier × attachmentMultiplier
```

โดยลำดับความสำคัญของตัวคูณของแต่ง `attachmentMultiplier` จะอิงดังนี้:

1. หากมีกำหนดค่าความเร็วปืนเฉพาะแอนิเมชัน เช่น `animations.reload: 1.25` → ให้ใช้ค่านี้ก่อน
2. ถ้าไม่มี แต่มีค่าตัวคูณของแต่งแบบทั่วไป เช่น `speed: 0.9` → ให้ดึงค่านั้นมาใช้
3. ถ้าไม่มีการตั้งค่าความเร็วเลย → ใช้ค่าเริ่มต้นคือ `1.0`

หากใส่ของแต่งหลายชิ้นพร้อมกัน (เช่น ปลายปืนและแม็กกาซีน) ตัวคูณความเร็วของแต่ละชิ้นจะถูกนำมา **คูณทวีคูณร่วมกัน**

### ระบบเปิดโหมดแต่งปืนกลางเกม (Customization Mode)

ผู้เล่นสามารถกดคีย์ลัดที่กำหนดไว้ เพื่อสลับเข้าสู่โหมดแต่งอาวุธแบบสมจริง โดยขณะเข้าโหมดนี้:

* ตัวผู้เล่นจะถูกล็อกให้อยู่กับที่ ไม่สามารถเคลื่อนที่, กดยิง หรือกดปุ่มรีโหลดใดๆ ได้
* **วิธีกดเล่น:**
* `ถือไอเท็มของแต่งในมือ + คลิกซ้าย`: สวมใส่ของแต่งชิ้นนั้นเข้ากับปืน
* `กดปุ่มสลับมือ (F)`: เลือก/หมุนสลับของแต่งปืนตามกลุ่มต่างๆ
* `มือเปล่า + คลิกซ้าย`: ถอดของแต่งชิ้นที่กำลังเลือกอยู่ออกจากปืน

{% hint style="info" %}
ℹ️ **เงื่อนไขการยกเลิกโหมดแต่งปืน:** หากผู้เล่นถูกโจมตีได้รับความเสียหาย หรือตัวละครตาย ระบบจะยกเลิกการแต่งปืนทันทีและปลดล็อกการเคลื่อนที่ของผู้เล่นทันทีเพื่อความปลอดภัย
{% endhint %}
{% 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/attachments.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.