holodepth

Three.js · Geliştirme ortamı

Modern iş akışına giriş: Neden Vite?

Geleneksel web mimarilerinde Three.js, doğrusal bir <script> enjeksiyonuyla küresel kapsama (global scope) dahil edilirdi. Ancak 3D sahneler karmaşıklaştıkça; harici modüllerin, özel shader dosyalarının (GLSL) ve ağır geometri yükleyicilerinin (GLTFLoader, Draco) bağımlılık hiyerarşisini elle yönetmek sürdürülemez bir mimari darboğaza dönüşür. Modern 3D web geliştirme süreçlerinde, tarayıcı tabanlı yerel ESM (ES Modules) mimarisini ve ışık hızında ön paketleme (pre-bundling) yeteneklerini kullanan yeni nesil araçlar, bu hantallığı tamamen ortadan kaldırarak geliştirme döngüsünü milisaniyeler seviyesine indirger.

Modern iş akışına giriş

Neden Vite'ı seçiyoruz?

  • Hız (The Speed) Vite, modern tarayıcıların yerel ES Modules (ESM) mimarisini doğrudan köprüler. Geleneksel derleyicilerin aksine, projenizin kaynak kod boyutu ne kadar büyük olursa olsun, Esbuild destekli ön paketleme (pre-bundling) sayesinde geliştirme sunucusu milisaniyeler içinde ayağa kalkar ve tarayıcıya sadece o an ihtiyaç duyduğu kodu gönderir.
  • HMR (Hot Module Replacement) Three.js sahnelerinde bir fragment shader modülünü güncellediğinizde, ışık yoğunluğuyla oynadığınızda veya bir kamera açısını değiştirdiğinizde, Vite sayfanın tamamını yeniden yüklemez (Full Reload). Mevcut uygulama durumunu (state) ve render döngüsünü koruyarak yalnızca değişen modülü sahneye anında enjekte eder; böylece görsel test ve hata ayıklama süreciniz kesintisiz akar.
  • Akıllı Varlık (Asset) Yönetimi 3D ekosistemler doğası gereği yüksek veri hacmine sahiptir. Vite; .gltf / .glb formatındaki ağır modelleri, yüksek çözünürlüklü .hdr çevre haritalarını ve karmaşık PBR materyal dokularını (textures) statik varlıklar olarak akıllıca çözümler. Üretim (build) aşamasında bu dosyaları otomatik olarak optimize ederek donanım hızlandırmalı render sürecine en düşük gecikmeyle aktarır.

Geleneksel ve modern geliştirme karşılaştırması

Mimari Özellik Geleneksel (<script> Enjeksiyonu) Modern (Vite + ESM Mimarisi)
Yükleme Hızı & Boyut Three.js çekirdeği ve tüm modüller global olarak yüklenir; gereksiz kodlar (dead code) bellek tüketir. Tree-shaking mekanizması ile sadece kullanılan sınıflar (örn. sadece BoxGeometry) derlenir, dosya boyutu minimize edilir.
Geliştirme Döngüsü (DX) Her değişiklikte tarayıcıda manuel sayfa yenileme gerekir; 3D sahne, kamera ve materyal durumu (state) sıfırlanır. HMR (Hot Module Replacement) ile değişiklikler sahne durumu (kamera açısı, ışık) korunarak milisaniyeler içinde ekrana yansır.
Bağımlılık (Dependency) Yönetimi Dosya yükleme sıralaması (örn. önce Three, sonra Controls) manuel yapılır; karmaşık ve kırılgan bir global yapı oluşur. Yerel ES modülleri (import/export) ile bağımlılıklar otomatik çözülür; temiz, ölçeklenebilir ve izole bir modül ağacı kurulur.
Asset & Performans Optimizasyonu Modeller, dokular (textures) ve GLSL shader dosyalarının yönetimi, sıkıştırılması ve sunulması tamamen manueldir. Üretim (build) aşamasında; varlıklar otomatik önbelleğe alınır, optimize edilir ve modern donanım hızlandırma standartlarına uyarlanır.
Hata Ayıklama & Güvenlik Tip denetimi yoktur; eksik parametreler veya yanlış obje referansları ancak çalışma zamanında (runtime) konsolda patlayınca fark edilir. TypeScript desteği ve gelişmiş IDE entegrasyonu (IntelliSense) sayesinde, matris veya vektör hataları daha kod yazılırken anında tespit edilir.

Kurulum ve paket yönetimi

Bir Three.js projesinin kalbi package.json dosyasıdır. Burada sadece kodları değil, projenin tüm yaşam döngüsünü yönetiriz.

