Cursor UI

แนวคิดแบบเข้าใจง่าย

เมนู Minecraft ปกติเป็นหน้าต่างหีบ แต่ CradGacha สร้างเมนูจาก โฮโลแกรมที่ลอยในโลก และให้ผู้เล่นมี เคอร์เซอร์เมาส์เสมือน ที่ขยับด้วยเมาส์ เหมือน UI บนเดสก์ท็อปเป๊ะ ผู้เล่นชี้ไปที่ปุ่มแล้วคลิก

เพื่อให้รู้สึกถูกต้อง ปลั๊กอินจะ แช่กล้องไว้: ตอนเปิดเมนู วิวของผู้เล่นจะล็อกนิ่ง (เมนูจะได้ไม่สั่น) ขณะที่เมาส์ยังขยับเคอร์เซอร์ได้ การแช่นี้ใช้ packetevents จึงต้องมี packetevents

ศัพท์สำคัญ

ศัพท์	ความหมาย
เคอร์เซอร์เสมือน	ตัวชี้เล็ก ๆ ที่คุณขยับด้วยเมาส์ ไม่ใช่เป้ากลางจอ vanilla แต่เป็น display entity ที่ปลั๊กอินขยับให้
พื้นที่คลิกได้	สี่เหลี่ยมล่องหน (hitbox) ที่ผูกกับปุ่ม เมื่อเคอร์เซอร์อยู่ในนั้น = "hover" ปุ่มนั้น
Hover	เคอร์เซอร์อยู่บนปุ่ม ปุ่มจะเรืองแสงและมีเสียงติ๊ก
Click	คลิกซ้าย/ขวาขณะ hover แอ็กชันของปุ่มจะทำงาน (เลือกตู้/เปิด ฯลฯ)
Spectator freeze	เทคนิคล็อกกล้องที่ทำให้วิวนิ่งขณะเมาส์ขยับเคอร์เซอร์

คลิกเกิดขึ้นยังไง (เบื้องหลัง)

เมาส์หมุนหัวคุณ ปลั๊กอินอ่านการหมุนนั้นแล้วขยับเคอร์เซอร์
ทุก tick มันเช็คว่าเคอร์เซอร์อยู่ในพื้นที่คลิกได้อันไหน
เมื่อคุณคลิก มันรันแอ็กชันของพื้นที่ที่กำลัง hover

คุณไม่ต้องตั้งค่าอะไรเลย — มันทำงานเอง เลย์เอาต์ (ตำแหน่งปุ่ม) อยู่ใน theme.yml ส่วน ความรู้สึก (ความไว ขอบเขต) อยู่ใน cursor.yml (ดู การตั้งค่า)

ปรับความรู้สึก (cursor.yml)

yaml

sensitivity-x: 0.3   # เพิ่มถ้าเคอร์เซอร์ขยับซ้าย-ขวาช้า
sensitivity-y: 0.22
bounds: { min-x: -2.8, max-x: 2.8, min-y: -1.6, max-y: 1.8 }  # ระยะที่เคอร์เซอร์ไปได้
smoothing: 0.7       # 1.0 = ทันที/ดิบ, ต่ำลง = ลื่นขึ้น

เคอร์เซอร์ช้า / ไปไม่ถึงขอบ? เพิ่ม sensitivity-x และ/หรือขยาย bounds
เคอร์เซอร์กระตุก? ลด sensitivity หรือลด smoothing

ทำไมทุกอย่างสว่าง (ไม่มีโมเดลมืด)

ไอเทมและข้อความในเมนูอาจดูมืดถ้าปล่อยให้แสงในโลกมีผล CradGacha จึงตั้ง display ทุกตัว ให้ สว่างเต็ม 15/15 ในโค้ด ปุ่มและโมเดลรางวัลจึงดูคมเสมอ ไม่ว่าเวลาในเกมหรือผู้เล่นยืนตรงไหน เป็นอัตโนมัติ ไม่มีค่าให้ตั้ง

theme.yml ใน 1 นาที

theme.yml ควบคุม ว่าอะไรอยู่ตรงไหน และ ใช้รูป/ข้อความอะไร คุณย้ายปุ่ม เปลี่ยนข้อความ สลับรูป หรือเพิ่ม element ของคุณเองได้ — โดยไม่ต้องแตะโค้ด หลังแก้รัน /gacha reload

yaml

elements:
  btn_x10:
    type: glyph          # glyph (รูป) | text | item
    value: g_open_x10    # ชื่อรูป/glyph
    x: 1.85              # ซ้าย(-)/ขวา(+)
    y: -1.0              # ล่าง(-)/บน(+)
    scale: 0.425
    action: open_count   # คลิกแล้วทำอะไร
    param: "{crate}:10"  # เปิด 10 ใบของตู้ที่เลือก
    hitbox: { w: 0.42, h: 0.16 }

