holodepth

Asset pipeline · Üretim → runtime köprüsü

Model Yolculuğu Sözleşmesi: DCC'den Tarayıcıya El Sıkışması

Bir glTF dosyası «indirildi» anında doğmaz; üretim hattından runtime'a yazılı bir sözleşmeyle gelir. Bu sayfa Blender/Maya export ayarlarını veya glTF accessor şemasını tekrar etmez; DCC çıktısı ile Three sahnesi arasındaki yolculuk, isimlendirme ve rol disiplinini anlatır.

Export paneli Blender · glTF exporter yaprağındadır. Mesh temizliği Modelleme · mesh cleanup izleğindedir. Draco, LOD ve sıkıştırma kararı Platform · asset sıkıştırma & LOD yaprağındadır. Bu sayfa «hangi dosya hangi sahnede, hangi isimle, hangi optimizasyon kapısından geçti ve kim onayladı?» sorusuna cevap verir — yani üretim ile runtime arasındaki anlaşmayı yazılı hale getirir.

Ekip büyüdükçe bu anlaşma sözlü kalamaz: bir 3D sanatçı dosyayı export eder, bir geliştirici onu sahneye bağlar, bir üçüncü kişi CDN'e yükler. Aralarında ortak bir checklist ve isimlendirme kuralı yoksa her adımda «bu dosya doğru mu?» sorusu yeniden sorulur ve zaman kaybolur. Model yolculuğu sözleşmesi tam olarak bu boşluğu kapatır: format bilgisini değil, süreç bilgisini taşır.

Sayfayı bitirdiğinizde şu cümleyi kurabilmelisiniz: «Model yolculuğu tek dosya değil zincirdir; isimlendirme manifeste bağlanır; optimize adımı format şemasından ayrıdır; runtime yalnızca sözleşmeye uyan paketi kabul eder; el sıkışma checklist'i olmadan CDN'e atmak borçtur.»

Bu sayfanın sınırı · komşu konularla ayrım

Bu sayfa şunları anlatır:

  • DCC → optimize → runtime zinciri ve sorumluluk paylaşımı
  • İsimlendirme, klasör ve manifest önizlemesi
  • El sıkışma checklist'i (handoff) ve tekrar üretilebilirlik

Bilinçli olarak dışarıda bırakılan konular:

Kısa ayrım: Bu sayfa «yolculuk sözleşmesi» · Modelleme «DCC export» · glTF «dosya şeması» · Platform «sıkıştırma kararı».

Zincir: üretim → optimize → paket → runtime

