fighting-konoha/guide/sprite-known-issues.md

Masalah yang Pernah Terjadi & Solusinya

Untuk keputusan gameplay dan format terbaru lihat gameplay-standard.md dan character-workflow.md. Kasus lama tetap berguna sebagai diagnosis; angka koreksinya bukan preset karakter baru.

Format: gejala → penyebab → solusi → pencegahan. Tambahkan entri baru setiap menemukan masalah baru, lalu tambahkan pencegahannya ke checklist di sprite-qa.md.

---

1. Saat diam, satu frame terlihat lebih besar

• Gejala: karakter "membesar" sekali tiap siklus idle.
• Penyebab: model gambar menggambar satu pose ~5 % lebih besar (78×149 px vs 74×142 px). Extractor hanya menyamakan posisi kaki, tidak menyamakan skala antar frame.
• Solusi: ukur dengan measure_head_scale.py (kepala, di gambar asli), lalu rebuild_raw.py --rel (koreksi per pose di gambar asli), extract ulang.
• Pencegahan: prompt idle berisi "all at the same scale", "feet planted in the same place"; checklist: skala ±1 %.

2. Setelah diperbaiki, frame yang dikoreksi terlihat sedikit buram / animasi berkedip

• Gejala: ukuran sudah sama tapi animasi terasa "kejut-kejut"; sebagian frame kurang tajam.
• Penyebab: koreksi dilakukan dengan scale (dan dx pecahan) di curation.json. Transform ini me-resample frame dengan bicubic → frame yang dikoreksi lebih lembut dari yang tidak.
• Solusi: hapus transform skala dari curation; koreksi skala di rebuild_raw.py (satu resample dari gambar asli); curation hanya berisi dx bulat.
• Pencegahan: aturan "curation hanya geser bulat" (sprite-qa.md → Yang TIDAK boleh dilakukan).

3. Saat berjalan badan goyang maju-mundur (glitch)

• Gejala: kepala/badan meloncat ±6 px tiap langkah.
• Penyebab: penyelarasan foot-centroid menaruh titik tengah kaki di tengah sel. Saat kaki melebar vs merapat, titik itu berpindah → badan ikut berpindah.
• Solusi: register_frames.py run walk --dx-only → write_dx.py (sejajarkan badan atas ke idle).
• Pencegahan: untuk walk/run selalu jalankan registrasi dx; checklist torso_x ±1.5 px.

4. Karakter mengecil saat mulai berjalan

