> 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-config.md).

# model config

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

## ⚙️ Weapon Model Configuration

Each weapon requires a configuration YAML placed inside the `plugins/KbAnimation/models/` directory (e.g., `ak12.yml`).

### YAML Configuration Example

Below is a clean configuration file detailing how basic weapon parameters are mapped:

```yaml
# Weapon Registry Settings
weapon-title: "AR_AK12"                    # Must match WeaponMechanics weapon ID
category: "GUN"                          # GUN or MELEE (defines animation trigger types)
model-id: "ak12_animation"                 # BetterModel model-id string

animations:
  equip:
    animation: "equip"                     # Blockbench animation key
    display-name: "Equip AK-12"            # Logger tracking name
    loop: false                            # Play once
    speed: 1.0                             # Playback speed multiplier (1.0 = normal)
    offset-x: 0.0                          # Right/Left offset shift (blocks)
    offset-y: 0.8                          # Height offset (blocks)
    offset-z: -0.8                         # Depth offset (forward/back blocks)
  standing:
    animation: "standing"
    loop: true
    speed: 1.0
    offset-x: 0.0
    offset-y: 0.8
    offset-z: -0.8
  zoom:
    animation: "aiming"
    loop: true
    speed: 1.0
    offset-x: 0.0                          # Aligned to screen center x=0
    offset-y: 1.109                        # Raised slightly to hit eye sight level
    offset-z: -0.8
```

### Configuration Field Reference

| Field Name                       | Data Type | Default      | Description                                                       |
| -------------------------------- | --------- | ------------ | ----------------------------------------------------------------- |
| `weapon-title`                   | String    | YML filename | Weapon ID matching WeaponMechanics config title.                  |
| `category`                       | String    | `GUN`        | Set to `GUN` for firearm ranges, or `MELEE` for melee slots.      |
| `model-id`                       | String    | None         | Registered BetterModel ID of the 3D entity (Required).            |
| `animations.<type>.animation`    | String    | None         | Name matching animation channel inside exported model (Required). |
| `animations.<type>.loop`         | Boolean   | `false`      | Specifies whether animation loops when active.                    |
| `animations.<type>.speed`        | Double    | `1.0`        | Base playback speed scale (e.g. 1.5 = 50% faster).                |
| `animations.<type>.offset-x/y/z` | Double    | `0.0`        | Position offsets (relative to player eye position).               |

### Understanding Category: GUN vs. MELEE

* **GUN:** Standard weapon category. Triggers `equip`, `standing`, `sprint`, `reload`, `shoot`, `zoom`, `zoom_aiming`, `inspect`, and `unequip` animations.
* **MELEE:** Knife/sword category. Restricts ranged animations. Focuses on `equip`, `standing`, `slash` (attack animation), `inspect`, and `unequip`. Does not display ammunition or fire mode icons on the HUD.

### Aligning Weapon Offsets (Aiming Down Sights)

The positioning offsets shift the entire 3D model relative to the player's camera viewpoint:

* **Offset-X:** Horizontal axis. Shift right (+) or left (-). ADS aiming transitions typically require X to be exactly `0.0` to align the iron sights or optic reticle to the screen center.
* **Offset-Y:** Vertical axis (height). Shift up (+) or down (-). The default holding height is usually `0.8`. For ADS zoom, raising Y to `1.1` or similar centers the scope aperture to the camera's eye line.
* **Offset-Z:** Depth axis (distance). Shift forward (+) or backward (-). Pushing the model back (e.g., `-0.8`) prevents model clipping.
  {% endtab %}

{% tab title="TH" %}

## ⚙️ การตั้งค่าโมเดลอาวุธ (YML Config)

อาวุธปืนหรือมีดทุกชิ้นในเซิร์ฟเวอร์ จะต้องมีไฟล์ตั้งค่าสกุล YAML 1 ไฟล์เป็นของตัวเอง โดยจัดเก็บไว้ที่โฟลเดอร์ `plugins/KbAnimation/models/` (เช่น `ak12.yml`)

### ตัวอย่างไฟล์ YAML ตั้งค่าแบบสมบูรณ์

ด้านล่างนี้คือตัวอย่างการกำหนดค่าปืนและท่าแอนิเมชันต่างๆ:

```yaml
# ข้อมูลอ้างอิงรหัสอาวุธ
weapon-title: "AR_AK12"                    # ชื่อปืนที่ตั้งไว้ในไฟล์คอนฟิกของ WeaponMechanics
category: "GUN"                          # หมวดหมู่: GUN (ปืนทั่วไป) หรือ MELEE (อาวุธระยะประชิด)
model-id: "ak12_animation"                 # รหัส Model ID ที่ลงทะเบียนไว้ใน BetterModel

# การกำหนดการเล่นแอนิเมชันแต่ละท่า
animations:
  equip:
    animation: "equip"                     # ชื่อแอนิเมชันที่ทำใน Blockbench
    display-name: "Equip AK-12"            # ชื่อป้ายบันทึกตอนตรวจสอบการโหลด
    loop: false                            # เล่นครั้งเดียวจบ (ไม่ลูป)
    speed: 1.0                             # ตัวคูณความเร็วการเล่นท่า (1.0 = ปกติ)
    offset-x: 0.0                          # เลื่อนพิกัดซ้าย/ขวา (หน่วยเป็นบล็อก)
    offset-y: 0.8                          # เลื่อนพิกัดความสูง (หน่วยเป็นบล็อก)
    offset-z: -0.8                         # เลื่อนพิกัดหน้า/หลัง (หน่วยเป็นบล็อก)
  standing:
    animation: "standing"
    loop: true                             # เล่นวนลูปตลอดเวลา
    speed: 1.0
    offset-x: 0.0
    offset-y: 0.8
    offset-z: -0.8
  zoom:
    animation: "aiming"
    loop: true
    speed: 1.0
    offset-x: 0.0                          # พิกัดตรงกลางหน้าจอพอดี (x=0)
    offset-y: 1.109                        # ยกระดับปืนขึ้นเล็กน้อยเพื่อให้ศูนย์เล็งตรงตา
    offset-z: -0.8
```

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

