Bab 1: Aturan & Rencana Pembangunan Aset

Bab ini merangkum lima dokumen sumber dari repo /Users/radityaaydin/repos/new-blender-project/. Repo ini berisi aturan dan rencana kerja untuk membuat aset 3D (10 ekor ikan, lingkungan danau, dan joran pancing) untuk sebuah game memancing sudut pandang orang pertama, dibangun dengan Blender lalu diekspor ke GLB/USDZ. Semua angka, nama file, dan istilah teknis dipertahankan persis seperti sumber aslinya.

1.1 Ringkasan Repo — CLAUDE.md

CLAUDE.md ada di root repo. Isinya jadi titik masuk (entry point) untuk siapa pun — manusia atau agen AI — yang perlu paham repo ini secara cepat. Ini penting terutama untuk agen yang bekerja di repo aplikasi terpisah, supaya mereka tahu cara memakai aset-aset ini dengan benar. Isinya menjelaskan: konsep game, aset mana yang bisa bergerak (animasi) dan mana yang tidak, lokasi file, status pembangunan saat ini, kewajiban lisensi, tugas yang masih tersisa untuk tim aplikasi, dan sebuah peringatan penting soal bug ekspor Blender yang berulang.

Repo ini hanya membuat aset 3D saja — 10 ikan + lingkungan danau + joran pancing — untuk game memancing orang-pertama yang dibangun di Apple RealityKit. Repo ini tidak berisi aplikasi game itu sendiri.

Repo aplikasi terkait