ดู reference เต็มที่ THEME-REFERENCE.md ในรากของ repo

ขนาดภาพที่แนะนำ

ถ้าจะเปลี่ยนภาพ UI เป็นของตัวเอง ให้ทำขนาดตามนี้เพื่อให้คมและไม่ยืดเพี้ยน — ตัวเลขเหล่านี้คือขนาดที่แพ็ก Dragon Jade ที่แถมมาใช้จริง

องค์ประกอบ	ขนาด PNG ที่แนะนำ	หมายเหตุ
Tile พื้นหลัง (`bg_1`…`bg_6`)	512 × 512	Minecraft จำกัดรูปเดี่ยวที่ 256×256 บนจอ → พื้นหลังใหญ่ต้องแบ่งเป็น grid (ดู การตั้งค่า → background)
พื้นหลังรูปเดี่ยว (`menu_background`)	256 × 256	backdrop แบบไม่ tile
แบนเนอร์ showcase (`showcase` / `showcase_pack`)	512 × 256 (2 ชิ้น)	แบนเนอร์กว้าง ทำจาก glyph 2 ครึ่ง
หลังการ์ดรางวัล (`card_back_*`)	512 × 512	การ์ดสี่เหลี่ยมจัตุรัส
ไอคอนตู้ในหน้าเลือก (`crate_1`, `crate_2`)	256 × 128
ปุ่ม Open (`g_open_x1`, `g_open_x10`, back/again/all)	66 × 22 (คงสัดส่วน ~3:1)	ปุ่มทรงยาว
ไอคอนเงิน/ไอคอนเล็ก (`i_token`, `i_money`)	~21 × 22	~จัตุรัส วางในบรรทัดข้อความ
ปุ่ม glyph เล็ก (shop, spark, wishlist, rate…)	24 × 24
Cursor crosshair (`cursor.png`)	16 × 16	เล็กไว้เพื่อเล็งแม่น
ช่อง pity bar (`pity_0`…`pity_full`)	16 × 32 (สูง)	เรียงต่อกันเป็นหลอด
แถบเครื่องมือ editor (`layout_edit`, `layout_edit_1`)	139 × 24 (6 ช่อง ~23 px)	ถ้าวาดใหม่กว้างต่างไป ตั้ง `theme.layout-editor.bar-aspect` = กว้าง ÷ สูง

หลักจำง่าย:

คงสัดส่วนภาพ — ปุ่มยาวที่วาดเป็นจัตุรัส (หรือกลับกัน) จะยืด เพราะเมนู scale ตามความสูง ความกว้างวิ่งตามสัดส่วนของภาพเอง
ไอคอนควรเป็นทรงจัตุรัส (ปุ่ม/เงิน/cursor) อ่านง่ายสุด ส่วนทรงกว้างเก็บไว้ให้แบนเนอร์/ปุ่ม
อย่าใช้ภาพใหญ่เกินกับไอคอนเล็ก — ภาพ 512×512 มาทำ cursor 16 px แค่กิน pack เปล่า ๆ (และในแท็บ "All Images" ของ Library ภาพพื้นหลังที่ใหญ่เกิน theme.layout-editor.max-glyph-scale จะถูกซ่อนอัตโนมัติ)
บน ItemsAdder ขนาดบนจอกำหนดด้วย scale_ratio ใน font config ไม่ใช่ขนาด PNG — PNG แค่ต้องคมพอที่ขนาดข้างบน

ข้อจำกัด (เฉพาะฝั่งเซิร์ฟ)

มาจากการทำ cursor UI บนเซิร์ฟล้วน (ไม่มี client mod):

เคอร์เซอร์อาจไปไม่ถึง ขอบจอซ้าย/ขวา สุด (การนั่งบนจุดกล้องจำกัดมุมหันหัว) บรรเทาด้วยการเพิ่ม sensitivity-x / ขยาย bounds
อาจมี ดีเลย์เล็กน้อย (เซิร์ฟอัปเดต 20 ครั้ง/วิ เทียบกับ 60fps ของ client)
เป้ากลางจอ vanilla ซ่อนจากฝั่งเซิร์ฟไม่ได้ — ทำ crosshair.png โปร่งใสใน resource pack ถ้าอยากให้หาย

ถัดไป: หน้าผลรางวัล →

Cursor UI ​

แนวคิดแบบเข้าใจง่าย ​

ศัพท์สำคัญ ​

คลิกเกิดขึ้นยังไง (เบื้องหลัง) ​

ปรับความรู้สึก (cursor.yml) ​

ทำไมทุกอย่างสว่าง (ไม่มีโมเดลมืด) ​

theme.yml ใน 1 นาที ​

ขนาดภาพที่แนะนำ ​

ข้อจำกัด (เฉพาะฝั่งเซิร์ฟ) ​