Framework entegrasyonları · React Three Fiber

Deklaratif Sahne Grafı: JSX'ten Object3D Kataloğuna

R3F'de <mesh> bir HTML etiketi değildir; Three kataloğuna açılan bir kapıdır. Bu sayfa JSX çocuklarını Object3D ağacına bağlayan haritayı anlatır: hangi prop constructor'a gider, hangisi runtime alanına yazılır, kim parent olur, kim yeniden doğar.

Holodepth bu yaprağı React bileşen dersi veya «ilk küp» turu olarak yazmaz. React dili varsayılır (React Vitae). Canvas kök mührü Canvas & kök sözleşme yaprağındadır. Buffer / materyal / Object3D matematik teorisi Three.js ve WebGL omurgasındadır. glTF dosya şeması, DCC export ve format karşılaştırmaları bu haritanın konusu değildir.

Sayfayı bitirdiğinizde şu cümleyi kurabilmelisiniz: «JSX intrinsikleri Three katalog adlarıdır. args çoğunlukla kurucu, diğer prop'lar alan/metod yüzüdür. attach geometri ve materyali yuvaya kilitler. key remount'u yönetir. Parent hiyerarşisi yerel uzayı taşır. primitive kaçış kapısıdır. Sonraki kapı useFrame / useThree diplomasisidir.»

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

Bu sayfa R3F'de deklaratif sahne grafı haritasını anlatır:

İntrinsic katalog · args / prop / attach
Hiyerarşi · key / remount · conditional çocuk
Materyal-geometri yuvalama · primitive
Uzlaştırma tuzakları · üç yazım profili

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

Canvas / DPR / frameloop / gl → Canvas & kök sözleşme
Kare döngüsü, store seçicileri → useFrame / useThree
Loader, Suspense, dispose borusu → Yükleme & Suspense köprüsü
Pointer / picking → Pointer olayları & picking
Imperatif kaçış derinliği → Performans & imperatif kaçış
React temeli → React Vitae · glTF/GLB şema → format izlekleri

Kısa ayrım: Bu sayfa «ağaç nasıl yazılır?» · Canvas «kapı nasıl mühürlenir?» · useFrame «ağaç açıkken kim günceller?» · Three Object3D «matematik / transform teorisi».

Katalog: JSX DOM değildir

Tarayıcı DOM'unda <div> bir düğümdür. R3F reconciler'ında <mesh>, <group>, <perspectiveCamera> gibi isimler Three.js katalog girdilerine çözülür. Holodepth dili: JSX burada HTML yazmaz; sahne katalogundan sipariş verir.

Bu ayrım pratikte kritiktir. CSS sınıfları, semantik HTML veya ARIA kuralları Canvas host'unda (DOM tarafında) yaşar; üç boyutlu düğümlerde className beklememek, props'u Three alan adlarıyla hizalamak gerekir. React Vitae'nin JSX sözdizimi bilgisini varsayarız; burada soru «JSX nedir?» değil, «hangi katalog girdisine düşer?»dir.

Aynı parantez, farklı dünyalar: DOM ağacı ve Object3D ağacı.

args, prop, attach: üç kapı

Holodepth üç kapıyı ayırır. Karıştırmak «nedense yeniden oluştu» veya «materyal bağlanmadı» semptomlarını üretir.

Üç kapı · yazım sözleşmesi
Kapı	Ne işe yarar?	Tipik tuzak
`args`	Kurucu parametreleri (çoğu geometri / ışık)	Her render'da yeni dizi → gereksiz remount
Alan prop'ları	`position`, `intensity`, `visible`…	Kurucu argümanı sanıp args'a gömmek
`attach`	Çocuğu ebeveynin yuvasına bağlar (`geometry`, `material`)	attach unutmak · yüzer nesne

args={[1, 1, 1]} gibi dizileri bileşen gövdesinde her karede yeniden yaratmak, referans eşitliğini bozar ve R3F'nin «kurucu değişti» yoluna düşmesine yol açabilir. Holodepth: sabit args'ı modül kapsamında veya useMemo disipliniyle kilitleyin; React memo dersini Vitae'ye bırakıp burada yalnızca sahne kimliği riskini mühürleriz.

Hiyerarşi: yerel uzay diplomasi

<group> altına yazılan çocuklar, ebeveynin transform uzayında yaşar. Bu, Three Object3D parent zincirinin R3F yüzüdür; matris çarpımı teorisini burada tekrar etmeyiz. Pratik sözleşme: ürün parçalarını grupla isimlendirin, pivot'u bilerek seçin, dünya konumunu her mesh'te ayrı ayrı yazmayın.

DCC Outliner / glTF node ağacı ile kavramsal akrabadır; fakat bu sayfa dosya paketini açmaz. Holodepth: runtime JSX hiyerarşisi ile export ağacını eşlemek istiyorsanız format ve modelleme izleklerine köprüleyin; burada yalnızca React ağacı ↔ Object3D ağacı eşlemesini mühürleriz.