Holodepth dört durak görür: üretim (DCC'de modelleme, UV, rigging), optimize (web bütçesine göre poligon/texture kararı), paket (glTF/GLB + yan dosyalar, tek bir teslim edilebilir birim) ve runtime (loader + sahne kökü). Her durak, öncekinin çıktısını girdi olarak alır; aradaki sözleşme yazılı değilse bir adım atlanabilir veya yanlış sırayla çalışabilir.

Bir adım atlanırsa sonraki durak patlar — örneğin optimize edilmemiş 40 MB'lık bir texture, CDN üzerinde hızlı görünse bile ilk kareyi öldürür; ya da paket adımında yanlış node adıyla export edilen bir mesh, runtime kodunun getObjectByName çağrısını sessizce başarısız kılar. Zincirin her halkası kendi başına doğru olabilir, ama sıradaki halkaya doğru bilgiyi taşımıyorsa bütün hattın değeri düşer.

Bu yaprak her durağın çıktı sözleşmesini tanımlar; içerik üretiminin kendisini (modelleme, export ayarları, sıkıştırma algoritması) başka izleklere linkler. Amaç, dört durağı ayrı ayrı öğretmek değil, aralarındaki geçiş noktalarını görünür kılmaktır.

İsimlendirme: URL, dosya ve sahne düğümü

Tutarlı isimler arama, cache ve debug maliyetini düşürür. Holodepth önerisi: category/asset-name_variant.glb — küçük harf, tire/alt çizgi disiplini, versiyon ayrı dosya adı veya hash ile taşınır (versiyon detayı sonraki yaprakta). Sahne içi node isimleri export'tan gelir; runtime'da getObjectByName ile eşleşecek şekilde DCC'de sabitlenir ve bu isim bir kez belirlendikten sonra ekip içinde «kırılmaz sözleşme» sayılır.

Üç katman farklı sorumluluk taşır ve birbirine karıştırılmamalıdır: URL yolu manifest anahtarıyla birebir örtüşür, dosya adı varyantı (LOD seviyesi, dil, sezon) taşır, node adı ise runtime kodunun müdahale edeceği stabil bir kancadır. Bu üçü aynı string olabilir ama aynı amaç için var değildir.

Üç isimlendirme katmanı ve sorumluluğu
Katman Sorumluluk Örnek
URL path CDN klasörü = manifest anahtarı /characters/hero-scan.glb
Dosya adı Varyant (LOD, dil, sezon) ayrımı hero-scan_lod0.glb
Sahne node'u Runtime müdahale kancası HeroScan_Root

Klasör sözleşmesi ve manifest önizlemesi

İsimlendirme kadar önemli olan diğer disiplin, klasör yapısının anlam taşımasıdır. Holodepth önerisi kategori bazlı bir kök: characters/, environment/, props/, ui/ gibi klasörler manifest'teki anahtarlarla bire bir eşlenir. Klasör derinliği ikiyi geçmemeli — «bulmak» değil «tahmin etmek» gerektiren bir hiyerarşi, ekip büyüdükçe kendi belgesine ihtiyaç duyar.

Manifest, bu klasör sözleşmesinin makine tarafından okunabilir hâlidir; hangi kategori altında hangi dosyanın olduğunu, hangi aşamalardan geçtiğini ve runtime'ın hangi loader ile açacağını tek bir JSON'da toplar. Bu sayfanın sonundaki simüle kod, tam olarak bu manifest'in minimal bir taslağını gösterir; manifest'in yükleme önceliği ve CDN header ilişkisi dağıtım izleğinde derinleşir.

Klasör ve manifest arasında tutarsızlık — örneğin dosya taşınmış ama manifest güncellenmemiş — «asset bulunamadı» hatalarının en sık nedenidir. Bu yüzden manifest güncellemesi, dosya taşımanın parçası sayılmalı, ayrı bir görev değil.

El sıkışma checklist'i

Runtime'a geçmeden önce minimum kontrol listesi vardır ve bu liste yazılı olmadan «çalışıyor gibi görünen» dosya prod ortamında kırılır:

  1. Birim ve eksen doğru mu? (Modelleme · units)
  2. Modifier apply / transform freeze yapıldı mı?
  3. Texture yolu göreli ve paket içinde mi?
  4. Poligon/texture bütçesi Platform LOD ile uyumlu mu?
  5. Node isimleri sözleşmeye uyuyor mu?
  6. Test GLB tek GLTFLoader ile açılıyor mu?

Checklist bir onay imzası değil, otomatikleştirilebilir bir kapı olarak düşünülmelidir: CI adımında GLB dosyası açılıp node isimleri ve boyut sınırı otomatik doğrulanabilir. Elle kontrol, ekip iki kişiyi geçtiği anda tutarsız uygulanmaya başlar.

Optimize kapısı: format değil karar

Optimize «hangi mesh hangi LOD, hangi texture hangi çözünürlük» kararıdır; glTF JSON yapısını yeniden yazmak değil. Karar Platform LOD yaprağında verilir; bu sayfa yalnızca kapının runtime öncesi zorunlu olduğunu ve atlanamayacağını hatırlatır.

Pratikte optimize kapısı iki soruya cevap üretir: «Bu asset hangi görüş uzaklığında hangi detayda görünecek?» ve «Toplam sahne bütçesi içinde bu asset'e ne kadar pay ayrıldı?». Bu iki soru cevaplanmadan paket adımına geçmek, runtime'da sonradan fark edilecek bir performans borcu biriktirir.

Sorumluluk paylaşımı: kim neyi onaylar?

Küçük ekiplerde tek kişi dört durağın hepsini yapabilir; ancak roller büyüdükçe ayrışır ve her rolün onayladığı bir «çıkış kapısı» olur. Rolleri değil kapıları netleştirmek, kişi değişse bile sözleşmeyi ayakta tutar.

Durak · onaylayan rol · referans yaprak
Durak Onaylayan Referans
Üretim (DCC) 3D sanatçı Modelleme · export ayarları
Optimize Teknik sanatçı / lead Platform · LOD
Paket & handoff Pipeline sahibi Bu sayfa · checklist
Runtime kabul Geliştirici glTF yükleme yüzeyi

Tekrar üretilebilirlik: aynı sahne, aynı sonuç

«Aynı DCC dosyasından tekrar export ettim, byte'lar değişti» sık görülen bir sorundur — rastgele isimlendirilen ID'ler, zaman damgası içeren metadata veya farklı exporter sürümü buna neden olabilir. Tekrar üretilebilirlik, versiyon mührü izleğinin ön koşuludur: hash'in anlamlı olması için aynı girdiden aynı çıktının üretilmesi gerekir.

Holodepth önerisi: export ayarlarını (sıkıştırma seviyesi, birim, apply edilen modifier listesi) DCC dosyasıyla birlikte versiyonlamak, ve mümkünse export komutunu bir betiğe bağlamak — elle tıklanan bir menü, iki farklı günde iki farklı sonuç üretebilir.

Yanlış yolculuk kalıpları

  • Her build'de rastgele dosya adı (cache kırılır)
  • Export ayarını runtime'da «düzeltmeye» çalışmak
  • 40 MB GLB'yi «sonra optimize ederiz» diye CDN'e atmak
  • Node isimlerini koddan rename ile düzeltmek
  • Checklist'i yalnızca hafızada tutmak, hiçbir yerde yazılı olmaması
  • glTF şema dersini bu sayfada beklemek

Yolculuk sözleşmesi olmayan bir pipeline'da her yeni asset, ekibin daha önce çözdüğü sorunu yeniden çözer.

Simüle: yolculuk manifest & kabul kontrolü

Simüle · handoff manifest (JSON).

{
  "assetId": "hero-scan-lod0",
  "source": "blender-4.2",
  "checksum": "sha1:9f2a1c",
  "stages": {
    "dcc": { "done": true, "ref": "blender/gltf-glb-exporter-settings" },
    "optimize": { "done": true, "ref": "platform/asset-compression-and-lod" },
    "package": { "file": "characters/hero-scan_lod0.glb", "bytes": 1840000 }
  },
  "handoff": {
    "checklistPassed": true,
    "approvedBy": "pipeline-owner"
  },
  "runtime": {
    "loader": "GLTFLoader",
    "rootNode": "HeroScan_Root"
  }
}

Simüle · runtime kabul kontrolü.

export function assertHandoff(manifest) {
  if (!manifest?.stages?.optimize?.done) {
    throw new Error('Optimize kapisi atlanmis - runtime kabul etmiyor')
  }
  if (!manifest.stages.package?.file) {
    throw new Error('Paket yolu tanimsiz')
  }
  if (!manifest.handoff?.checklistPassed) {
    throw new Error('El sikisma checklist onayi yok')
  }
  return manifest.stages.package.file
}

Üç yolculuk rigor profili

  • 01 · Rigor

    Hızlı prototip

    Checklist
    Kısa, elle
    Manifest
    Tek dosya
    Risk
    Prod'a sızma
  • 02 · Rigor

    Prodüksiyon sahnesi

    Checklist
    CI'da otomatik
    Manifest
    Kategori bazlı
    Risk
    Rol karışıklığı
  • 03 · Rigor

    Büyük dünya / çok sahne

    Checklist
    Zorunlu + imzalı
    Manifest
    Parçalı, route bazlı
    Risk
    Versiyon senkronu

Holodepth perspektifleri

Köprü, export klonu değil

Modelleme izleği «nasıl export edilir» der; bu izlek «export sonrası ne garanti edilir» der. İkisini aynı sayfada tekrar etmek, hem içeriği şişirir hem de sınırları belirsizleştirir.

Checklist = sözleşme

El sıkışma yazılı değilse ekip büyüdükçe herkes farklı dosya üretir; checklist'i otomatikleştirmek, kişiye bağımlılığı azaltır.

Rol ayrışması erken planlanır

Tek kişilik projede dört durak bir kişide birleşebilir; ama sözleşmeyi baştan «kapı» olarak yazmak, ekip büyüdüğünde sorunsuz bölünmeyi sağlar.

  1. İsimlendirme kuralı yazılı ve tek kaynak mı?
  2. Klasör yapısı manifest anahtarlarıyla eşleşiyor mu?
  3. Checklist otomatikleştirilebilir mi, yoksa tamamen elle mi?
  4. Optimize kapısı paket adımından önce mi çalışıyor?
  5. Hangi rol hangi durağı onaylıyor, yazılı mı?
  6. Aynı DCC dosyasından iki export aynı sonucu veriyor mu?
  7. Runtime, sözleşmeye uymayan paketi reddediyor mu?

Holodepth içgörüsü

Asset pipeline yolculuk yaprağı, format ve DCC izleklerinin üstündeki ince köprüdür. Sıradaki kapı: glTF yükleme yüzeyi.

Sonraki kapı

Sözleşme hazırsa sıradaki yaprak glTF yükleme yüzeyidir: GLTFLoader, decoder yüzeyi ve sahne kökü — glTF şema dersi değil.