| ชื่อตัวแปร                       | ชนิดข้อมูล | ค่าเริ่มต้น | หน้าที่การทำงาน                                                                 |
| -------------------------------- | ---------- | ----------- | ------------------------------------------------------------------------------- |
| `weapon-title`                   | String     | ชื่อไฟล์    | ชื่อของปืนที่จะให้แสดงแอนิเมชันนี้ ต้องตรงกับ ID ใน WeaponMechanics.            |
| `category`                       | String     | `GUN`       | ประเภทอาวุธ: ใส่ `GUN` สำหรับปืนยิง และ `MELEE` สำหรับมีดฟัน.                   |
| `model-id`                       | String     | ไม่มี       | รหัส Model ID ของตัวโมเดล 3D ที่ได้ลงทะเบียนไว้กับ BetterModel (จำเป็นต้องใส่). |
| `animations.<type>.animation`    | String     | ไม่มี       | ชื่อไฟล์หรือชื่อท่าในแถบแอนิเมชันของ Blockbench (จำเป็นต้องใส่).                |
| `animations.<type>.loop`         | Boolean    | `false`     | ตั้งเป็น `true` หากต้องการให้ท่าเคลื่อนไหวนี้ลูปทำงานวนซ้ำ.                     |
| `animations.<type>.speed`        | Double     | `1.0`       | อัตราความเร็วการเล่น (เช่น 2.0 = เล่นเร็วขึ้นสองเท่า).                          |
| `animations.<type>.offset-x/y/z` | Double     | `0.0`       | พิกัดเลื่อนตำแหน่งโมเดลปืน (แกน x, y, z เทียบกับสายตาผู้เล่น).                  |

### ความแตกต่างระหว่างประเภทอาวุธ: GUN vs. MELEE

* **GUN (หมวดปืนยิง):** รองรับแอนิเมชันการทำงานครบทั้งหมด: ดึงปืน (equip), ท่าถือยืนนิ่ง (standing), ท่าวิ่ง (sprint), ท่ารีโหลด (reload), ท่ายิงปกติ, ท่าซูมเล็ง (zoom), ท่ายิงตอนซูม, ท่าเช็กปืน (inspect) และท่าเก็บปืน (unequip)
* **MELEE (หมวดอาวุธประชิด):** ปิดระบบซูมเล็งและระบบกระสุนทั้งหมด รองรับเพียงแอนิเมชันดึงอาวุธ (equip), ถือยืนนิ่ง (standing), ท่าฟันมีด (slash), ท่าเช็กมีด (inspect) และท่าเก็บมีด (unequip) เพื่อลดการใช้งานการประมวลผลที่ไม่จำเป็น

### หลักการเลื่อนพิกัดตำแหน่งปืน (Offsets & ADS Setup)

ตำแหน่งโมเดลอาวุธ 3D จะปรับอิงสัมพันธ์กับระดับพิกัดสายตา (Camera Viewpoint) ของตัวผู้เล่นดังนี้:

* **Offset-X (แกนซ้ายขวา):** ขยับปืนไปทางขวา (+) หรือไปทางซ้าย (-) ในแอนิเมชันเล็งยิง (zoom หรือ ADS) ส่วนนี้จำเป็นต้องเป็น `0.0` เพื่อให้ตัวปืนหรือศูนย์หน้าเล็งตรงกับกลางจอ (เป้าเล็ง) พอดี
* **Offset-Y (แกนความสูง):** ดึงปืนขึ้นด้านบน (+) หรือยกลงด้านล่าง (-) ค่าปกติเวลากดถือดึงปืนทั่วไปจะอยู่ที่ประมาณ `0.8` แต่เวลาสลับท่าเป็น ADS (เล็งผ่านกล้อง) เราจะต้องดึงปืนขึ้นมาที่ระดับ `1.1` หรือใกล้เคียง เพื่อให้ศูนย์กล้องทาบระดับสายตาพอดี
* **Offset-Z (แกนระยะหน้าหลัง):** ผลักปืนไปข้างหน้า (+) หรือดึงมาใกล้ตา (-) แนะนำให้ตั้งไว้ที่ `-0.8` หรือ `-1.0` เพื่อป้องกันไม่ให้ปืนชนทะลุบล็อก หรือแสดงผลทับมุมกล้อง
  {% 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-config.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.