İç içe çok derin gruplar okunabilirliği düşürür; düz liste ise pivot kontrolünü kaybettirir. Ürün dilinde «montaj grubu» + «yüzey parçaları» ayrımı çoğu vitrinde yeterlidir.

Geometri ve materyal yuvaları

Bir mesh'in iki klasik yuvası vardır: geometri ve materyal. R3F'de bunları çocuk olarak yazıp attach (veya katalog varsayılan attach davranışını) kullanmak yaygındır. Alternatif: dışarıda üretilmiş örneği prop olarak vermek. Holodepth tercihi üretimde genellikle açık yuvalamadır: okuyan kişi «bu mesh'in cildi ve formu nerede?» sorusunu JSX'te görür.

Paylaşılan materyal / geometri örnekleri (aynı material'i birden fazla mesh'in kullanması) performans ve tutarlılık getirir; ancak dispose diplomasisini yükleme yaprağına bırakırız. Bu sayfada yalnızca şunu mühürleriz: yuva sahipliği ile örnek paylaşımı ayrı kararlardır.

ShaderMaterial üniformları, texture slot'ları ve PBR kanalları Three / WebGL / materyal omurgasındadır. Burada soru «roughness nedir?» değil, «roughness prop olarak mesh/materyal yuvasına nasıl düşer?»dir.

key ve remount: kimlik politikası

React'te key listelerin kimliğini taşır; R3F'de aynı mekanizma Three nesnesinin yeniden doğup doğmayacağını belirler. Geometri tipini veya ışık sınıfını değiştirirken bilinçli remount isterim / istemem ayrımını ürün kararına bağlayın.

Koşullu çocuk ({open && <mesh … />}) ağaçtan çıkınca GL kaynağı ne olur? R3F çoğu durumda bağlı nesneyi temizlemeye çalışır; yine de paylaşılmış örnekler ve elle tutulan ref'ler sizin borcunuzdur. Derin dispose borusu yükleme yaprağındadır; burada kimlik / varlık kapısı mühürlenir.

key bilerek kullanılır; rastgele UUID üretmek her karede mezarlık açar.

primitive: deklaratif kaçış eşiği

<primitive object={…} />, halihazırda var olan bir Three nesnesini R3F ağacına taşır. Loader sonucu, üçüncü taraf kurucu veya elle üretilmiş Object3D burada «misafir» olur. Holodepth: primitive bir köprüdür, varsayılan yazım stili değil.

Yanlış kullanım: her şeyi elle yaratıp yalnızca primitive ile yerleştirmek (o zaman neden R3F?). Doğru kullanım: dış kaynaklı nesneyi ağaca bağlamak, parent / visible / dispose diplomasisini açık tutmak. Imperatif performans kaçışı sonraki yaprakta derinleşir; burada eşik tanınır.

Uzlaştırma tuzakları

R3F, React render'ı ile Three durumunu uzlaştırır. Holodepth'in sık görülen kırılma listesi:

Inline obje/dizi prop'ları: her render yeni referans · gereksiz güncelleme veya remount hissi.
Yarım deklaratif: bir prop JSX'te, aynı alan useEffect ile eziliyor · çift kaynak.
Gizli mute: visible={false} ile unmount'u karıştırmak · hâlâ maliyet taşıyan görünmez düğüm.
İsim çakışması: katalogda olmayan etiket · sessiz başarısızlık veya uyarı (sürüme göre değişir).
Kamera çifte aktif: Canvas varsayılanı + sahnede ikinci kamera · kimin render ettiği belirsiz (kök sayfaya köprü).

Kare içi sürekli mutasyon (position.x += …) deklaratif haritanın değil, useFrame diplomasisinin alanıdır. Burada ağaç yazımı; orada ağaç güncellemesi.

Güvenli yazım: simüle katalog

Aşağıdaki örnekler güncel R3F yüzeyine yaslanan öğretim kalıplarıdır. Paket sürümünüzü doğrulayın. Canvas kökü önceki yaprakta mühürlü kabul edilir; React kurulum anlatılmaz.

Simüle · monte edilmiş ürün parçası. boxArgs sabit tutulur; materyal ve geometri açık yuvada.

import { useMemo } from 'react'

// Modül sabiti: her render'da yeni dizi üretmeyin.
const BOX_ARGS = [1, 0.35, 0.6]

export function ProductPart({ selected = false, position = [0, 0, 0] }) {
  // position gibi dizi prop'ları üstten geliyorsa üst bileşende sabitleyin.
  const accent = useMemo(
    () => (selected ? '#5ec8ff' : '#9aa6b8'),
    [selected],
  )

  return (
    <group position={position} name="product-part">
      <mesh castShadow receiveShadow>
        <boxGeometry args={BOX_ARGS} />
        <meshStandardMaterial
          color={accent}
          metalness={0.25}
          roughness={0.45}
        />
      </mesh>
    </group>
  )
}

Simüle · primitive köprüsü. Dışarıda üretilmiş Object3D (ör. loader sonucu) ağaca misafir edilir; sahiplik ve dispose politikası ürün sözleşmesine yazılır.