Adım adım başlangıç

Proje iskeleti: Aşağıdaki komutu kullandığımızda Vite temiz bir klasör yapısı sunar. "Vanilla JavaScript" seçeneği, Three.js'in saf gücünü anlamak için iyi bir başlangıçtır.

npm create vite@latest

Komut çalıştıktan sonra Vite etkileşimli olarak birkaç soru sorar. Verdiğiniz yanıtlar, oluşacak klasörü, package.json içeriğini ve hangi şablon dosyaların (saf JS mi, TypeScript mi, hangi çatı ile mi) üretileceğini belirler.

  • Project name — Proje klasörünün adıdır (örneğin my-three-app). Bu isimle yeni bir dizin oluşturulur; bağımlılık kurulumu ve npm run dev gibi komutları hep bu dizinin içinden çalıştırırsınız.
  • Select a framework — Vanilla seçtiğinizde ekstra UI çatısı olmadan düz JavaScript düzeni kurulur; Three.js'i doğrudan import ederek sahneyi öğrenmek için bu rehberle uyumludur. React, Vue veya Svelte seçerseniz bileşen tabanlı uygulama iskeleti gelir; Three.js genelde bu çatının yaşam döngüsü ve durum yönetimiyle entegre edilir (örneğin React tarafında sıkça @react-three/fiber ekosistemi).
  • Select a variant — JavaScript ile kaynaklar .js olarak gelir; derleyici ve tip katmanı olmadan hızlı başlangıç sağlar. TypeScript seçerseniz .ts dosyaları ve tip denetimi devreye girer; büyüyen projelerde IDE desteği ve refaktör güveni artar (bu sayfada anlatılan saf öğrenme yolu için JavaScript yeterlidir).

Proje klasörüne girme: Sorular tamamlandıktan sonra terminalde oluşan proje dizinine geçin. Aşağıdaki my-three-app yerine Project name adımında yazdığınız klasör adını kullanın; yalnızca o klasörün içindeyken bir sonraki bölümdeki npm install komutları doğru yere kurulum yapar.

cd my-three-app

Kütüphanelerin dahil edilmesi

npm install three
npm install --save-dev @types/three

@types/three, VS Code kullanıyorsanız IntelliSense sağlayarak hata riskini azaltır.

Dizin hiyerarşisi

  • src/ — Tüm JavaScript/TypeScript dosyaları, shader'lar ve uygulama mantığı.
  • public/ — Modeller (.glb), sesler ve görseller. Vite bu klasöre kök üzerinden doğrudan erişim sağlar.

Node.js ve NPM ekosistemi

Vite'ın komut satırı aracı (npm create vite, npm run dev) Node.js üzerinde çalışır; geliştirme sunucusu ve üretim derlemesi bu yüzden makinenizde Node kurulu olmalıdır. npm (Node Package Manager) bağımlılıkları package.json'a yazar ve indirir; aynı işi pnpm veya Yarn ile de yapabilirsiniz; hangi aracı seçtiğiniz ekip tercihi ve kilit dosyası uyumu meselesidir.

Tarayıcı uyumluluğu ve WebGL kontrolü

Modern tarayıcıların neredeyse tamamı WebGL sunsa da, "benim makinede çalışıyor" varsayımıyla ilerlemek risklidir. Üretim öncesi veya yeni bir cihazda, WebGL'in gerçekten etkin olduğunu doğrulamak iyi bir alışkanlıktır (örneğin üçgen bir sahne açıp konsolda hata olmaması, THREE.WebGLRenderer'ın oluşturulması veya tarayıcı geliştirici araçlarında WebGL bağlamının görünmesi). Bu, özellikle kurumsal ortamda donanım hızlandırması kısıtlı makinelerde sorun çıkmadan yakalamanıza yardım eder.

Vite konfigürasyonu (vite.config.js)

Çoğu küçük proje varsayılan Vite ayarıyla yeterlidir. Shader dosyalarını (.glsl) doğrudan import ile string olarak almak, özel varlık yolları veya eklenti tabanlı dönüşümler istiyorsanız kök dizinde bir vite.config.js (veya .ts) tanımlarsınız. Örneğin GLSL içe aktarımı için toplulukta sık kullanılan vite-plugin-glsl benzeri bir eklenti eklemek, shader dosyalarını modül gibi yönetmenizi sağlar; tek dosyalık demolar için şart değildir; daha büyük veya shader ağırlıklı sahnelerde profesyonel bir adımdır.

Modül Yapısı ve Modern Standartlar