• Gejala: transisi idle → walk terlihat "zoom out".
• Penyebab: strip walk digambar lebih kecil oleh model; normalisasi pitch tidak sempurna (sisa ~4.5 %).
• Solusi: ukur dengan measure_head_scale.py → median skala → rebuild_raw.py --rel. ⚠ Koreksi pertama memakai registrasi siluet (1.045) dan ternyata berlebihan — walk jadi ±6 % lebih besar dari idle (lihat #12). Nilai yang benar setelah diukur lewat kepala: 0.990.
• Pencegahan: setiap gerakan diukur terhadap idle frame 0 lewat kepala, bukan siluet.

5. Ukuran karakter berbeda-beda antar gerakan

• Gejala: walk jauh lebih kecil dari idle, attack lebih besar, dst.
• Penyebab: tiap strip hasil generate punya skala sendiri (idle 860 px, walk 675 px tinggi).
• Solusi: normalisasi per strip dengan pitch (0.5 / pitch) — sudah otomatis di rebuild_raw.py.

6. Extractor: pitch disagreement … detect 1.00x1.00 dan frame dikecilkan paksa

• Penyebab: gambar AI adalah pixel art "palsu" (tidak ada grid asli), sementara mode pixel-unfake aktif; dan sel terlalu kecil untuk resolusi asli.
• Solusi: --no-fit-pixel-unfake, perkecil strip dulu (langkah normalisasi), pakai sel yang cukup besar.

7. Warning native logical exceeds the physical cap … capped frames

• Penyebab: pose tidak muat di sel → dikecilkan per frame → skala tidak konsisten.
• Solusi: perbesar sel (--cell-width/--cell-height) sampai warning hilang. Jangan diabaikan.

8. Model tidak bisa membuat strip selebar layout guide

• Gejala: layout guide 768×160 (4.8:1), model maksimal 21:9.
• Solusi: gambar ulang guide di rasio yang didukung dengan jumlah slot sama. Extractor memisahkan pose per komponen, jadi rasio strip tidak harus sama dengan sel.

9. rebuild_raw.py: "ditemukan X pose, harusnya N"

• Penyebab: dua pose saling menempel (pedang/jubah menyentuh tetangga) atau ada efek lepas.
• Solusi: generate ulang strip itu dengan persen tinggi lebih kecil dan "clear gap between poses".

10. Makhluk terbang: posisi melompat-lompat antar frame kepak sayap

• Gejala: naga/burung "meloncat" naik-turun 30–90 px saat sayap turun.
• Penyebab: tidak ada kaki untuk dijadikan anchor, dan registrasi siluet penuh tertipu sayap (sayap adalah bagian terbesar dan bergerak paling jauh; IoU hanya 0.4–0.5).
• Solusi: sejajarkan dengan bagian yang memang diam di gerakan itu:
  • kepak sayap / hover → ujung moncong (titik paling kanan di 45 % atas siluet) atau kepala
  • serangan yang menggerakkan kepala (semburan) → badan/perut (kotak tengah siluet), IoU harus ≥ 0.85
  • tetap geser bulat saja. Goyang naik-turun (bob) ditambahkan di kode game, bukan dari sprite.
• Pencegahan: di prompt tulis bagian mana yang harus diam ("head and neck stay steady").

11. Sayap / ekor terpotong di tepi sel setelah digeser

• Penyebab: geser (curation) memindahkan frame di dalam sel; sel yang pas-pasan jadi terlalu kecil.
• Solusi: perbesar sel lalu extract + compose ulang. Cek: tidak ada piksel alpha di baris/kolom tepi sel.
• Pencegahan: ukuran sel = pose terbesar + jangkauan geser terbesar + margin.

12. Karakter mengecil setiap menyerang / memakai skill, lalu "membesar" lagi saat diam

• Gejala: kepala dan badan terlihat lebih kecil selama serangan/skill; begitu kembali ke idle/jalan, karakter seperti membesar. Paling terasa di frame pedang terangkat (dipakai berkali-kali oleh skill).
• Penyebab:
  1. Normalisasi skala hanya memakai pitch (ukuran pixel palsu). Model menggambar strip serangan dengan pitch yang sama tapi karakter lebih kecil (±6–15 %) — supaya senjata yang terangkat muat di slot.
  2. Cek skala sebelumnya hanya dilakukan untuk idle & walk. Gerakan aksi tidak pernah diukur.
  3. Walk malah dikoreksi berlebihan (+4.5 %) karena registrasi siluet: hasilnya walk ±6 % lebih besar dari idle. Transisi serang (kecil) → jalan (besar) memperparah kesan "membesar".
• Kenapa sulit diukur: tinggi & siluet berubah karena pose (lutut ditekuk, lengan & pedang), pencocokan warna gagal karena tiap strip diberi pencahayaan berbeda, dan di atlas kepala hanya ±20 px.
• Solusi: measure_head_scale.py — cocokkan tepi helm di gambar asli untuk setiap frame semua gerakan terhadap idle frame 0 → median per gerakan → rebuild_raw.py --rel → extract → ukur lagi → ukur ulang hitbox & titik efek. Hasil kasus ini: walk 1.056→1.00, jump 0.97→1.00, attack1 0.94→1.00, attack2 ~0.93→1.015, attack3 1.03→1.00.
• Pencegahan: checklist "Skala antar gerakan — SEMUA gerakan" di sprite-qa.md; rel.json per karakter; setiap gerakan baru wajib diukur terhadap idle sebelum dipakai.

13. Gerakan yang ditambah belakangan skalanya jauh berbeda

• Gejala: gerakan baru (mis. "hurt" yang dibuat setelah gerakan lain selesai) tampil ±30 % lebih kecil.
• Penyebab: tiap generate adalah undian baru; strip baru tidak "ingat" ukuran strip lama walau base sama.
• Solusi: gerakan baru diperlakukan sama seperti yang pertama — measure_head_scale.py terhadap idle frame 0 (pakai rel.json + --head-box dari kartu karakter) → rebuild_raw.py --rel → tambah state ke sprite-request.json → extract → compose.
• Pencegahan: simpan --head-box, --landmark, --target, dan rel.json di kartu karakter supaya pengukuran gerakan baru tinggal dijalankan ulang.

14. Pose jatuh / rebahan tidak bisa diukur lewat kepala

• Gejala: head-check.png untuk strip "down"/"knockdown" berisi lengan atau senjata, bukan kepala.
• Penyebab: kepala miring atau terbalik; template kepala tegak tidak cocok.
• Solusi: pakai rel dari strip lain dengan pitch sama yang terbukti pas, lalu cek visual: jajarkan frame jatuh di samping idle (ukuran badan, lebar bahu, panjang kaki harus sebanding).

15. Jalan terlihat "berselancar": kaki tidak pernah bergantian

• Gejala: karakter bergerak tapi kakinya seperti meluncur; di setiap frame kaki yang sama selalu di belakang.
• Penyebab (dua sekaligus):
  1. Sprite salah dari generate: model menggambar 6 pose dengan kaki terbuka yang mirip-mirip, tanpa pose "melintas" (kaki merapat saat satu kaki mengayun melewati yang lain). Tidak ada frame yang duplikat persis, jadi tidak tertangkap cek duplikat.
  2. Animasi tidak sinkron dengan gerak: fps tetap (9) sementara badan bergerak 95 px/s → kaki "menempuh" ±312 px/s, badan hanya 95 → kaki meluncur.
• Deteksi: measure_atlas.py sekarang mengukur jarak kaki per frame untuk walk/run. Siklus benar: lebar → rapat → lebar → rapat (rasio terkecil/terbesar ≤ 0.45). Kasus ini: [93, 62, 78, 88, 69, 83] rasio 0.67 ✗; setelah diperbaiki [102, 31, 38, 106, 31, 43] rasio 0.29 ✓.
• Solusi sprite: generate ulang dengan prompt yang menyebut kaki mana di depan tiap frame dan bahwa kaki bersilang di frame melintas, plus lampirkan strip walk karakter lain yang sudah benar sebagai referensi gerakan saja (lihat sprite-prompts.md). Strip baru tetap diukur skalanya (kasus ini: 7 % kecil).
• Solusi game: kecepatan animasi dihitung dari jarak tempuh, bukan fps tetap — lihat sprite-runtime.md.

16. Hasil jalan masih sedikit "kejut" setelah skala & posisi benar

• Penyebab: pose kaki hasil generate memang tidak sempurna berurutan (bukan masalah ukuran).
• Solusi: generate ulang strip walk 2–3 kali, pilih yang paling halus; atau buang/ulang frame lewat curation (selected/order). Tidak bisa diperbaiki dengan skala/geser.

17. Frame terakhir serangan/kombo lebih kecil → karakter "membesar" saat kembali ke idle

• Gejala: median skala gerakan sudah lolos (1.00), tapi di game pada perpindahan frame terakhir serangan → idle, karakter terlihat membesar sedikit dan bergeser beberapa piksel.
• Penyebab: koreksi --rel satu angka per strip memakai median semua frame. Model tetap menggambar tiap pose dengan ukuran/proporsi sedikit berbeda; kebetulan frame terakhir (pose kembali siaga) lebih kecil. Contoh nyata (kombo knight): median strip 1.000, tapi frame terakhir kepala ±0.96, dan pose berdiri tegak 11 px lebih pendek dari idle (helm→sabuk 55 vs 58 px), badan bergeser 1–7 px.
• Kenapa lolos QA: median menyembunyikan satu frame yang meleset; frame putar/menunduk tidak terukur sehingga frame terakhir tidak mendapat perhatian khusus.
• Solusi: ukur frame pertama & terakhir tiap serangan langsung terhadap idle frame 0 di atlas (ukuran kepala + tinggi helm→sabuk untuk pose tegak) → koreksi per pose hanya untuk frame itu (rebuild_raw.py --rel 1.143,1.143,1.143,1.143,1.143,1.223) → geser bulat supaya posisi kepala sama dengan idle (write_dx.py … 0,0,0,0,0,1) → extract → compose → cek ulang berdampingan dengan idle. Hasil kasus ini: kepala 0.96 → 0.99 (= idle), combo3 f5 helm 130 → 139 px (idle 141), posisi kepala ±0 px.
• Catatan alat: pose di strip kombo saling menempel (ujung pedang menyentuh jubah tetangga). rebuild_raw.py sekarang memotong di kolom tersentuh-tipis, lalu hanya pose yang dikoreksi ditempel ulang; strip lainnya tetap di-resize utuh (versi lama menata ulang semua pose → pedang tetangga terbelah).
• Pencegahan: checklist "Frame sambungan" di sprite-qa.md.

18. Kepala sudah lolos tetapi badan aksi masih tampak mengecil

• Penyebab: luas rambut/median kepala tidak menangkap pemendekan torso atau kaki, terutama recovery dan ultimate.
• Perbaikan: bandingkan tubuh utuh pada garis kaki sama; ukur crown→sabuk dan sabuk→kaki. Koreksi secukupnya dari original atau regenerate proporsi yang salah. Jangan membesarkan atlas per frame.
• ARCO membutuhkan perbaikan body presence dan ultimate upright baru; hasil rambut saja tidak cukup sebagai bukti.

19. Jump ramai, kaku, atau mengecil sesudah double jump

• Empat pose jump lama memutar crouch ketika karakter sudah airborne; setelah double jump timer berakhir, animasi mengulang crouch dari awal.
• Satu pose pengganti yang terlalu mirip berdiri juga ditolak karena kaku. Solusi final: satu pose jump atletis dengan siku/lutut menekuk, ditahan sepanjang lintasan fisika.
• Double jump menggunakan satu tuck yang benar-benar diputar360°/0,28 s, bukan pose menendang. Keluar dari roll langsung ke jump, dengan pivot terukur.

20. Summon selesai menembak baru karakter bisa bergerak

• Penyebab: durasi pose cast disamakan dengan umur seluruh efek.
• Solusi: cast ultimate ARCO0,50 s terpisah dari drone 2,85 s; I melepas karakter saat peluru keluar. Drone/peluru tidak memakai global hit-stop untuk pemiliknya.

21. Cutout prop tampak kecil dan muzzle meleset

• Satu piksel liar di(0,0) ikut memperbesar bbox drone walaupun hampir tidak tampak. Resize ke112 px lalu membuat objek utama terlalu kecil.
• Solusi: periksa komponen alpha, ambil bbox komponen utama yang benar dengan padding aman, lalu resize sekali dari cutout resolusi asli. Ukur muzzle di output final.
• Jangan memakai pusat gambar sebagai nozzle; wing/ekor dapat menggeser center bbox.

22. HP dua lapis salah ditafsirkan

• Damage trail dan dua baris vertikal bukan yang diminta pengguna.
• Solusi final: satu track, dua fill bertumpuk pada koordinat yang sama; setiap fill mewakili 100HP nyata. Warna depan terkikis lalu reserve. Total200HP, KO hanya pada 0.
• Ultimate tidak memaksa KO atau mengosongkan bar. Nilai final damage ada di gameplay-standard.

23. Asap lari terus keluar saat tertahan

• Penyebab: emisi berbasis waktu atau status tombol, tanpa memeriksa jarak yang benar-benar ditempuh.
• Solusi: emisi tiap 30 px perjalanan di tanah saat state run. Jangan memunculkan asap saat walk/jump atau ketika collision membuat posisi tidak bergerak. Soft gradient harus mengikuti bentuk puff agar tidak menjadi lingkaran keras seperti gelembung.