import { useEffect } from 'react'

/**
 * object: önceden üretilmiş THREE.Object3D
 * disposeOnUnmount: false ise misafir çağıranın mülküdür (paylaşılan sahne).
 */
export function GuestObject({ object, disposeOnUnmount = false }) {
  useEffect(() => {
    return () => {
      if (!disposeOnUnmount || !object) return
      // Eğitim notu: gerçek dispose politikası yükleme yaprağında derinleşir.
      object.traverse?.((child) => {
        child.geometry?.dispose?.()
        const mats = child.material
        if (Array.isArray(mats)) mats.forEach((m) => m.dispose?.())
        else mats?.dispose?.()
      })
    }
  }, [object, disposeOnUnmount])

  if (!object) return null
  return <primitive object={object} />
}

Güvenlik: kullanıcı girdisinden katalog adı veya shader metni üretmeyin. İntrinsic isimleri sabit tutun; dinamik etiket birleştirmesi hem kırılgan hem risklidir. Model URL'leri ve CORS yükleme yaprağının alanıdır.

Üç yazım profili

Aynı katalog üç farklı yazarlık ister. Profil seçmeden «her şeyi primitive» veya «her şeyi tek dosyada mesh yığını» kırılganlıktır.

01 · Graf
Vitrin parçası

Stil

group + açık geometry/material

args

Modül sabiti / tek kaynak

Risk

Inline args dizisi remount
02 · Graf
Montaj sahnesi

Stil

İsimli group katmanları

Pivot

Montaj grubunda · parçalar yerel

Risk

Dünya pozisyonunu her mesh'e yazmak
03 · Graf
Misafir nesne

Stil

primitive + sahiplik notu

Dispose

Çağıran / misafir açıkça ayrılır

Risk

Her şeyi primitive'e kaçırmak

Yardımcı katman sınırı

Drei ve benzeri yardımcılar katalog yazımını hızlandırır; fakat Holodepth onları bu yaprağın omurgası yapmaz. Önce intrinsik haritayı bilin: group, mesh, light, camera, primitive. Yardımcı bir «görünmez ikinci dil» olmamalıdır. İhtiyaç olduğunda bilinçli ekleyin; her sarmalayıcıyı ezber demeti saymayın.

Canvas olay kökü ve picking bir sonraki etkileşim yaprağındadır. Burada yalnızca şunu not ederiz: yardımcı bileşen de aynı uzlaştırma kurallarına (args kimliği, key, yuvalama) tabidir.

Holodepth perspektifleri

Haritayı ezberleyin, sihri değil

«Çalıştı» yetmez. Hangi kapıdan (args / prop / attach) geçtiğinizi söyleyebilmelisiniz.

Kimlik pahalıdır

Gereksiz remount, sessiz GC ve flicker üreticisidir. key ve args referansını ürün kararı gibi yazın.

Tek kaynak

Aynı alanı hem JSX prop hem effect ile ezmeyin. Deklaratif kalın; kaçış bilinçli olsun.

Teşhis maddeleri

İntrinsic isimler katalogla uyumlu mu?
args sabit / memo'lu mu, yoksa her render yeni mi?
Geometri / materyal yuvası görünür mü?
Hiyerarşide pivot bilinçli mi?
key bilerek mi, rastgele mi?
primitive misafir mi, alışkanlık mı?
Çift kaynaklı prop yazımı var mı?
Canvas / loader / picking bu sayfaya sızmış mı?

Holodepth içgörüsü

Deklaratif sahne grafı «React'te 3D yazmak» değildir; Three kataloğunu React uzlaştırıcısıyla konuşturmaktır. Kapıyı (Canvas) mühürledikten sonra haritayı (bu sayfa) okumadan mesh yığmak, gümrüksüz kargo taşımaktır.

Sonraki kapı: useFrame / useThree

Ağaç durduğunda güzeldir; canlı ürün ağacı her karede güncellenir. Sonraki sayfa useFrame / useThree store diplomasisini ve kare içi mutasyon sözleşmesini anlatır. Yükleme, picking ve imperatif kaçış sonraki yapraklardadır.

Bu sayfada öğrendikleriniz

Katalog metaforu (1).
args / prop / attach (2).
Hiyerarşi / yerel uzay (3).
Geometri-materyal yuvaları (4).
key / remount (5).
primitive eşiği (6).
Uzlaştırma tuzakları (7).
Simüle katalog örnekleri (8).
Üç yazım profili (9).
Yardımcı katman sınırı (10).
Holodepth perspektifleri (11).
Sonraki kapı (12).

Komşu sayfalar

React Three Fiber grubunun ikinci yaprağıdır. Kök mühür önceki sayfada; kare güncellemesi sonraki sayfadadır. React temeli React Vitae'de; glTF/GLB şeması format izleklerindedir.

Vitrin parçası

Montaj sahnesi

Misafir nesne

Haritayı ezberleyin, sihri değil

Kimlik pahalıdır

Tek kaynak

Teşhis maddeleri