> 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/hud-setup.md). # hud setup {% tabs %} {% tab title="EN" %} ## 🖥️ BetterHUD & Placeholder Setup KbAnimation registers native placeholders directly inside the BetterHud registry (requiring no % wrapper) and exports standard PlaceholderAPI variables for external plugins. ### 1. PlaceholderAPI Variables These variables can be used in chat formats, tablists, or scoreboard plugins: | PAPI Placeholder | Returned Value Type | Description | | ---------------------------- | ------------------------ | ------------------------------------------------------------------------ | | `%wmbhud_display%` | String | Formatted ammo text (or reload status). Empty when not holding a weapon. | | `%wmbhud_crosshair%` | String | Configured crosshair image text. Empty when scoping in ADS. | | `%wmbhud_crosshair_visible%` | Boolean (true/false) | Visibility condition state of the crosshair. | | `%wmbhud_fire_mode%` | String (AUTO/BURST/SEMI) | Currently selected Selective Fire mode of the held gun. | ### 2. Native BetterHud Placeholders Use these variables directly in BetterHud layout conditions or text components: | BetterHud Placeholder | Value Type | Usage Description | | ---------------------------- | ---------- | -------------------------------------------------------------------------- | | `{wmbhud_visible}` | Boolean | `true` when holding any valid WeaponMechanics gun. Used to toggle the HUD. | | `{wmbhud_display}` | String | Main ammunition count display text. | | `{wmbhud_crosshair_visible}` | Boolean | `true` when the hip-fire crosshair should be drawn on screen. | | `{wmbhud_crosshair}` | String | Crosshair image/unicode text content. | | `{wmbhud_fire_mode_auto}` | Boolean | `true` if active fire mode is AUTO. | | `{wmbhud_fire_mode_burst}` | Boolean | `true` if active fire mode is BURST. | | `{wmbhud_fire_mode_semi}` | Boolean | `true` if active fire mode is SEMI. | | `{wmbhud_damage_up}` | Boolean | `true` for 1 second when taking damage from the front. | | `{wmbhud_damage_down}` | Boolean | `true` when taking damage from behind. | | `{wmbhud_damage_left}` | Boolean | `true` when taking damage from the left. | | `{wmbhud_damage_right}` | Boolean | `true` when taking damage from the right. | | `{wmbhud_hitmarker}` | Boolean | `true` when hit-marker duration is active. | | `{wmbhud_headshotmarker}` | Boolean | `true` when hit-marker headshot duration is active. | | `{wmbhud_killfeed_text}` | String | Recent PvP/PvE death logger message. | | `{wmbhud_in_customization}` | Boolean | `true` when player is in gun customization mode. | | `{wmbhud_stat_weapon_name}` | String | The display name of the gun (stripped of color codes). | ### 3. Gun Customization Stats Bars In customization mode, the plugin calculates weapon stats (including modifiers from attachments) and outputs bar lengths. For each stat (`damage`, `rpm`, `range`, `accuracy`, `control`, `magazine`, `reload`), these placeholders are available: * `{wmbhud_stat__max}` - The maximum possible value for scaling bars. * `{wmbhud_stat__white}` - The base gun stat value (rendered as a neutral white/gray bar). * `{wmbhud_stat__green}` - The added value of equipped positive attachments (rendered as a green bar). * `{wmbhud_stat__red}` - The removed value of equipped negative attachments (rendered as a red bar overlay). * `{wmbhud_stat__text}` - Formatted comparison text (e.g. `42.0 (+7.0)`). ### 4. BetterHud Configuration Examples To use fire modes, register the icons in BetterHud (e.g., `images/fire_mode.yml`): ```yaml fire_mode_auto: type: single file: fire_mode_auto.png height: 12 fire_mode_semi: type: single file: fire_mode_semi.png height: 12 ``` Then, set conditions in your layout file (e.g. `simple_ui_layout.yml`): ```yaml # Ammo counter layout ammo_text: type: text text: "{wmbhud_display}" conditions: - "{wmbhud_visible}" x: -30 y: 5 align: left # Conditional fire mode icon displays auto_icon: type: image image: fire_mode_auto conditions: - "{wmbhud_fire_mode_auto}" - "{wmbhud_visible}" x: -45 y: 5 semi_icon: type: image image: fire_mode_semi conditions: - "{wmbhud_fire_mode_semi}" - "{wmbhud_visible}" x: -45 y: 5 ``` > 📸 **📸 \[Insert HUD UI Layout preview screenshot here]** *Demonstrates HUD positioning for Ammo count, Fire mode icons, and Hit markers in action* > {% endtab %} {% tab title="TH" %} ## 🖥️ การเชื่อมโยงกับ BetterHUD & Placeholders KbAnimation มีการลงทะเบียนตัวแปร (Placeholders) เข้าไปในระบบของ BetterHud โดยตรง (เวลาใช้งานไม่ต้องครอบเครื่องหมาย % ) และส่งออกตัวแปรสำหรับเชื่อมปลั๊กอินภายนอกผ่าน PlaceholderAPI ### 1. ตัวแปรผ่านปลั๊กอิน PlaceholderAPI (ใช้ภายนอก) ตัวแปรกลุ่มนี้ต้องครอบด้วยเครื่องหมาย % เพื่อนำไปใช้กับปลั๊กอินบอกสถานะ คะแนน (Scoreboard) บอร์ดแชท หรือรายชื่อผู้เล่น: | ตัวแปร PAPI | ชนิดของค่าที่ได้ | คำอธิบายการทำงาน | | ---------------------------- | ------------------------ | ---------------------------------------------------------------------- | | `%wmbhud_display%` | String | ข้อมูลจำนวนกระสุนหรือข้อความรีโหลด (จะได้ค่าว่างเปล่าหากไม่ได้ถือปืน). | | `%wmbhud_crosshair%` | String | ข้อความหรือรูปภาพเป้าเล็ง (จะได้ค่าว่างเปล่าเมื่อกดเล็งซูมยิง). | | `%wmbhud_crosshair_visible%` | Boolean (true/false) | ตรวจสอบว่าเป้าเล็งปืนกลางหน้าจอควรจะแสดงผลอยู่หรือไม่. | | `%wmbhud_fire_mode%` | String (AUTO/BURST/SEMI) | โหมดการยิงที่ปืนกระบอกนั้นกำลังใช้งานอยู่ในปัจจุบัน. | ### 2. ตัวแปรระบบภายใน BetterHUD (ใช้จัดแต่ง UI) ใช้ตัวแปรเหล่านี้เขียนเงื่อนไข (Conditions) หรือพิมพ์ข้อความในไฟล์ Layout หน้าจอของ BetterHud ได้ทันที: | ตัวแปร BetterHUD | ชนิดตัวแปร | ประโยชน์และการใช้งาน | | ---------------------------- | ---------- | ---------------------------------------------------------------------------- | | `{wmbhud_visible}` | Boolean | เป็น `true` เมื่อผู้เล่นถือปืนจาก WeaponMechanics (ใช้เปิด/ปิด HUD ทั้งหมด). | | `{wmbhud_display}` | String | แสดงผลจำนวนกระสุนปืนรวม (อิงตามไฟล์ config.yml). | | `{wmbhud_crosshair_visible}` | Boolean | เป็น `true` เมื่อเป้าเล็งปืนกลางหน้าจอควรจะโผล่ขึ้นมา. | | `{wmbhud_crosshair}` | String | ดึงรูปภาพ/สัญลักษณ์เป้าเล็งปืนตรงกลางหน้าจอมาแสดง. | | `{wmbhud_fire_mode_auto}` | Boolean | เป็น `true` หากปืนที่ถือตั้งโหมดการยิงแบบอัตโนมัติ (AUTO). | | `{wmbhud_fire_mode_burst}` | Boolean | เป็น `true` หากปืนตั้งยิงทีละชุด/สามนัด (BURST). | | `{wmbhud_fire_mode_semi}` | Boolean | เป็น `true` หากปืนตั้งยิงทีละนัด (SEMI). | | `{wmbhud_damage_up}` | Boolean | เป็น `true` ชั่วขณะ (1 วินาที) เมื่อได้รับดาเมจจากทิศทางด้านหน้า. | | `{wmbhud_damage_down}` | Boolean | เป็น `true` เมื่อโดนโจมตีจากทิศทางด้านหลัง. | | `{wmbhud_damage_left}` | Boolean | เป็น `true` เมื่อโดนโจมตีจากทิศทางด้านซ้าย. | | `{wmbhud_damage_right}` | Boolean | เป็น `true` เมื่อโดนโจมตีจากทิศทางด้านขวา. | | `{wmbhud_hitmarker}` | Boolean | เป็น `true` ชั่วขณะเมื่อยิงกระสุนโดนเป้าหมาย (ใช้โชว์เป้ากระพริบ). | | `{wmbhud_headshotmarker}` | Boolean | เป็น `true` ชั่วขณะเมื่อยิงกระสุนเข้าหัวเป้าหมาย (ใช้โชว์เป้าสีแดงคริติคอล). | | `{wmbhud_killfeed_text}` | String | ข้อความแจ้งสถานะการตายล่าสุด (ใช้ในโหมดแจ้งเตือนเด้งมุมจอ). | | `{wmbhud_in_customization}` | Boolean | เป็น `true` ขณะที่ผู้เล่นกำลังกดสลับเข้าโหมดแต่งปืน. | | `{wmbhud_stat_weapon_name}` | String | ชื่อแสดงผลปืนที่กำลังถืออยู่ (ตัดรหัสโค้ดสีออกเพื่อความสวยงาม). | ### 3. ตัวแปรแถบแสดงสเตตัสปืนในโหมดแต่งปืน ในหน้าจอแต่งปืน ปลั๊กอินจะทำการดึงข้อมูลปืนมาคำนวณและแสดงความก้าวหน้าของแถบพลัง (Stats) ตามค่าของแต่งที่ใส่ โดยตัวแปรค่าพลัง (มีค่าพลัง: `damage`, `rpm`, `range`, `accuracy`, `control`, `magazine`, `reload`) จะส่งออกค่าดังนี้: * `{wmbhud_stat_<ชื่อค่าพลัง>_max}` - ค่าพลังสูงสุดที่ปืนจะทำได้ (ใช้กำหนดขอบเขตความกว้างของหลอด) * `{wmbhud_stat_<ชื่อค่าพลัง>_white}` - ค่าพลังดั้งเดิมของปืนเปล่าๆ (แสดงผลเป็นหลอดสีขาว) * `{wmbhud_stat_<ชื่อค่าพลัง>_green}` - ค่าพลังที่เพิ่มขึ้นมาจากการใส่ของแต่งที่มีผลดี (แสดงผลเป็นหลอดสีเขียวเสริม) * `{wmbhud_stat_<ชื่อค่าพลัง>_red}` - ค่าพลังที่หักลดลงไปจากการใส่ของแต่งที่มีผลเสีย (แสดงผลเป็นหลอดสีแดงซ้อนทับ) * `{wmbhud_stat_<ชื่อค่าพลัง>_text}` - ข้อความเปรียบเทียบความต่าง เช่น `42.0 (+7.0)` ### 4. ตัวอย่างการกำหนดการแสดงผลใน BetterHud Layout ตัวอย่างการลงทะเบียนรูปภาพไอคอนโหมดปืนใน `BetterHud/images/fire_mode.yml`: ```yaml fire_mode_auto: type: single file: fire_mode_auto.png height: 12 fire_mode_semi: type: single file: fire_mode_semi.png height: 12 ``` และตัวอย่างการนำตัวแปรเงื่อนไขไปใช้งานในไฟล์แสดงผล UI (เช่น `simple_ui_layout.yml`): ```yaml # ช่องตัวอักษรกระสุน (แสดงเฉพาะเวลาถือปืน) ammo_text: type: text text: "{wmbhud_display}" conditions: - "{wmbhud_visible}" x: -30 y: 5 align: left # แสดงไอคอนตามสถานะโหมดการยิงจริง auto_icon: type: image image: fire_mode_auto conditions: - "{wmbhud_fire_mode_auto}" - "{wmbhud_visible}" x: -45 y: 5 semi_icon: type: image image: fire_mode_semi conditions: - "{wmbhud_fire_mode_semi}" - "{wmbhud_visible}" x: -45 y: 5 ``` > 📸 **📸 \[รูปภาพจำลองหน้าต่าง HUD แสดงไอคอนกระสุน, โหมดปืน และเป้าคิลฟีดที่อยู่ขอบจอ]** *ตัวอย่างแสดงผลการเปลี่ยนพิกัด x, y ในหน้าตั้งค่า BetterHud Layout* > {% 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/hud-setup.md?ask=&goal= ``` `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.