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

# plugin config

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

## 🔧 Main Plugin Configuration

This page details the options inside the primary configuration file located at `plugins/KbAnimation/config.yml`.

### Complete config.yml Template

```yaml
# Ammo layout text format shown when holding a weapon
# Variables: {ammo} = current, {max_ammo} = clip capacity
# Supports MiniMessage (e.g. <white>, <red>) instead of legacy &codes
display-format: "    <white>{ammo}<gray>/<white>{max_ammo}"

# Text displayed while reload is in progress
reload-format: "<red>Reload..."

# Text format for close combat items (ammunition value of -1 or capacity 0)
melee-format: "<white>Knife"

# Specific Custom Melee titles (overrides the generic melee-format above)
custom-melee:
  Combat_Knife: "<white>Combat Knife"
  Karambit: "<white>Karambit"

# Check the player's offhand slot for weapons as well
check-offhand: false

# Crosshair Display Settings
crosshair:
  format: "<image:crosshair>"       # Crosshair string or BetterHud image tag
  hide-when-aiming: true             # Auto-hide crosshair when ADS zooming
  keep-when-aiming:                  # Exception list: keep crosshair on screen for:
    - "SR_OSV96"

# Damage received direction indicator settings
damage-indicator:
  test-mode: false                   # Force all 4 arrow overlay directions to render (for positioning tests)

# Kill Feed Announcement Settings
killfeed:
  enable: true                       # Toggle Kill Feed registry
  mode: "popup"                      # "chat" (global chat log) or "popup" (BetterHud toast popup)
  player-only: true                  # Only show PvP kills (false matches PvE mobs too)
  headshot-format: "<red>☠ <white>{shooter} <gray>[<yellow>{weapon}<gray>] <red> (Headshot) <gray>-> <white>{victim}"
  normal-format: "<red>☠ <white>{shooter} <gray>[<yellow>{weapon}<gray>] <gray>-> <white>{victim}"

# Hit Marker Overlay Settings
hitmarker:
  enable: true                       # Enable body damage hit cross marker
  duration-ms: 300                   # Marker display time in milliseconds (1000ms = 1s)

# Core Settings Section
settings:
  language: "th"                     # Active localized language filename (in lang/ folder)
  
  # Customization Mode entry trigger keys.
  # Options: SNEAK_SWAP (Sneak+F), SNEAK_DROP (Sneak+Q), SWAP (F), DROP (Q)
  customization-trigger: SNEAK_SWAP
  
  # Idle check reset delay.
  # Specifies ticks to wait after firing ceases before reverting to standing stance.
  shoot-reset-ticks: 6
```

### Section Explanations

* **Display & Melee:** Formatting uses the MiniMessage system. When a player holds an item defined as a weapon, `display-format` translates the current clip status. If the weapon is defined as a `MELEE` category or has negative ammo values, it translates using `melee-format`, or searches `custom-melee` keys.
* **Crosshair Exception list:** The `keep-when-aiming` list is critical for sniper scopes. If you want a custom sniper scope overlay reticle to display instead of vanishing when zooming, add the weapon ID here.
* **Damage Indicator test-mode:** When configuring your BetterHud layouts, adjusting x/y alignment coordinates is difficult if arrows only render when damaged. Enable `test-mode: true` to force all 4 arrows on screen continuously during setup.
* **Trigger Options:**`customization-trigger` maps the key actions to freeze movement and enter the modification overlay. Setting it to `SNEAK_SWAP` means sneaking while swapping hands (default key Shift+F) starts the session.
  {% endtab %}

{% tab title="TH" %}

## 🔧 การตั้งค่าหลัก (config.yml)

หน้านี้อธิบายรายละเอียดตัวแปรทั้งหมดในไฟล์ปรับแต่งหลักของปลั๊กอิน ซึ่งจัดเก็บอยู่ที่ `plugins/KbAnimation/config.yml`

### โครงสร้างไฟล์ config.yml ฉบับสมบูรณ์