Gelişen WebGL ekosistemiyle birlikte Three.js; yüzlerce matematiksel sınıf, karmaşık geometri jeneratörü ve devasa materyal modülü barındıran geniş çaplı bir kütüphaneye dönüşmüştür. Tüm bu monolitik yapıyı uygulamanın başlangıcında (initial load) tek seferde tarayıcıya yüklemeye çalışmak, ana iş parçacığını (main thread) bloke ederek açılış hızını ve etkileşime geçme süresini (TTI) dramatik şekilde düşürür. Modern modüler mimari, bu darboğazı aşmanın temel anahtarıdır.

ES Modules (ESM) ve Tree Shaking (Ölü Kod Eleme)

Eski nesil global tanımlamalar yerine import { Scene, PerspectiveCamera, WebGLRenderer } from 'three' gibi isimlendirilmiş içe aktarımlar (named imports) kullanarak, uygulamanızın bellek ayak izini en baştan kontrol altına almış olursunuz.

Tree Shaking: Bu modern mimarinin en büyük getirisidir. Üretim (build) aşamasında Vite ve arka plandaki derleyici, kodunuzun soyut sözdizimi ağacını (AST) analiz eder. Projede hiç çağırmadığınız Three.js modüllerini (örneğin; sahnede hiç kullanmadığınız FogExp2 sınıfını veya CylinderGeometry nesnesini) derlenmiş nihai paketten (bundle) tamamen ayıklar. Bu akıllı eleme işlemi sayesinde son kullanıcı, megabaytlarca gereksiz veri yerine sadece sahnenin ihtiyaç duyduğu optimize edilmiş kilobaytlık çekirdek paketi indirir.

Import Maps: Tarayıcı Seviyesinde Bağımlılık Çözümleme

Modern web standartlarının (W3C) güçlü bir bileşeni olan Import Maps, "çıplak modül belirteçlerinin" (bare module specifiers) doğrudan tarayıcı tarafından anlaşılmasını sağlar. Kod yapınızda karmaşık ve kırılgan ../../node_modules/three/build/three.module.js gibi göreceli dosya yolları belirtmek yerine, temiz bir şekilde doğrudan paket ismiyle aktarım yapmanıza olanak tanır. Import maps, bu soyut ismin hangi yerel yola veya üretim ortamındaki hangi CDN adresine çözümleneceğini tek bir merkezden yönetir; böylece bağımlılık ağacınızı geleceğe dönük, modüler ve son derece esnek tutar.

İlk render testi: Sahneyi Ayağa Kaldırmak

Geliştirme ortamınızın (Vite, ESM ve bağımlılıkların) doğru yapılandırıldığını doğrulamanın en kesin yolu, ekrana donanım hızlandırmalı ilk pikselleri çizmektir. Ekranda beliren basit bir geometri parçası, aslında kaputun altında WebGL'in karmaşık grafik boru hattının (graphics pipeline) sorunsuz çalıştığını kanıtlar.

Bu temel "Merhaba Evren" testi; matematiksel uzayı, perspektif projeksiyonunu ve grafik bağlamını bir araya getiren Three.js'in üç temel mimari direğinin (Core Pillars) entegrasyonuna dayanır:

  • Sahne (Scene)

    Evrenin kendisi. Nesnelerin (modeller, geometriler), ışıkların ve çevresel efektlerin yerleştirildiği üç boyutlu sonsuz koordinat düzlemidir. İçine bir nesne veya ışık kaynağı eklemediğiniz sürece, varsayılan olarak zifiri karanlık bir boşluktan ibarettir. Uygulamanızın bel kemiğidir.

  • Kamera (Camera)

    Gözlemcinin vizörü. Bu sonsuz sanal evrene hangi koordinattan ve hangi açıyla bakılacağını matematiksel olarak belirler. İnsan gözünün derinlik algısını kusursuzca taklit eden PerspectiveCamera, nesnelerin kameradan uzaklaştıkça küçülmesini sağlayarak sahneye gerçekçi bir hacim katar.

  • Render Motoru (Renderer)

    Görüntü işlemcisi. Sahnedeki nesnelerin verisini ve kameranın bakış açısını alıp birleştirir. WebGL altyapısını kullanarak kaputun altındaki ağır matris hesaplamalarını yapar ve nihai görüntüyü saniyede 60 kare (60fps) hızında, ekrandaki HTML <canvas> elementine pikseller halinde boyar.