Repo aplikasi ada di ~/repos/c4/CtSPoC, dengan workspace CtSPoC.xcworkspace, dan dua aplikasi: World (renderer RealityKit) dan Rod (kontroler gerak di iPhone). Repo aplikasi menyimpan salinan sendiri dari setiap file FishAssets/Environment/*.usdz di dalam World/World/Assets/Environment/.

Aturan penting: setiap aset yang diekspor ulang di repo ini wajib disalin ulang ke repo aplikasi, begitu juga sebaliknya. Kedua salinan harus identik byte-per-byte, dicek pakai shasum di kedua sisi. Contoh kasus nyata aturan ini ada di CHECKPOINT.md CP42 (sebuah prim DomeLight nyasar yang ditemukan lewat hasil render di aplikasi, lalu diperbaiki di kedua repo sekaligus).

Konsep game (§0)

• Memancing orang-pertama di danau ikan trofi buatan — dalam, buatan manusia/eksotis, sehingga masuk akal spesies laut lepas dan air tawar hidup di satu badan air yang sama.
• Pemain berdiri di dermaga kayu, tinggi mata 1,6 m.
• BUKAN AR — kamera perangkat tidak pernah dipakai; RealityKit merender dunia 3D yang sepenuhnya virtual.
• Input: lempar dengan gerakan flick (flick-to-cast); kemiringan HP mengendalikan lengkungan joran + ketegangan senar saat bertarung dengan ikan.
• Pencahayaan: skybox golden-hour yang di-bake + satu lampu directional statis. Tidak ada sistem siang-malam, tidak ada estimasi cahaya ARKit.
• Alur per ikan: Cruise (berpatroli) → Bite (menyambar umpan) → Caught (meronta → tenang → dipamerkan) → Preview (berputar di turntable, untuk UI koleksi/album).

§1 — Model animasi (tabel paling penting)

Tidak semua jenis aset bergerak dengan cara yang sama. Ini tabelnya:

Catatan khusus per aset

• Langit (sky_dome.usdz): kubah ber-shader Emission unlit; menampilkan gambar golden-hour yang sudah di-bake terlepas dari pencahayaan scene; sengaja tidak punya prim Light/DomeLight. "Lampu directional statis" harus ditambahkan terpisah di kode RealityKit: elevasi ~15°, azimuth 135°, warna hangat 3200–4000K (aturan lengkap ada di AGENTS.md §4.6). Alasan pemisahan ini: pernah ada bug nyata di mana sebuah prim Light ikut ter-bake ke USDZ — sebuah World default yang gelap ikut ter-embed jadi DomeLight dan membuat model ikan jadi nyaris hitam total di Reality Composer (lihat CHECKPOINT.md CP24). Jangan menaruh lampu di dalam aset kubah langit lagi.
• Joran: rantai bone Root → Handle → Rod_01 → Rod_02 → Rod_03 → Tip di dalam rod_main.usdz. Handle bersifat kaku (mencakup pegangan + reel — jangan dibengkokkan). Putar rotasi Rod_01 sampai Tip (amplitudo makin besar ke arah Tip) berdasarkan besaran kemiringan HP. Detail geometri rig (handle di titik origin dunia, ujung/tip di lokal Y=+2,2 m, rest pose) ada di FishAssets/Environment/Documentation/Source_Log.md bagian Asset 4.
• Senar: rod_line.usdz punya rig 6-bone sendiri yang terpisah: Root → Anchor → Line_01 → Line_02 → Line_03 → Line_04, independen dari rig joran, supaya ketegangan bisa dianimasikan tanpa terikat pada lengkungan joran. Titik penyambungan (penting): origin lokal senar (0,0,0) harus berada di ekor (tail) bone Tip milik rod_main, bukan kepalanya (head) — koordinat dunia (0, 2,2, 0) pada rest pose, bukan (0, 1,95, 0). Salah menukar head vs tail ini benar-benar pernah terjadi dan baru ketahuan saat verifikasi (lihat Source_Log Asset 5) — akibatnya senar diam-diam terpasang 0,25 m lebih pendek dari ujung joran yang sebenarnya.
• Air: tidak ada gerakan bawaan — material animated-normal/riak/refraksi/depth-fade harus dibuat di RealityKit. UV mesh sudah di-skala sedemikian rupa sehingga 1 ubin (tile) UV = 2,04 m — sesuaikan tiling riak berdasarkan angka ini.

§2 — Struktur folder

FishAssets/
├── Fish0N_Species/…/{Cruise,Bite,Caught,Preview}/Species_State.{glb,usdz}   (10 ikan, selesai)
└── Environment/
    ├── dock_main.usdz                (selesai, hero 2K)
    ├── water_surface.usdz            (selesai, statis)
    ├── terrain_underwater.usdz       (selesai)
    ├── rod_main.usdz                 (selesai, hero 2K, hanya rig)
    ├── rod_line.usdz                 (selesai, hanya rig, independen dari joran)
    ├── sky_dome.usdz                 (selesai, unlit, tanpa lampu baked, panorama 4K)
    ├── terrain_horizon_ring.usdz     (selesai, cincin transisi bukit+pepohonan)
    ├── rock_shoreline_01/02/03.usdz  (selesai, 3 batu berbeda)
    ├── foliage_grass_01.usdz         (selesai, alpha-cutout)
    ├── foliage_reed_01.usdz          (selesai, alpha-cutout)
    ├── tree_01/02/03.usdz            (selesai — cemara/pohon daun lebar/palem)
    ├── prop_bucket_01.usdz           (selesai)
    ├── prop_tacklebox_01.usdz        (selesai)
    ├── prop_rope_01.usdz             (selesai)
    └── Documentation/
        ├── Asset_Candidates.md       (keputusan sourcing, skor, kandidat yang ditolak)
        └── Source_Log.md             (asal-usul, semua modifikasi, semua log perbaikan)

Dokumen lain: FishAssets/AGENTS.md (kumpulan aturan lengkap), FishAssets/BUILD_PLAN_ENV.md (rencana lingkungan + tabel progres), FishAssets/BUILD_PLAN.md (rencana ikan), FishAssets/CHECKPOINT.md (log pembangunan kronologis, entri terbaru ada di paling bawah).

§3 — Status terkini (per 2026-07-17 menurut file ini)

• Ikan: 8/10 sudah lengkap sepenuhnya (4 state baked, GLB+USDZ masing-masing) — Bluefin, Yellowfin, Skipjack, Giant Trevally, Grouper, Marlin, Sailfish, Mekong Catfish. Clownfish + Blue Tang hanya punya satu animasi asli (3 "state" lainnya cuma duplikat identik byte-per-byte, tanpa USDZ) — di luar roster inti.
• Lingkungan: 18/18 selesai — 6 aset esensial (dermaga, air, terrain, joran, senar, langit) + 11 aset sekunder (3 batu, rumput, tanaman reed, 3 pohon, 3 properti dermaga) + 1 aset penghalus (terrain_horizon_ring, ditambahkan setelah review "terlihat seperti kardus", lihat §7). Pembangunan lingkungan sudah selesai penuh, tidak ada yang terblokir.

§4 — Fakta skala & konvensi

• 1 unit Blender = 1 meter, skala dunia nyata di seluruh proyek.
• Ikan berkisar dari 0,6 m (Grouper) sampai 3,0 m (Marlin).
• Badan air ~80 × 60 m, kedalaman basin sampai −11 m; dek dermaga di +0,80 m di atas garis air z=0; tiang dermaga menembus sampai −0,67 m (sengaja dibuat rak dangkal supaya tiang dermaga menancap ke terrain — lihat Source_Log Asset 3).
• Semua aset lingkungan pakai penamaan snake_case (dock_main.usdz); ini menggantikan PascalCase yang dipakai sebelumnya untuk ekspor ikan (Marlin_Cruise.glb) — file ikan tidak ikut diganti nama (item terbuka, dicatat di BUILD_PLAN_ENV.md §7).
• Setiap aset adalah file USDZ terpisah — bukan satu scene gabungan — supaya aplikasi bisa mengatur posisi/skala/animasi masing-masing secara independen.

§5 — Lisensi

Beberapa aset yang di-sourcing berlisensi CC-BY (wajib mencantumkan atribusi), bukan CC0. Teks atribusi yang wajib dicantumkan ada di Source_Log.md masing-masing aset (untuk Environment, atau tiap ikan). Ini secara eksplisit disebut sebagai syarat kepatuhan lisensi, bukan sekadar bonus.

§6 — TODO eksplisit untuk sisi aplikasi (BELUM dikerjakan di repo ini)

1. Shader air — normal animasi, riak, refraksi, depth fade. Sudah ditandai, belum dibuat.
2. Kontrol rig joran + senar berbasis kemiringan HP — putar bone joran secara live tiap frame dari kemiringan perangkat; atur ketegangan senar independen dari lengkungan joran; sambungkan senar di ekor (tail) bone Tip joran, bukan kepalanya (head).
3. Layar kredit/atribusi — ambil teks atribusi dari setiap Source_Log.md. Catatan: HDRI milik sky_dome.usdz (evening_road_01_puresky, dari Poly Haven) dan tekstur pasir milik terrain_underwater (damp_sand, dari Poly Haven) keduanya CC0 — tidak perlu atribusi. Setiap aset batu/pohon/properti/dermaga/joran berlisensi CC-BY — atribusi wajib untuk itu.
4. Tambahkan DirectionalLight RealityKit sesuai AGENTS §4.6 (elevasi ~15°, azimuth 135°, warna hangat 3200–4000K) — sky_dome.usdz sengaja dikirim tanpa sumber cahaya sendiri. Pertimbangkan juga memakai HDRI yang sama (evening_road_01_puresky) sebagai sumber IBL/pencahayaan-lingkungan supaya warna ambient objek foreground cocok dengan langit — ini yang memperbaiki kesan "kardus" saat verifikasi render (lihat §7).

§7 — Peringatan kritis soal ekspor USD Blender

Exporter USD Blender punya tabel terjemahan shader yang sempit. Yang bisa ditangani secara konsisten hanya:

1. Nilai default_value flat pada Principled BSDF (contoh: warna tan polos milik rod_line), dan
2. Sambungan langsung Image Texture → Base Color / Image Texture → Normal Map → Normal.

Selain dua pola itu, exporter tidak bisa diandalkan — sebuah node shader Emission mandiri, dan sebuah node graph prosedural (Geometry/Math/ColorRamp yang mengendalikan Base Color), keduanya pernah dicoba dan diam-diam diekspor jadi material kosong atau abu-abu default, tanpa error ekspor sama sekali, dan tetap lolos usdchecker. Ini bukan hipotesis — sky_dome.usdz pernah terkirim tanpa data shader sama sekali selama dua siklus ekspor ulang sebelum ketahuan; gradien warna yang dimaksudkan untuk terrain_horizon_ring diam-diam berubah jadi abu-abu flat (0.8,0.8,0.8). Cerita lengkap ada di CHECKPOINT.md CP38.

Prosedur wajib saat ekspor ulang: sederhanakan setiap material ke dua pola yang didukung di atas sebelum ekspor, lalu cek ulang dengan:

unzip -o file.usdz -d /tmp/check && usdcat /tmp/check/*.usdc | grep -A2 "diffuseColor\|def Shader"

usdchecker yang lolos secara eksplisit disebut tidak cukup — itu hanya memvalidasi kesesuaian skema, bukan apakah warna/tekstur yang dimaksud benar-benar masuk ke dalam file.

Item terbuka / TODO / keterbatasan (dari CLAUDE.md)

• Shader air belum dibuat (TODO eksplisit sisi aplikasi).
• Kontrol rig joran/senar berbasis kemiringan belum dibuat (TODO sisi aplikasi).
• Layar kredit/atribusi belum dibuat (TODO sisi aplikasi).
• DirectionalLight RealityKit belum ditambahkan (TODO sisi aplikasi).
• File ikan masih pakai penamaan lama PascalCase, belum dimigrasi ke snake_case (dicatat, belum mendesak).
• Clownfish + Blue Tang belum lengkap (hanya 1 dari 4 state animasi yang asli) tapi memang sudah di luar cakupan roster inti.
• Peringatan umum: setiap ekspor ulang Blender di masa depan wajib dicek manual dengan usdcat/grep karena validator yang lolos bisa menyembunyikan material yang diam-diam rusak.

1.2 Buku Aturan Utama — FishAssets/AGENTS.md (583 baris)

Ini adalah rulebook utama untuk seluruh pipeline aset — dokumen paling detail dan paling sering direvisi/dianotasi. Isinya mencakup: kewajiban dokumentasi, spesifikasi per jenis aset (lingkungan, joran, ikan), daftar spesies historis, aturan sourcing/lisensi, semua spesifikasi teknis (budget geometri, tingkatan tekstur, rigging, animasi, aturan sistem koordinat), rubrik penilaian, pipeline 13-fase untuk ikan, struktur file/folder, kode setup material PBR, pengaturan ekspor, alur kerja git, dan daftar "pelajaran yang dipetik" dari bug-bug yang pernah terjadi. Banyak bagian memiliki anotasi "SUPERSEDED" (digantikan) yang menunjukkan proyek ini pernah berbelok arah secara signifikan di tengah jalan — dari aplikasi kolam AR menjadi scene danau virtual non-AR, dan dari daftar spesies sembarangan menjadi roster ikan tangkapan besar khas Indonesia yang sudah dikonfirmasi.

§0 — Aturan Wajib Update Dokumentasi

Tidak ada tugas aset yang dianggap "selesai" sampai semua dokumen di-update. Tabel yang harus diperbarui setiap selesai membuat satu aset ikan:

Checklist verifikasi sebelum dianggap selesai: CHECKPOINT.md punya entri untuk setiap fase di sesi ini; status pipeline di Asset_Candidates.md diperbarui; Source_Log.md mencatat semua modifikasi berstempel waktu; semua file .md sudah di-commit+push ke git@github.com:K-ere-Horee/blender-assets.git; file GLB + Blend sudah diekspor/disimpan; tidak ada dokumen yatim atau file yang hilang. "Kalau dokumen belum diperbarui, tugasnya belum selesai."

§1 — Jenis Aset & Persyaratan

§1.1 Lingkungan — Scene Kolam Imersif

Ditandai SUPERSEDED (CP36, 2026-07-16): spesifikasi awal (bidang datar yang responsif terhadap permukaan AR yang terdeteksi, 3 ukuran Small/Medium/Large, format GLB) berasumsi memakai AR passthrough; padahal game ini BUKAN AR — ini scene 3D orang-pertama yang sepenuhnya virtual (mode non-AR RealityKit). Jadi: tidak ada deteksi bidang, tidak ada penyesuaian permukaan saat runtime, tidak ada 3 varian ukuran, dan wajib ada langit yang benar-benar dirender. Tabel spesifikasi yang berlaku sekarang:

§1.2 Joran Pancing (aset hero orang-pertama)

Ditandai EXPANDED (CP36) — aset yang paling dekat dengan kamera, jadi kualitasnya harus paling tinggi.

§1.3 Ikan (per Spesies)

4 state animasi wajib:

Persyaratan ekspor per state ikan:

§2 — Urutan Spesies

Aturannya: selesaikan satu ikan sepenuhnya sebelum mulai ikan berikutnya. Ditandai SUPERSEDED (CP28, 2026-07-15) — daftar awal digantikan oleh set "tangkapan besar Indonesia" (lihat BUILD_PLAN.md/CHECKPOINT.md untuk urutan yang berlaku). Target aktif per catatan tersebut: Bluefin Tuna (Fish04, selesai), Yellowfin Tuna (Fish07, selesai), Giant Trevally (Fish05, rusak/perlu dibangun ulang), Skipjack Tuna (Fish08, tertunda), Grouper (Fish09, tertunda), Marlin (Fish03, saat itu terblokir). Clownfish/Blue Tang/Mekong Giant Catfish sudah selesai tapi di luar set ini.

Roster awal (disimpan untuk sejarah):

§3 — Strategi Perolehan Aset

Prioritas utama: cari aset gratis + legal terbaik; membuat dari nol hanya jika pencarian menyeluruh sudah gagal.

§3.1 Urutan Pencarian Sumber

1. Sketchfab (utama, variasi model CC gratis terbanyak)
2. Poly Haven (CC0, pilihan ikan terbatas)
3. Smithsonian Open Access (historis/seni, tidak ada ikan ditemukan)
4. BlendSwap (model komunitas berbasis Blender)
5. CGTrader Free (filter gratis+lisensi)
6. Internet Archive (koleksi 3D)
7. Repo GitHub
8. Repo akademik (dataset riset)
9. Hunyuan3D / Hyper3D Rodin — pilihan terakhir saja

§3.2 Persyaratan Pencarian

Minimal 5 kali percobaan pencarian per sumber sebelum pindah ke sumber lain; dokumentasikan setiap kandidat (diterima maupun ditolak); catat kegagalan pencarian di Source_Log.md.

§3.3 Persyaratan Lisensi

§4 — Spesifikasi Teknis

Arahan gaya: gaya game semi-realistis — proporsi realistis, detail disederhanakan, seperti simulator memancing; geometri bersih dan efisien untuk engine.

§4.1 Geometri (budget ikan/hero)

Catatan (CP36): §4.1 hanya berlaku untuk ikan/hero, tidak berlaku untuk properti lingkungan (kerikil tidak butuh 5 ribu tris) — pakai §4.1b sebagai gantinya.

§4.1b Geometri — Lingkungan (CP36)

Filosofinya: poli rendah-sampai-menengah + normal map, jangan pernah high-poly; pakai ulang/instance beberapa model daripada membuat banyak model unik (jumlah draw call lebih penting daripada jumlah tris di iPad).

Target scene: total scene yang sudah dirakit ≲150 ribu tris dan ≲60 draw call di iPad, dicapai lewat instancing.

§4.2 Tekstur

§4.2b Tingkatan tekstur — Lingkungan (CP36)

Semua material lingkungan wajib PBR penuh: BaseColor + Normal + Roughness + Metallic (metallic=0 untuk semua permukaan alami — batu/kayu/air/tumbuhan bersifat dielektrik; hanya perangkat keras joran/reel yang boleh metallic).

§4.6 Konvensi Pencahayaan (CP36) — wajib, supaya semua aset serasi

Setiap aset lingkungan harus dibuat/dipratinjau di bawah satu setup pencahayaan yang sama, kalau tidak, hasilnya tidak akan cocok saat dirakit:

HDRI yang sama menggerakkan langit yang terlihat maupun IBL — jangan menerangi satu aset dengan environment yang berbeda "cuma buat pratinjau," karena hasilnya akan melenceng.

§4.3 Prioritas rigging

§4.4 Animasi

Siklus renang: 48 frame @ 24fps (2 detik). Jenis gerakan: undulasi tubuh, dayungan sirip pektoral, gelombang sirip dorsal/anal, sinkronisasi sirip ekor (caudal). Jumlah keyframe: sekitar 400–500 keyframe tersebar di 9–10 bone.

§4.5 Struktur Armature

Armature standar ikan, 10 bone:

Root → Spine → Spine.001 → Tail → Caudal_Fin
  └→ Head
  └→ Dorsal_Fin
  └→ Anal_Fin
  └→ Pectoral_Fin_L
  └→ Pectoral_Fin_R

§5 — Sistem Koordinat (KRITIS)

§5.1 Setup Blender

X = panjang tubuh (kepala-ekor), Y = lebar (lateral), Z = tinggi (punggung-perut).

§5.2 Persyaratan Armature

Bone Root WAJIB mengarah ke +Y (kepala di origin, ekor di +0,002 Y) — ini menghasilkan matrix_local identitas, yang menghasilkan rotasi ekspor glTF standar. Semua bone tubuh (Spine, Head, Tail) berada di bidang XZ atau sepanjang sumbu-X. Rotasi objek armature harus (0,0,0) — armature-nya sendiri tidak boleh dirotasi.

§5.3 Perilaku Ekspor glTF

Exporter glTF Blender mengubah orientasi Z-up menjadi Y-up dengan menambahkan rotasi −90° pada sumbu X hanya pada node ROOT armature, menghasilkan Root rotation: [-0.7071, 0, 0, 0.7071] (ini standar/benar). Exporter juga menukar Y↔Z pada vertex mesh: Blender X (panjang tubuh) → GLB X (panjang tubuh); Blender Y (lebar) → GLB Z (lebar); Blender Z (tinggi) → GLB Y (tinggi).

§5.4 Kesalahan Orientasi yang Umum Terjadi

§5.5 Checklist Verifikasi (setelah ekspor)

Rotasi Root = [-0.7071, 0, 0, 0.7071]; sumbu X mesh = panjang tubuh (sumbu terpanjang); sumbu Y mesh = tinggi (punggung-perut); sumbu Z mesh = lebar (lateral); tidak ada node tambahan (empty boleh saja kalau memang cuma neutral_bone hasil auto-weight).

§6 — Rubrik Penilaian (dari 100)

Ambang batas diterima: skor minimal 50/100; lisensi harus termasuk jenis yang diterima; geometri harus dalam rentang LOD0 (5k–30k tris).

§7 — Pipeline 13 Fase

Dikerjakan berurutan untuk setiap spesies ikan:

§8 — Struktur File

§8.0 Konvensi Penamaan (CP36)

KEPUTUSAN (dari user, 2026-07-16): pakai snake_case untuk SEMUA aset, menggantikan PascalCase lama. Pola: <kategori>_<subjek>[_<varian>][_<NN>].usdz.

Aturannya: huruf kecil semua, hanya garis bawah (underscore), tanpa spasi/camelCase/PascalCase; varian bernomor pakai 2 digit dengan nol di depan (_01, _02). Aset ikan direncanakan diganti nama dari PascalCase lama (Marlin_Cruise.glb → marlin_cruise.glb) — dicatat sebagai tugas migrasi terpisah; semua referensi silang di dokumen juga perlu diperbarui. (Menurut CLAUDE.md/BUILD_PLAN_ENV.md, penggantian nama ini belum terjadi.)

Pohon folder lengkap yang dimaksudkan (ilustratif — mencerminkan kondisi awal/ideal, misalnya menunjukkan Pond_Small/Medium/Large yang belakangan sudah digantikan):

FishAssets/
├── AGENTS.md
├── CHECKPOINT.md
├── Environment/
│   ├── Pond/
│   │   ├── Pond_Small.glb
│   │   ├── Pond_Medium.glb
│   │   └── Pond_Large.glb
│   └── FishingRod/
│       ├── FishingRod.glb
│       └── FishingRod.blend
├── Fish01_Clownfish/
│   ├── Fish01_Clownfish.blend
│   ├── Cruise/Clownfish_Cruise.glb        (siklus renang 48 frame)
│   ├── Bite/Clownfish_Bite.glb            (sambaran 24 frame, 2× kecepatan)
│   ├── Caught/Clownfish_Caught.glb        (transisi 72 frame)
│   ├── Preview/Clownfish_Preview.glb      (idle 48 frame)
│   ├── Model/clownfish.glb + download_urls.json
│   ├── Textures/
│   └── Documentation/{Asset_Candidates.md, Source_Log.md, Scientific_Validation.md}
├── Fish02_BlueTang/ (struktur sama)
├── Fish03_Marlin/             ← TERBLOKIR (belum ada sumber CC gratis, saat penulisan)
├── Fish04_BluefinTuna/        ← SELESAI
├── Fish05_GiantTrevally/      ← RUSAK, perlu dibangun ulang
├── Fish06_MekongGiantCatfish/ ← TERBLOKIR
├── Fish07_YellowfinTuna/      ← SELESAI
└── References/{Images/, Papers/, Videos/}

§9 — Setup Material PBR (kode standar Blender)

material.node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value = (R, G, B, 1.0)
material.node_tree.nodes["Principled BSDF"].inputs["Roughness"].default_value = 0.5
material.node_tree.nodes["Principled BSDF"].inputs["Coat Weight"].default_value = 0.3
material.node_tree.nodes["Principled BSDF"].inputs["Subsurface Weight"].default_value = 0.1

Aturan pemetaan tekstur: Base Color → input Base Color; Roughness → input Roughness (mungkin butuh penyesuaian ColorRamp); Normal → input Normal (set ke Non-Color); AO → Ambient Occlusion atau dikalikan dengan Base Color.

§10 — Pengaturan Ekspor (kode contoh)

bpy.ops.export_scene.gltf(
    filepath="path/to/export.glb",
    use_selection=False,
    export_apply=True,
    export_animations=True,
    export_skins=True,
    export_image_format='AUTO',
    export_format='GLB'
)

Checklist ekspor: semua transform sudah diterapkan (apply); mesh berpusat di origin; armature di origin dengan Root mengarah ke +Y; tidak ada objek empty tambahan; action animasi sudah ditugaskan (assigned) ke armature; ukuran file <10MB per ikan.

§11 — Persyaratan Dokumentasi per spesies ikan

• Asset_Candidates.md: semua kandidat (diterima+ditolak), rincian skor, pilihan akhir + alasannya, tabel status pipeline.
• Source_Log.md: URL sumber asli + lisensi, metode download, semua modifikasi beserta alasannya, log perbaikan.
• Scientific_Validation.md (opsional tapi disarankan): taksonomi/klasifikasi, karakteristik fisik, catatan perilaku renang, detail warna/pola.
• CHECKPOINT.md (level proyek): checkpoint berstempel waktu per fase yang selesai, tabel progres keseluruhan, isu yang diketahui + item tertunda.

§12 — Alur Kerja Git

Repo: git@github.com:K-ere-Horee/blender-assets.git. Konvensi commit:

Add Fish0N SpeciesName assets

- Description of what was added
- Key specs (tri count, materials, animation)
- License and attribution

Yang di-commit: file kerja .blend, ekspor .glb, model/tekstur sumber (untuk atribusi), file dokumentasi, AGENTS.md/CHECKPOINT.md. Yang TIDAK di-commit: backup .blend1/.blend2, .DS_Store/Thumbs.db, file temporary.

§13 — Isu yang Diketahui & Pelajaran yang Dipetik

• Perubahan API Blender 5.1: Action.fcurves sudah dihapus — pakai keyframe_insert() pada pose bone; action.layers adalah sistem layer baru; import OBJ sudah tidak tersedia — pakai import GLB sebagai gantinya.
• Download Sketchfab: tool download BlenderMCP rusak; solusinya — baca API key dari preferences, pakai urllib.request untuk memanggil API, download lewat shell curl.
• Sistem koordinat glTF: vertex mesh ditukar Y↔Z oleh exporter; Root armature mendapat rotasi −90° pada sumbu X; bone Root harus mengarah ke +Y untuk ekspor yang benar; Root mengarah ke +X → matrix_local tidak identitas → rotasi salah di GLB.
• Weight Painting: Auto-weights (Bone Heat) sering gagal untuk bone kecil; pakai envelope weights sebagai cadangan, lalu berikan bobot zona anatomi secara manual (berdasarkan jarak-dari-pusat-bone, falloff berbanding terbalik dengan jarak).
• Menganimasikan banyak rantai bone sekaligus (mesh sobek): sebelum menganimasikan beberapa rantai bone secara independen (misalnya bone per-jari sirip dorsal, pasangan sirip pektoral/anal), cek dulu apakah mereka berbagi bobot skin (skin weight) pada vertex mesh yang sama — jangan asumsikan rantai yang namanya berbeda pasti independen secara mekanis hanya karena terlihat berbeda secara semantik. Cek lewat vertex.groups, cari bobot >0,05 yang menyebar dari dua rantai bone berbeda — karakter hasil import/rig profesional yang kompleks sering mencampur bobot di titik-titik sambungan yang berdekatan. Kalau ada rantai yang berbagi bobot: (a) jaga agar tetap sefase (oscillation phase/frekuensi/sumbu rotasi sama), atau (b) kecilkan amplitudo animasi mendekati nol di area yang berbagi bobot tersebut, biarkan hanya segmen luar yang bobotnya bersih bergerak bebas. Frekuensi/fase/sumbu yang tidak cocok pada vertex yang dibagi bersama akan membuat mesh sobek secara visual (jari sirip lepas, sendi patah salah arah) walaupun amplitudo tiap rantai terlihat baik-baik saja jika dilihat sendiri-sendiri. Selalu cek waras (sanity-check) rig yang dianimasikan dengan render (sudut lebar + close-up di area sirip/sendi, mencakup seluruh rentang frame termasuk amplitudo puncak) sebelum menganggap animasi selesai — rest pose atau satu frame saja bisa terlihat baik padahal gerakannya tetap merobek mesh.
• Pembersihan hirarki import Sketchfab: import GLB dari Sketchfab membuat hirarki empty yang dalam (5+ level: Sketchfab_model > fbx > Object_2 > RootNode > ExportRIG); ini membuat transform (skala, rotasi) ikut ter-bake ke dalam matrix dunia armature, sehingga armature bisa menunjukkan matrix_world yang tidak identitas walaupun lokasi/rotasi/skala-nya sendiri sudah identitas. Selalu putuskan rantai parent (obj.parent = None) sebelum dipakai, lalu terapkan (apply) semua transform baik di armature maupun body. Vertex mesh body bisa saja bergeser dari armature setelah di-append — cek keselarasan dengan membandingkan batas vertex vs posisi kepala bone. Objek duplikat sering muncul kalau memuat dari beberapa file .blend sekaligus — pastikan dulu salinan mana yang harus dipakai sebelum menghapus yang lain. File .blend yang berdiri sendiri sebaiknya hanya berisi tubuh ikan + armature, tanpa empty yang nyasar.

§14 — Catatan Integrasi RealityKit

Ditandai DIKOREKSI (CP36, 2026-07-16): game ini BUKAN AR — tidak memakai kamera perangkat; merender scene 3D orang-pertama yang sepenuhnya virtual di iPad/macOS lewat mode non-AR RealityKit. Konsekuensinya: tidak ada deteksi bidang, tidak ada penyesuaian permukaan saat runtime, tidak ada estimasi cahaya ARKit (pencahayaan dibuat sendiri sesuai §4.6), langit adalah geometri yang dirender, bukan hasil passthrough kamera.

• Aset lingkungan + joran: hanya format USDZ (satu file per aset, masing-masing diposisikan/diskala/dianimasikan lewat kode). Ikan tetap memakai pasangan GLB + USDZ seperti biasa.
• Skala: 1 unit Blender = 1 meter, scene harus konsisten dengan ikan yang sudah dikirim (grouper 0,6 m → marlin 3,0 m), kolam berukuran sedemikian rupa supaya ikan terlihat meyakinkan.
• Kamera orang-pertama berada di garis pantai, tinggi mata ~1,6 m — buat/pratinjau dari sudut pandang itu, bukan dari tampilan orbit.
• Animasi diputar otomatis kalau sudah dikonfigurasi; lengkungan joran + ketegangan senar digerakkan dari kode (kemiringan perangkat) — ekspos bone-nya, jangan hanya mengandalkan klip yang di-bake.
• Validasi setiap aset dengan usdchecker sebelum disetujui; pengecekan akhir di Reality Composer Pro.

Item terbuka / TODO / keterbatasan (dari AGENTS.md)

• §1.1 dan §14 sama-sama menandai spesifikasi lama kolam-AR sebagai sudah mati/digantikan — perubahan arah proyek besar yang perlu diketahui pembaca saat membaca bagian-bagian lama.
• Daftar spesies di §2 hanya bersifat historis; roster sebenarnya dicatat di tempat lain (BUILD_PLAN.md/CHECKPOINT.md).
• Migrasi penamaan file ikan dari PascalCase→snake_case (§8.0) masih jadi tugas terbuka yang belum disentuh.
• Marlin (Fish03) dan Mekong Giant Catfish (Fish06) ditampilkan sebagai "TERBLOKIR" di pohon folder ilustratif — status ini berlaku saat terakhir bagian itu ditulis, sudah digantikan menurut CLAUDE.md (keduanya belakangan selesai).
• Giant Trevally (Fish05) ditampilkan sebagai "RUSAK, perlu dibangun ulang" di pohon folder yang sama.
• Langkah git push disebut "Tidak berlaku — belum ada repo lokal" menurut BUILD_PLAN.md (lihat Dokumen 3), padahal AGENTS §12 mendokumentasikan alur kerja git yang lengkap — kedua dokumen ini saling bertentangan di titik ini; dicatat sebagai celah proses, bukan diselesaikan.

1.3 Rencana Pembangunan Ikan — FishAssets/BUILD_PLAN.md (116 baris)

Ini adalah peta jalan kerja untuk membangun roster ikan — hasil saringan dan rangkuman aturan AGENTS.md yang relevan menjadi satu checklist per-ikan, ditambah catatan pembangunan konkret per spesies (UID sumber, cacat yang diketahui, target jumlah poligon). Aturannya: bangun satu ikan sampai tuntas melalui seluruh 13 fase sebelum mulai ikan berikutnya.

Cakupan & Urutan

Roster yang sudah dikonfirmasi (CHECKPOINT.md CP28); Bluefin Tuna (Fish04) sudah selesai. Urutan pembangunan sisanya, dari termudah ke tersulit:

Spesifikasi umum yang wajib dipatuhi setiap ikan (ringkasan dari AGENTS.md)

• Pipeline 13-fase (§7): 01 Validasi-ilmiah → 02 Pencarian → 03 Download → 04 Verifikasi → 05 Akuisisi → 06 Retopo (lewati jika sudah bersih) → 07 UV (lewati jika >95%) → 08 Tekstur (PBR Principled) → 09 Rig (10-bone, lewati jika sudah di-rig) → 10 Animasi (4 state) → 11 Poles → 12 Ekspor → 13 Finalisasi/dokumentasi.
• Geometri (§4.1): LOD0 = 5k–30k tris. Decimate hasil scan mentah ke rentang ini dengan hati-hati — Trevally sempat hancur karena decimate yang buruk memecah hasil photoscan.
• Tekstur (§4.2): 2K lebih disukai, jaga tetap ≤2K supaya file ekspor tidak kebesaran (pelajaran dari Fish04).
• Rig (§4.5): armature standar 10-bone (Root→Spine→Spine.001→Tail→Caudal_Fin, +Head, Dorsal_Fin, Anal_Fin, Pectoral_Fin_L/R). Lewati jika model sudah punya rig yang bisa dipakai.
• 4 state animasi (§1.3): Cruise (loop renang), Bite (sambaran cepat ~2×), Caught (meronta→tenang→dipajang), Preview (idle). Tuna/trevally/marlin adalah perenang thunniform — jaga badan tetap kaku, dorongan berasal dari batang ekor (peduncle) + sirip ekor bulan sabit (lunate caudal fin), minim undulasi tubuh. Grouper adalah ikan karang yang lebih lambat — gerakan pektoral/tubuh lebih banyak.
• Sistem koordinat (§5): Bone Root mengarah ke +Y (kepala di origin, ekor di +Y) → matrix_local identitas → rotasi root glTF yang benar [-0.7071,0,0,0.7071]. Panjang di sumbu tubuh, tinggi di Z, lebar di X. Terapkan (apply) SEMUA transform; mesh berpusat di origin; tanpa empty yang nyasar. Hasil scan Sketchfab mentah biasanya ter-import dengan rotasi belum di-apply (lokal≠dunia) dan hirarki empty yang dalam — putuskan parent + apply transform dulu (§13 pembersihan Sketchfab).
• Penjaga anti-sobek mesh (§13): cek bobot skin yang dibagi bersama antar-rantai bone sebelum menganimasikan secara independen; jaga area yang berbagi bobot tetap sefase atau kecilkan amplitudo mendekati nol. Cek waras setiap animasi dengan render (sudut lebar + close-up sirip, pada amplitudo puncak).
• Ekspor (§10): GLB (export_animation_mode='ACTIVE_ACTIONS' — satu action per file state, pelajaran dari Fish04) + USDZ (relative_paths=True, export_animation=True, convert_world_material=False, Y-up). Validasi USDZ dengan usdchecker. Target <10 MB per file.
• Dokumentasi (wajib): update CHECKPOINT.md + Asset_Candidates.md/Source_Log.md/Scientific_Validation.md milik ikan tersebut setelah setiap ikan selesai. Catatan: "Git push saat ini tidak berlaku — belum ada repo lokal."

Catatan infrastruktur (spesifik lingkungan kerja, bukan aturan)

Blender berjalan secara live (GUI) lewat MCP TCP di localhost:9876; dikendalikan dengan helper execute_code berbasis raw-socket (tmp/blend.py). Import glTF butuh temp_override(window/screen/area/region) untuk viewport, kalau tidak akan error di context.object. Download Sketchfab: baca sketchfab_api_key dari preferences addon Blender, ambil lewat urllib (curl kena error sandbox). Id engine render adalah BLENDER_EEVEE (bukan _NEXT).

Rencana per ikan

1. Yellowfin Tuna (Fish07) — SIAP DIBANGUN. Sumber: Sketchfab CC0 ffishAsia (UID d4eeea976932…), sudah di-download ke Model/gltf/. 1,39 juta tris, tanpa rig, ~26 m (skala salah — perlu dikoreksi), pose mati dengan mulut terkulai terbuka, rotasi belum di-apply. Fase 01–03 sudah selesai.

• 04/05: sudah di-import; gabungkan tile-tile body, hapus color-chart yang mengambang.
• Pra-11 pembersihan: apply transform (perbaiki rotasi lokal≠dunia), pusatkan ke origin, ubah skala ke panjang ≈2,0 m (skala yellowfin sungguhan), luruskan pose yang terkulai, tutup/rilekskan rahang.
• 06 Retopo → decimate hati-hati ke LOD0 (~15–25k tris); pastikan tidak pecah setelah decimate (rasio edge batas harus tetap rendah) — ini persis kegagalan yang menghancurkan Trevally.
• 07 UV: UV hasil photoscan sudah ada, dipertahankan kalau masih bisa dipakai, kalau tidak, tekstur yang sudah di-bake masih tetap bisa dipetakan.
• 08 Tekstur: bangun ulang PBR Principled dari baseColor hasil scan, turunkan resolusi ke ≤2K.
• 09 Rig: armature standar 10-bone, Root +Y; weight-paint (fallback berbasis zona kalau auto-weight gagal).
• 10 Animasi: 4 state thunniform; verifikasi dengan render sweep (penjaga anti-sobek mesh).
• 12 Ekspor: 4 file GLB + 4 file USDZ ke Cruise/Bite/Caught/Preview; validasi; simpan file .blend.
• 13 Dokumentasi: update Source_Log/Asset_Candidates/Scientific_Validation + CHECKPOINT.

2. Giant Trevally (Fish05) — BANGUN ULANG DARI SUMBER. Aset yang ada sudah tidak bisa diselamatkan (geometri dasarnya pecah, dikonfirmasi dengan armature dinonaktifkan).

• 03 Download ulang: Sketchfab CC0 ffishAsia (UID e6446df50ba746ed8ce8a3dd66b3b8e8) lewat API Sketchfab → folder Model/ baru (folder sumber lokal lama sudah hilang).
• Urutan sama seperti Yellowfin (bersihkan → decimate hati-hati dengan cek pecahan → tekstur → rig → 4 animasi → ekspor → dokumentasi). Pakai ulang Documentation GT yang sudah ada.
• Ganti file .blend dan GLB yang rusak hanya setelah hasil bangun ulang tervalidasi.

3. Skipjack Tuna / Cakalang (Fish08) — PENCARIAN + BANGUN.

• 01 Validasi ilmiah: Katsuwonus pelamis — skala game ~0,8–1 m, punggung biru gelap, perut perak dengan 4–6 garis lurik gelap memanjang di sisi bawah (ciri identifikasi), thunniform.
• 02 Pencarian: Sketchfab CC0/CC-BY dulu (5+ percobaan/sumber, §3), skor ≥50 (§6), dalam rentang LOD0. Sumber cadangan sesuai §3.1.
• 03–13: pipeline standar (kemungkinan besar perlu di-rig dari nol seperti tuna-tuna lainnya).

4. Grouper / Kerapu (Fish09) — PENCARIAN + BANGUN.

• 01 Validasi ilmiah: misalnya Epinephelus sp. — ikan karang bertubuh gempal, mulut besar, corak coklat/zaitun berbintik-bintik; bukan thunniform → renang carangiform/labriform yang lebih lambat, gerakan pektoral + tubuh lebih banyak dalam animasi.
• 02 Pencarian → 03–13: pipeline standar. Peluang bagus untuk menemukan model ikan karang gratis.

5. Marlin (Fish03) — TERSULIT.

• Sebelumnya terblokir total (tidak ditemukan aset CC gratis; dokumentasi ada di Fish03/Documentation).
• 02 Pencarian (diperluas): sisir ulang semua sumber §3 dengan lebih banyak percobaan; cek Blue Marlin Makaira nigricans DAN Black/Striped marlin sebagai alternatif. Kalau tetap tidak ada yang layak → fallback Fase-5: buat dari nol (Hunyuan3D — catatan: pernah ada kesalahan billing sebelumnya; atau bikin manual base bill-fish sederhana). Baru setelah itu rig/animasi/ekspor.

Verifikasi (per ikan, sebelum ditandai selesai)

• Render sweep dari 4 state (sudut lebar + close-up sirip/sendi, frame amplitudo puncak) — tidak boleh ada yang sobek.
• Cek GLB: rotasi root [-0.7071,0,0,0.7071], sumbu mesh benar, satu animasi per state, skin ada, <10 MB (§5.5).
• usdchecker lolos di setiap USDZ.
• Import ulang tiap GLB ke scene bersih dan render (untuk menangkap regresi ekspor).
• Terakhir: user melakukan review di Reality Composer Pro.

Item terbuka / TODO / keterbatasan (dari BUILD_PLAN.md)

• Marlin (Fish03) secara eksplisit ditandai tersulit / tidak ada sumber gratis saat penulisan; fallback scratch-build ditandai dengan catatan "pernah ada kesalahan billing" untuk Hunyuan3D.
• "Git push saat ini tidak berlaku — belum ada repo lokal" — bertentangan langsung dengan alur kerja git di AGENTS.md §12; dicatat sebagai inkonsistensi, tidak diselesaikan di dokumen ini.
• Menurut CLAUDE.md (status terkini), kelima ikan dalam rencana ini (Yellowfin, Trevally, Skipjack, Grouper, Marlin) sekarang sudah selesai semua — dokumen ini adalah potret historis/sedang-berjalan, bukan status terkini.
• Catatan-catatan seputar tooling Sketchfab (tool download BlenderMCP yang rusak, error sandbox curl) adalah kendala khusus lingkungan kerja yang perlu diketahui pembangun di masa depan, bukan sesuatu yang sudah diperbaiki secara permanen.

1.4 Rencana Pembangunan Lingkungan — FishAssets/BUILD_PLAN_ENV.md (186 baris)

Ini adalah dokumen pendamping BUILD_PLAN.md, tapi untuk lingkungan + joran pancing, bukan ikan. Isinya mendokumentasikan brief kreatif yang sudah dikonfirmasi untuk scene dermaga/danau orang-pertama (setelah berbelok dari konsep kolam-AR semula), daftar lengkap aset yang harus dikirim beserta tabel progres yang hidup, strategi sourcing, pipeline khusus lingkungan (menggantikan pipeline 13-fase ikan), urutan pembangunan, dan item terbuka. Ditulis 2026-07-16 (CP36), difinalisasi sesuai brief yang dikonfirmasi user (CP36b).

§0 — Premis yang Dikonfirmasi

• BUKAN AR — kamera perangkat tidak pernah dipakai; RealityKit merender dunia 3D orang-pertama yang sepenuhnya virtual di iPad/macOS dengan pemain ditempatkan di dalamnya.
• Setting: kolam/danau ikan trofi buatan yang sudah ditebar — besar, dalam, buatan manusia/eksotis, tempat spesies unggulan sengaja diintroduksi. Framing ini membuat masuk akal spesies air tawar + laut lepas hidup di satu badan air (marlin 3,0 m dan catfish Mekong di danau yang sama). Skala waduk, bukan kolam alami kecil — cukup dalam untuk secara visual masuk akal menampung ikan besar.
• Pemain: orang-pertama, tinggi mata 1,6 m, berdiri di dermaga/dermaga kayu yang menjorok ke air; bisa menunduk dan melihat dermaga serta joran mereka sendiri — kehadiran fisik adalah tujuannya.
• Roster (7 ikan — sudah dibangun saat penulisan, jangan buat ikan baru): mekong giant catfish, giant trevally, grouper, bluefin tuna, yellowfin tuna, skipjack tuna, marlin/sailfish. (Clownfish + blue tang di luar roster ini.)
• Input (memengaruhi rigging, bukan geometri): Cast = gestur flick di iPhone-sebagai-kontroler; Fight = kemiringan HP, menggerakkan lengkungan joran + ketegangan senar secara real-time ⇒ joran dan senar harus berupa rig yang bisa digerakkan lewat bone, BUKAN klip yang di-bake.
• Alur game: Cruise (berpatroli/menampakkan diri) → Bite (sambaran cepat ~2×) → Caught (meronta→tenang→dipajang) → Preview (turntable statis untuk UI koleksi/album).
• Pencahayaan: skybox golden-hour yang di-bake + lampu directional statis. Tidak ada siang-malam dinamis.
• Air: butuh shader real-time (normal animasi, riak/refraksi) — secara eksplisit ini tugas shader/teknis terpisah, BUKAN modeling; bangun mesh-nya siap-shader, shader-nya menyusul.

Tabel digantikan-vs-aktual:

Keputusan user: SATU lingkungan yang imersif; snake_case di mana-mana; USDZ saja (lingkungan); Sketchfab dulu, Hunyuan3D hanya kalau tidak ada yang cocok.

§0b — Referensi Skala (diusulkan)

§1 — Daftar Aset yang Harus Dikirim

Setiap aset adalah file .usdz terpisah (sesuai penamaan AGENTS §8.0), diposisikan/diskala/dianimasikan secara independen lewat kode. Jangan pernah satu file scene gabungan.

§1a — ESENSIAL (dibangun lebih dulu, satu per satu, berurutan)

Progres saat penulisan: 6/6 esensial + 11/11 sekunder + 1 aset penghalus = 18/18 selesai (per 2026-07-17). Pembangunan penuh selesai ditambah satu babak penghalusan, dipicu oleh feedback user "lingkungan keseluruhan terlihat seperti kardus," yang diatasi dengan: (a) HDRI langit di-sourcing ulang di 8K → di-bake ke 4K (sebelumnya 2K); (b) aset baru terrain_horizon_ring.usdz (3.409 tris, dibuat manual + tekstur CC0, cincin bukit+pepohonan yang menjembatani scene inti dengan kubah langit); (c) render verifikasi sekarang memakai pencahayaan Sun+HDRI yang sudah dipasangkan sesuai §4.6, bukan lagi pratinjau netral flat. Dua bug ekspor material yang signifikan ditemukan/diperbaiki selama babak ini, dirinci di bagian "REFINEMENT PASS" milik Source_Log.md. Item terbuka yang tersisa dicatat di §4b.

Tabel lengkap aset esensial:

Catatan urutan: HDRI golden-hour dipilih di awal sebagai referensi pratinjau/validasi supaya setiap aset dinilai di bawah pencahayaan final — tapi aset sky_dome sendiri dikirim di urutan #6 sesuai prioritas user. Ini aman karena pencahayaannya baked/statis dan albedo PBR tidak tergantung pencahayaan.

§1b — SEKUNDER — semua 11 selesai (2026-07-17, disetujui user)

(Catatan: penomoran di tabel sumber mengulang "7" dan "9" pada beberapa baris — direproduksi persis seperti aslinya; jumlah baris totalnya cocok dengan 11 aset sekunder: 3 batu + rumput + reed + 3 pohon + ember + tacklebox + tali = 11.)

Target scene: ≲150 ribu tris, ≲60 draw call (batu/rumput/pohon di-instance).

§1c — Format laporan wajib per aset

Untuk setiap aset, laporkan: sourced vs dibuat manual · nama file · lokasi penyimpanan · penyimpangan dari spesifikasi (jumlah poli, resolusi tekstur, penyederhanaan) · hasil usdchecker.

§2 — Strategi Sumber

MCP yang benar-benar tersedia (diverifikasi 2026-07-16) — "TANS" dan "WinU1" pada brief tidak benar-benar ada:

Aturan lisensi tetap sama: CC0/Public Domain/CC-BY saja; kalau CC-BY ⇒ atribusi wajib dicatat.

§3 — Pipeline (varian lingkungan dari §7)

Pipeline 13-fase ikan berpusat pada spesies; rubriknya ("Akurasi Anatomi 35") dan Fase 01 "Validasi Ilmiah" tidak relevan untuk sebuah batu. Pipeline lingkungan:

Rubrik penilaian lingkungan (menggantikan §6 untuk lingkungan):

Ambang batas 50/100; lisensi harus CC0/CC-BY.

§4 — Urutan Pembangunan (dikonfirmasi user, CP36b)

Referensi pencahayaan E02 (HDRI) dipilih lebih dulu (hanya untuk pratinjau/validasi, bukan aset yang dikirim). Lalu 6 aset esensial dibangun satu per satu, masing-masing dilaporkan+diverifikasi sebelum lanjut ke berikutnya: 1. dock_main → 2. water_surface (mesh saja) → 3. terrain_underwater → 4. rod_main → 5. rod_line → 6. sky_dome. BERHENTI — aset sekunder (7–9) baru mulai dikerjakan setelah user menyetujui aset-aset esensial.

§4b — Tugas lanjutan (BUKAN modeling — dicatat, belum dikerjakan di sini)

§5 — Gaya Seni

(Tidak berubah dari pembukaan §4): semi-realistis, cocok dengan ikan-ikan yang sudah realistis; bukan kartun, bukan photoreal yang terlihat aneh (uncanny). Alami, menenangkan, palet golden-hour hangat-desaturasi. Pencahayaan konsisten sesuai §4.6.

§6 — Verifikasi (per aset, sebelum dianggap "selesai")

Rendernya benar dari kamera orang-pertama 1,6 m di bawah HDRI yang terkunci; jumlah tris sesuai §4.1b; tekstur sesuai tingkatan §4.2b; map PBR lengkap; metallic=0 pada permukaan alami; usdchecker → Sukses; skala masuk akal dibanding ikan yang sudah dikirim (0,6 m grouper … 3,0 m marlin, 1 unit Blender = 1 m); cek draw-call/tris pada scene yang sudah dirakit.

§7 — Item Terbuka

Migrasi penggantian nama ikan (user sudah memutuskan snake_case di mana-mana): ~80 file GLB/USDZ yang sudah dikirim + setiap referensi silang dokumen harus diganti namanya (contoh: Marlin_Cruise.glb → marlin_cruise.glb). Dicatat terpisah — karena ini mengubah-ubah deliverable yang sudah selesai dan tervalidasi, jadi ini tugasnya sendiri, tidak digabung ke pembangunan lingkungan.

Item terbuka / TODO / keterbatasan (dari BUILD_PLAN_ENV.md)

• Shader air secara eksplisit ditunda — belum dibangun di repo ini.
• Migrasi penggantian nama ikan (~80 file) secara eksplisit ditunda, dicatat tapi belum dimulai.
• Dua "bug ekspor material yang signifikan" dari babak penghalusan hanya dirangkum di sini; detail lengkapnya ada di bagian "REFINEMENT PASS" milik Source_Log.md (tidak ikut dibaca untuk tugas ini).
• Penomoran tabel progres aset sekunder (baris berlabel "7" dan "9" yang berulang) tampaknya adalah keanehan penulisan pada dokumen sumbernya sendiri, direproduksi apa adanya di atas.

1.5 Catatan Serah Terima Tim Aplikasi — FishAssets/APP_TEAM_HANDOFF.md (195 baris)

Ini adalah catatan serah terima satu kali pakai, ditulis oleh sesi Claude Code yang mengerjakan fitur preview ikan AR di repo aplikasi terpisah (CtSPoC), ditujukan untuk sesi mana pun di masa depan yang punya akses live ke Blender MCP (hanya bisa diakses dari repo aset ini, bukan dari repo aplikasi). Isinya mendokumentasikan perbaikan akar-masalah yang perlu dilakukan di Blender untuk bug orientasi/normal/tekstur yang memengaruhi ekspor Preview/ beberapa spesies ikan, karena menambal file .usdz yang sudah diekspor (dari sisi repo aplikasi) sudah mentok jalan buntu. File ini secara eksplisit bilang harus dihapus setelah pekerjaan yang dideskripsikan benar-benar selesai — ini catatan tugas sementara, bukan bagian dari dokumentasi permanen repo (per update terakhirnya file ini masih ada karena pekerjaannya belum tuntas).

Kenapa file ini ada

Tim aplikasi sempat mencoba memperbaiki bug orientasi/rendering dengan menambal file .usdz yang sudah diekspor (menambahkan koreksi xformOp:rotateXYZ, membangun ulang material yang hilang dari tekstur file .glb pasangannya). Cara ini gagal secara struktural: rumus koreksi rotasi angka yang sama berhasil untuk sebagian spesies tapi tidak untuk yang lain, membuktikan objek-objek Blender itu sendiri memang tidak konsisten diorientasikan/diekspor satu sama lain — harus diperbaiki di sumber Blender-nya, bukan ditambal per-file ekspor.

• Spesies referensi/template: Mekong Giant Catfish (Fish06_MekongGiantCatfish) — user sudah mengonfirmasi langsung di perangkat bahwa ini ikan dengan hasil ekspor/orientasi terbaik saat ini di aplikasi. Pakai transform objek Blender-nya, setup material, dan proses ekspornya sebagai template untuk yang lain.
• Jangan sentuh Sailfish (Fish10_Sailfish) — sudah dikonfirmasi benar di perangkat, melalui jalur import berbeda (Sketchfab/FBX) dibanding ikan-ikan Blender-native lainnya, jadi konvensinya memang sudah berbeda dari yang lain — biarkan saja.
• Cakupan: hanya ekspor state Preview/ (.glb + .usdz per spesies) — satu-satunya state yang dipakai aplikasi saat ini (layar AR "muncul dan periksa"). Ekspor Cruise/Bite/Caught di luar cakupan tugas ini.

Linimasa status per spesies (dari pengujian AR di perangkat)

• Update 2026-07-20 (CP43): 2 dari 5 spesies bermasalah sudah diperbaiki. Akar masalah isu normal ditemukan dan dikonfirmasi: data custom split-normal basi dari pipeline scan yang menimpa arah hadap wajah (mesh.has_custom_normals == True); perbaikannya = customdata_custom_splitnormals_clear() lalu normals_make_consistent(inside=False), urutannya harus begitu. Resep itu tidak aman untuk langsung dipakai ke 3 sisanya — malah memperburuk ketiganya secara terukur (lihat CP43 untuk angkanya) karena mesh mereka membawa kontaminasi non-manifold yang lebih berat daripada yang bisa aman diselesaikan cuma dengan recalculate lewat skrip; mereka butuh babak bangun-ulang sungguhan (weld-sebelum-decimate, verifikasi viewport langsung), sama seperti perbaikan pecah Giant Trevally di CP30 aslinya.
• Update 2026-07-20 (CP46): Mesh Preview Giant Trevally mendapat babak pembersihan sungguhan — 39 segitiga sampah terisolasi + 30 wajah interior yang terbukti tersembunyi dihapus lewat select_interior_faces(), jumlah edge non-2-manifold turun dari 165→101. Temuan penting: pola "lubang seperti dimakan ngengat" yang dramatis dan awalnya terlihat seperti gejala yang dilaporkan pada render backface-culled ternyata cuma artefak pencahayaan, bukan cacat sungguhan — dikonfirmasi dengan render material-flat + latar terang yang menunjukkan siluet solid penuh. Follow-up di hari yang sama: screenshot viewport Blender milik user sendiri menunjukkan mesh masih terlihat jelas berduri/sobek di area kepala/insang/dorsal — cacat yang lebih besar dan lebih jelas daripada apa pun yang terungkap dari analisis babak ini, lebih mendekati kelas bug "pecah/hancur" asli di CP30 daripada isu duplikasi-geometri halus yang diperbaiki babak ini. Giant Trevally dikonfirmasi masih rusak — dilewati dulu atas instruksi user, butuh bangun-ulang penuh weld-sebelum-decimate dari scan sumber mentah (seperti CP30), bukan tambalan topologi lokal lagi.
• Update 2026-07-21 (CP47): Mesh Preview Skipjack Tuna sudah dibersihkan dan dikonfirmasi solid secara visual, memakai metode debris/wajah-interior yang sama seperti Trevally tapi dijalankan sampai benar-benar konvergen: 1 segitiga sampah terisolasi + 3.180 wajah interior (11,4% dari mesh) dihapus lewat select_interior_faces(), edge non-manifold turun dari 2.923→798. Berbeda dari Trevally, sudah dicek dulu untuk pecahan skala-besar (tidak ada vertex berduri, hanya 1 pulau mesh sungguhan) dan hasilnya diverifikasi dengan render material-flat + latar terang dari 5 sudut — solid penuh di setiap sudut, tanpa lubang, tanpa siluet berduri. Lebih yakin ini benar-benar sudah diperbaiki dibanding Trevally, tapi belum dikonfirmasi di perangkat.
• Update 2026-07-21 (CP48): Mesh Preview Grouper dibersihkan dengan cara yang sama, hasilnya sama bersihnya. Sudah dicek dulu untuk pecahan (tidak ada — kelas kegagalan yang sama-sama bisa ditangani seperti Skipjack), lalu 364 wajah sampah (pulau-pulau kecil terputus) + 1.023 wajah interior dihapus lewat select_interior_faces(), edge non-manifold turun dari 2.511→479. Diverifikasi solid di 5 sudut dengan tes material-flat + latar terang yang sama. Ini menuntaskan ketiga spesies yang masih rusak dari CP43: Skipjack dan Grouper sudah dibersihkan dan dikonfirmasi solid secara visual (belum dites di perangkat); Giant Trevally tetap benar-benar rusak dan butuh bangun-ulang penuh.

Tabel status per spesies

Clownfish/Blue Tang (Fish01/Fish02) sudah diketahui memang di luar cakupan aplikasi (tidak punya animasi Preview yang asli, tidak ada ekspor .usdz sama sekali) — di luar cakupan.

Catatan "belum dihapus dulu": per CP48, Skipjack dan Grouper sudah dibersihkan+dikonfirmasi solid di Blender tapi belum dikonfirmasi di perangkat; Giant Trevally dikonfirmasi masih benar-benar rusak. Hapus file ini hanya setelah tim aplikasi mengonfirmasi Skipjack/Grouper sudah terlihat benar di perangkat DAN Giant Trevally sudah menjalani bangun-ulang penuhnya — mana pun yang belakangan.

Detail diagnosis per gejala

1. Orientasi (semua spesies yang bermasalah). Investigasi dari sisi aplikasi (mengekstrak bindTransforms skeleton tiap .usdz, membandingkan joint bernama — Dorsal_Fin vs Anal_Fin vs Pectoral_Fin_L/_R — terhadap sumbu lokal mesh-nya sendiri) mengonfirmasi semantik sumbu lokal konsisten secara internal per spesies (contoh: Skipjack Tuna: X = kiri-kanan, dikonfirmasi karena Pectoral_Fin_L/R hanya berbeda di X; Y = panjang hidung-ke-ekor; Z = punggung-perut, Dorsal_Fin positif, Anal_Fin negatif). Yang tidak konsisten adalah bagaimana objek tiap spesies diorientasikan/di-parent di scene Blender relatif terhadap Mekong. Satu rumus rotasi post-hoc yang diterapkan seragam ke transform SkelRoot hasil ekspor setiap spesies bermasalah (xformOp:rotateXYZ) sudah dicoba berkali-kali dan tidak pernah berhasil untuk lebih dari satu-dua spesies sekaligus — ini mengonfirmasi bahwa perbaikannya harus per-objek di Blender, bukan tambalan pasca-ekspor yang seragam.
   Perbaikan: untuk setiap spesies bermasalah, bandingkan rotasi objek armature/mesh-nya saat ini di scene Blender terhadap milik Mekong, lalu orientasikan ulang (sesuaikan rotasi objek, atau terapkan rotasi supaya ter-bake ke data mesh/armature — mana pun yang cocok dengan setup Mekong sendiri) supaya semua spesies berbagi konvensi orientasi akhir yang sama seperti Mekong sebelum diekspor.
2. Bluefin Tuna: tekstur kosong. Dikonfirmasi bukan masalah material yang hilang — graph material file .usdz yang diekspor secara struktural lengkap (Principled_BSDF + Material_baseColor.png/Material_normal.png/Material_metallicRoughness.png yang asli, semuanya tidak kosong saat dibuka langsung). Tekstur base color memakai layout atlas UV bergaya "pulau pecah" (region kecil yang dicat dikelilingi latar belakang abu-abu besar yang tidak dicat — khas pipeline fotogrametri yang dipakai di seluruh ikan-ikan ini). Kemungkinan penyebab terbesar: koordinat UV mesh tidak persis mendarat di pulau-pulau yang dicat untuk sebagian besar permukaan, jadi wajah-wajah itu mengambil sampel dari latar abu-abu kosong.
   Perbaikan: periksa layout UV Bluefin Tuna terhadap tekstur baked-nya; bandingkan dengan setup UV Mekong (yang tidak punya masalah ini) untuk menemukan perbedaan strukturalnya. Kemungkinan butuh koreksi UV unwrap dan/atau bake ulang tekstur dengan penempatan pulau yang benar, mengikuti proses yang sama yang menghasilkan hasil bersih Mekong.
3. Skipjack Tuna / Grouper: "hanya bagian dalam model yang terekspor." Pengecekan forensik sebelumnya pada Skipjack Tuna (cross-product antara arah normal geometris hasil winding-order tiap segitiga vs normal per-vertex yang tercatat, pada file .usda sumber sebelum diperbaiki) menemukan 96,6% sudut wajah cocok arahnya dan hanya 0,9% yang tidak cocok — bukan mesh yang terbalik secara global, tapi memang ada subset wajah yang lebih kecil dengan normal yang tidak konsisten/terbalik, kemungkinan terkonsentrasi di satu permukaan yang menonjol secara visual — makanya terlihat seperti "melihat bagian dalam model" padahal sebagian besar mesh sebenarnya baik-baik saja.
   Perbaikan: di Blender, pilih mesh, masuk Edit Mode, pilih semua, recalculate normal ke arah luar (bpy.ops.mesh.normals_make_consistent(inside=False), yaitu Shift+N) untuk Skipjack Tuna maupun Grouper. Ada baiknya juga dicek Yellowfin Tuna dan Giant Trevally untuk isu yang sama karena mereka berbagi jalur ekspor atlas multi-material yang sama.
4. Jalur ekspor "atlas" itu sendiri mungkin adalah akar masalah bersama. Skipjack Tuna, Grouper, Yellowfin Tuna, dan Giant Trevally semuanya memakai pola atlas UV multi-material (beberapa GeomSubset, satu region tekstur per subset — nama material seperti Q11870_1all_2_tex0/1/2). Jalur ekspor ini sama dengan yang menyebabkan "insiden CP38" yang sudah didokumentasikan sebelumnya (di CLAUDE.md repo ini sendiri) yang diam-diam menghapus seluruh shader saat ekspor .usdz untuk spesies-spesies persis ini (sudah diakali dari sisi aplikasi dengan membangun ulang graph shader dari tekstur embedded milik file .glb pasangannya — sudah diterapkan dan berjalan, jadi material/tekstur saat ini tidak hilang di aplikasi, hanya orientasi dan normal yang masih rusak). Mengingat jalur ini sudah menyebabkan dua cacat ekspor yang berbeda (shader yang hilang, sekarang dicurigai normal terbalik/kemungkinan isu UV), ada baiknya membandingkannya secara struktural dengan jalur ekspor material-tunggal Mekong yang lebih sederhana untuk menemukan satu perbaikan di level lebih atas (setting ekspor atau isu modifier/data) yang bisa mencegah kejadian ini terulang di keempat spesies berpola atlas, daripada memperbaikinya satu-satu.

Pengaturan Ekspor

(Dari AGENTS.md, sudah jadi konvensi yang terdokumentasi):

• glTF/GLB: export_apply=True, export_animations=True, export_skins=True, export_animation_mode='ACTIVE_ACTIONS'
• USDZ: relative_paths=True, export_animation=True, convert_world_material=False

Ekspor ulang state Preview tiap spesies yang sudah diperbaiki sebagai .glb dan .usdz, menimpa file yang sudah ada di FishAssets/FishNN_Species/Preview/.

Aturan Kerja (sesuai CLAUDE.md/AGENTS.md repo ini)

1. Baca CLAUDE.md dan FishAssets/AGENTS.md secara lengkap sebelum mulai.
2. Tambahkan entri berstempel tanggal ke CHECKPOINT.md untuk pekerjaan ini — jangan pernah menghapus entri sebelumnya. Dokumentasikan persis apa yang berubah per spesies (penyesuaian orientasi, perbaikan UV/normal, ekspor ulang) dan alasannya.
3. Jangan sentuh Sailfish atau apa pun di luar FishAssets/.
4. Tugas ini terbatas hanya pada repo aset Blender — repo aplikasi CtSPoC (tempat fitur preview AR dan riwayat penambalan rotasi berada) di luar cakupan; seorang manusia akan men-deploy ulang hasil ekspor yang sudah diperbaiki ke sana secara terpisah dengan menjalankan ulang langkah penyalinan aset dari sisi aplikasi (lihat entri "AR Fish Preview" di CtSPoC/CHECKPOINT.md untuk proses itu — mendokumentasikan konvensi penyalinan byte-per-byte + verifikasi sha256 yang dipakai saat menarik Preview/*.usdz ke dalam aplikasi).

Setelah pekerjaan ini selesai

Setelah diekspor ulang, perbaikan di sisi aplikasi jadi sederhana: hapus seluruhnya tambalan xformOp:rotateXYZ post-hoc milik aplikasi (yang tadinya jadi akal-akalan untuk inkonsistensi sisi Blender yang diperbaiki tugas ini di akarnya) dan salin ulang file Preview/*.usdz yang sudah diperbaiki langsung dari repo ini ke CtSPoC/Rod/Rod/Assets/FishPreview/, diganti namanya supaya cocok dengan id masing-masing spesies (lihat tabel di entri "AR Fish Preview" milik CtSPoC/CHECKPOINT.md untuk pemetaan pasti <Species>_Preview.usdz → <id>.usdz). Tidak perlu ada lagi perhitungan rotasi di sisi aplikasi kalau semua spesies sekarang sudah cocok dengan konvensi orientasi Mekong.

Instruksi terakhir: hapus file ini setelah pekerjaannya selesai — ini catatan tugas satu-kali-pakai, bukan bagian dari kumpulan dokumentasi permanen repo.

Item terbuka / TODO / keterbatasan (dokumen ini pada dasarnya SEMUA berisi item terbuka)

• Giant Trevally (Fish05): dikonfirmasi masih benar-benar rusak per CP46 — geometri berduri/sobek dekat kepala/insang/dorsal, butuh bangun-ulang penuh weld-sebelum-decimate dari scan sumber mentah (seperti perbaikan CP30 aslinya), bukan tambalan topologi lokal lagi. Secara eksplisit dilewati dulu atas instruksi user.
• Skipjack Tuna (Fish08) dan Grouper (Fish09): sudah dibersihkan dan dikonfirmasi solid secara visual di Blender per CP47/CP48, tapi belum dikonfirmasi di perangkat di aplikasi — perlu dites ulang.
• Bluefin Tuna (Fish04): normal sudah diperbaiki, tapi keluhan awal "tekstur kosong" tidak bisa direproduksi di level file — kemungkinan sudah teratasi, tapi belum dikonfirmasi di perangkat; isu layout UV "pulau pecah" yang mendasarinya (region yang dicat dikelilingi latar abu-abu yang tidak dicat) belum benar-benar diperbaiki, baru diduga sebagai penyebabnya.
• Blue Marlin (Fish03): belum dites di babak ini, diduga OK (berbagi jalur ekspor material-tunggal yang lebih sederhana dengan Mekong/Sailfish) — belum diverifikasi.
• Pertanyaan struktural yang lebih luas masih terbuka: apakah jalur ekspor "atlas" multi-material bersama (dipakai Skipjack, Grouper, Yellowfin, Trevally) punya satu perbaikan di level lebih atas (setting ekspor atau isu modifier/data) versus butuh tambalan per-spesies — belum diselidiki.
• File ini sendiri adalah artefak yang akan dihapus: penghapusannya digantungkan pada (a) tim aplikasi mengonfirmasi Skipjack/Grouper sudah terlihat benar di perangkat, DAN (b) Giant Trevally sudah menjalani bangun-ulang penuhnya — mana pun yang belakangan. Per update terakhir file ini, belum ada satu pun kondisi yang terpenuhi, jadi file ini seharusnya masih ada di repo.
• Ketergantungan lintas-repo: perbaikan yang dibuat di sini harus disalin ulang secara manual (dengan verifikasi sha256) ke repo aplikasi CtSPoC yang terpisah oleh seorang manusia — otomatisasi repo ini sendiri tidak menjangkau repo itu.