```yaml
# รูปแบบตัวอักษรของกระสุนปืนที่จะแสดงผลบน HUD ขณะถืออาวุธ
# ตัวแปร: {ammo} = จำนวนกระสุนในแม็ก, {max_ammo} = จำนวนกระสุนสูงสุด
# รองรับแท็กสีแบบ MiniMessage (เช่น <white>, <red>) แทนการใช้รหัส & แบบเก่า
display-format: "    <white>{ammo}<gray>/<white>{max_ammo}"

# ข้อความที่จะแสดงผลตรงตำแหน่งจำนวนกระสุนขณะกำลังบรรจุกระสุนปืน
reload-format: "<red>Reload..."

# รูปแบบข้อความที่จะแสดงเมื่อผู้เล่นถืออาวุธระยะประชิด (ค่ากระสุน = -1 หรือความจุแม็ก = 0)
melee-format: "<white>Knife"

# กำหนดข้อความเฉพาะสำหรับอาวุธระยะประชิดบางชิ้น (อิงชื่อชื่อปืนจาก WeaponMechanics)
# หากตรงกับปืนที่มีรายชื่อที่นี่ มันจะข้าม melee-format ด้านบนแล้วใช้ข้อความตามนี้ทันที
custom-melee:
  Combat_Knife: "<white>Combat Knife"
  Karambit: "<white>Karambit"

# เปิดใช้งานการตรวจสอบอาวุธปืนที่สวมใส่อยู่ในมือซ้าย (Off-hand) หรือไม่
check-offhand: false

# การตั้งค่าเป้าเล็งกลางหน้าจอ (Crosshair)
crosshair:
  format: "<image:crosshair>"       # ข้อความหรือแท็กแสดงรูปภาพเป้าเล็งใน BetterHud
  hide-when-aiming: true             # ซ่อนเป้าเล็งนี้โดยอัตโนมัติเมื่อกดซูมยิง (ADS)
  keep-when-aiming:                  # รายชื่อปืนที่ยกเว้น (ให้แสดงเป้าปกติไว้แม้จะกดซูมอยู่ก็ตาม)
    - "SR_OSV96"

# การตั้งค่าทิศทางดาเมจเมื่อได้รับความเสียหาย (Damage Indicator)
damage-indicator:
  test-mode: false                   # โหมดทดสอบ: บังคับให้รูปทิศทางทั้ง 4 ทิศโชว์ค้างตลอดเวลา (สำหรับเปิดวัดตำแหน่ง x, y)

# ระบบแจ้งเตือนการฆ่า (Kill Feed)
killfeed:
  enable: true                       # เปิดใช้งานระบบคิลฟีดหรือไม่
  mode: "popup"                      # รูปแบบแสดงผล: "chat" (ส่งเข้าช่องแชท) หรือ "popup" (แสดงเป็นหน้าต่างลอยของ BetterHud)
  player-only: true                  # แสดงเฉพาะตอนผู้เล่นคิลผู้เล่นกันเองเท่านั้น (หากตั้งเป็น false ยิงซอมบี้ตายคิลฟีดจะขึ้นด้วย)
  headshot-format: "<red>☠ <white>{shooter} <gray>[<yellow>{weapon}<gray>] <red> (Headshot) <gray>-> <white>{victim}"
  normal-format: "<red>☠ <white>{shooter} <gray>[<yellow>{weapon}<gray>] <gray>-> <white>{victim}"

# การแจ้งเตือนเป้ากระพริบเวลายิงโดนศัตรู (Hit Marker)
hitmarker:
  enable: true                       # เปิดระบบเป้ากระพริบเมื่อโจมตีโดนตัวละครอื่น
  duration-ms: 300                   # ระยะเวลาแสดงเป้าสีแดงบนหน้าจอ (หน่วยมิลลิวินาที: 300ms = 0.3 วินาที)

# หมวดหมู่ระบบปลั๊กอินทั่วไป (Settings)
settings:
  language: "th"                     # ชื่อภาษาที่จะใช้งาน (ไฟล์จะอยู่ในโฟลเดอร์ lang/)
  
  # ปุ่มคีย์ลัดกดเพื่อเข้าหรือออกจากหน้าจอแต่งปืน
  # ตัวเลือก: SNEAK_SWAP (ย่อ+F), SNEAK_DROP (ย่อ+Q), SWAP (F), DROP (Q)
  customization-trigger: SNEAK_SWAP
  
  # จำนวน Tick ในการรอหลังจากยิงกระสุนนัดสุดท้าย ก่อนจะปรับแอนิเมชันกลับเป็นท่ายืนถือปกติ
  shoot-reset-ticks: 6
```

### คำอธิบายส่วนต่างๆ ที่ควรทราบ

* **สีแบบ MiniMessage:** การตั้งค่าสีข้อความในปลั๊กอินนี้ใช้ระบบ MiniMessage ของ Paper (เช่น `<white>`, `<gray>`, `<red>`) ซึ่งรองรับระบบสีแบบไล่เฉด RGB หรือ Hex ได้ด้วย มีประสิทธิภาพสูงกว่าระบบโค้ดสี `&` แบบดั้งเดิม
* **ข้อยกเว้นปืนสไนเปอร์ (Keep-when-aiming):** ปืนประเภทสไนเปอร์ที่ต้องซูมเห็นเส้นกล้องสโคปเต็มหน้าจอมักจะมีภาพเป้าสีดำในตัวอยู่แล้ว แต่ถ้าปืนบางรุ่นไม่มีเส้นเล็งและจำเป็นต้องให้เป้าจุดกลางจอยังคงแสดงอยู่ขณะซูม ให้นำชื่อปืนมาใส่ในรายการยกเว้นนี้
* **ประโยชน์ของโหมดทดสอบทิศทางโดนยิง (Damage test-mode):** เวลาเราเขียนหน้าต่าง HUD เพื่อจัดวางตำแหน่งลูกศรทิศทางเหนือ, ใต้, ออก, ตก มันเป็นเรื่องยากถ้าต้องให้มอนสเตอร์มาตีเพื่อทดสอบตำแหน่ง การเปลี่ยน `test-mode: true` จะทำให้ลูกศรทั้งสี่ทิศค้างบนหน้าจอตลอด ทำให้จัดตำแหน่งใน BetterHud Layout ได้สะดวกขึ้น
* **การตั้งค่าปุ่มแต่งปืน:** ตัวแปร `customization-trigger` แนะนำให้ใช้ค่าเริ่มต้นคือ `SNEAK_SWAP` ซึ่งผู้เล่นจะกดโดยการกดปุ่มย่อตัวพร้อมกดปุ่ม F (สลับมือ) ซึ่งจะไม่ชนกับปุ่มกดเก็บของหรือการควบคุมทั่วไป
  {% 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/plugin-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.