Geliştirici yardımcıları (dev tools)

  • OrbitControls (Mekânsal Gezinme): Geliştirme aşamasındaki en temel "gözünüzdür". Fare veya dokunmatik hareketleri algılayarak sahnenin etrafında 360 derece dönmenizi (orbit), yakınlaşıp uzaklaşmanızı (zoom) ve kaydırma (pan) yapmanızı sağlar. Kameranın karmaşık matris hesaplamalarını sizin yerinize otomatik olarak yöneterek 3D uzayda özgürce test yapmanıza olanak tanır.
  • Stats.js (Performans Profili): Render döngünüzün (render loop) ne kadar verimli çalıştığını anlık olarak izlemenizi sağlayan hafif bir analiz aracıdır. Ekrana eklediği küçük bir grafikle saniyedeki kare hızını (FPS), her bir karenin işlenme süresini (MS) ve anlık bellek tüketimini (Memory) gösterir. Sahneye ağır bir model veya karmaşık bir materyal eklediğinizde oluşabilecek performans darboğazlarını anında tespit etmenizi sağlar.
  • Lil-gui (Canlı Hata Ayıklama Paneli): Modern, hafif ve son derece temiz bir arayüze sahip hızlı prototipleme (rapid prototyping) aracıdır. Sahnede bir ışığın şiddetini, bir nesnenin konumunu veya materyalin rengini değiştirmek için sürekli editöre dönüp kod yazmak yerine; bu değişkenleri ekrandaki kaydırıcılar (slider), renk paletleri ve butonlar aracılığıyla çalışma zamanında (runtime) dinamik olarak kontrol etmenizi sağlar.

Uygulamalı kurulum rehberi

Video notu: Bu rehberde modern ES Modules yapısı kullanılmıştır. Sürecin sorunsuz ilerlemesi için bilgisayarınızda Node.js (LTS önerilir) kurulu olmalıdır. Terminalde node -v yazarak kurulumu kontrol edebilirsiniz.

Olası sorunlar ve çözümleri

PowerShell "Execution Policy" Güvenlik Engeli

Sorun (Semptom): Windows ortamında geliştirme yaparken terminale npm run dev yazdığınızda; "scripts cannot be loaded because running scripts is disabled on this system" şeklinde kırmızı renkli, uzun bir erişim reddi hatasıyla karşılaşırsınız. Sunucu ayağa kalkmaz.

Arka Plan & Çözüm: Bu bir Node veya Vite hatası değil, Windows PowerShell'in kötü niyetli scriptleri engellemek için varsayılan olarak kapalı tuttuğu güvenlik politikasıdır (Restricted Mode). Çözmek için PowerShell terminalini Yönetici (Administrator) olarak çalıştırıp aşağıdaki komutu girmeniz yeterlidir:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Bu komut, makinenizde yerel olarak oluşturduğunuz geliştirme scriptlerinin (Vite gibi) çalışmasına kalıcı olarak izin verir.

"Node" veya "npm" Komutu Tanınmıyor (PATH Hatası)

Sorun (Semptom): Terminal ekranına kurulum yapmak için npm install veya versiyon kontrolü için node -v yazdığınızda; "command not found" veya "is not recognized as an internal or external command" hatası alırsınız.

Arka Plan & Çözüm: Bu durum, Node.js bilgisayarınızda yüklü olsa bile işletim sisteminizin ortam değişkenlerinde (Environment Variables) bu programın nerede bulunduğunu bilmediği anlamına gelir. En güvenilir çözüm: Node.js yükleyicisini (installer) tekrar çalıştırıp onarım (repair/modify) seçeneğine gitmek ve kurulum adımları sırasında "Add to PATH" (PATH'e Ekle) seçeneğinin kesinlikle işaretli olduğundan emin olmaktır. İşlem bittikten sonra mevcut terminali kapatıp yeniden açmanız gerekir.

Port Çakışması (EADDRINUSE)

Sorun (Semptom): Geliştirme sunucusunu başlatmak istediğinizde terminal "Error: listen EADDRINUSE: address already in use :::5173" hatası fırlatır ve süreç sonlanır.

Arka Plan & Çözüm: Vite, geliştirme ortamını yerel ağda varsayılan olarak 5173 numaralı port üzerinden yayınlar. Eğer arka planda açık unutulmuş başka bir proje veya farklı bir uygulama zaten bu portu dinliyorsa sistem çakışma yaşar. Vite genellikle bir sonraki boş porta (örn: 5174) otomatik geçiş yapsa da, portu kendiniz zorlamak isterseniz başlatma komutuna bir bayrak (flag) ekleyebilirsiniz:
npm run dev -- --port 8080
Veya arka planda asılı kalan Node süreçlerini terminalinizden (Windows'ta Görev Yöneticisi, Mac/Linux'ta killall node) temizleyebilirsiniz.