← Tehnička dokumentacija Faza 1 — Priprema podataka Faza 2 — Import u Unity Faza 3 — Runtime Streaming Building Interaction ↓ Puna specifikacija (ZIP)

Faza 2: Import u Unity

Nakon što su sve četiri pripremne staze (Track A–D, opisane u dokumentu Faza 1: Priprema podataka prije Unity importa) proizvele svoje 1×1 km pločice s pripadajućim JSON metapodacima, slijedi uvoz tih podataka u Unity. Za to postoje dva odvojena, međusobno neovisna Unity Editor alata, koji rade nad istim izvornim datasetom, ali proizvode potpuno različit rezultat:

	Dataset Import Manager	RealTime Asset Importer
Skripta	`ZGConnectDatasetManagerWindow.cs`	`ZGConnectRealtimeStreamerWindow.cs`
Meni	`ZG Connect → Dataset Import Manager`	`ZG Connect → RealTime Asset Importer`
Rezultat	Populira trenutnu Unity scenu — Terrain objekti, building prefabi, vegetacijske maske se stvarno instanciraju u sceni i spremaju kao asseti unutar `Assets/...`	Pakira isti izvorni dataset u AssetBundle-ove unutar `StreamingAssets/ZGConnect/...`, ne dira sadržaj otvorene scene
Runtime sustav koji koristi rezultat	`TerrainStreamingController` (klasični, scene-based streaming iz `Assets/Generated/...`)	`RealtimeStreamingController` (streaming bundle-ova iz `StreamingAssets/` — download/memory-friendly, radi i u buildu bez source assets-a)
Kad se koristi	Editor rad, pregled/debug, manji broj pločica, priprema sadržaja koji ostaje trajno u projektu	Priprema finalnog runtime dataset-a za distribuciju/build, uključujući inkrementalno pakiranje velikih regija

Oba alata čitaju isti dataset root folder (strukturu podfoldera s metadata.json datotekama opisanu u Fazi 1), ali svaki na svoj način: Dataset Import Manager odmah stvara Unity objekte i prefabove, dok RealTime Asset Importer sve pakira u komprimirane bundle-ove koje tek runtime kontroler kasnije učitava po potrebi.

Napomena: ovaj dokument opisuje samo import/pack korak — kako se izvorni podaci pretvaraju u Unity odnosno StreamingAssets sadržaj. Kako TerrainStreamingController i RealtimeStreamingController zatim streamaju taj sadržaj tijekom igranja (LOD, pozicioniranje igrača, memory management, itd.) opisano je u zasebnom dokumentu o runtime streamingu.

Dio 1: Dataset Import Manager

ZGConnectDatasetManagerWindow je EditorWindow s tri taba — Terrain, Buildings, Vegetation — plus dvije dodatne sekcije ispod Terrain taba: Scene Setup i Addressables. Postavke prozora (root folder, sve opcije) se automatski spremaju u EditorPrefs (prefiks ZGConnect.Importer.) i vraćaju pri sljedećem otvaranju.

Dataset Root Folder i skeniranje

Na vrhu prozora korisnik postavlja Dataset Root Folder — nadređeni folder koji sadrži podfoldere s Track A/C outputima (heightmap i basemap izvore). Klik na "Scan for Data Sources" (ScanRootFolder()) prolazi kroz sve direktne podfoldere i za svaki koji sadrži metadata.json pokušava ga parsirati kao jedan od tri prepoznata formata, redom:

HeightmapMetadataJson — prepoznaje se po settings.resolution > 0 i postojanju tiles liste (Track A izlaz)
OrthoMetadataJson — prepoznaje se po settings.textureResolution > 0 i tiles (Track C, ortofoto varijanta)
TiledMetadataJson — prepoznaje se po neprazoj layers listi i tiles (Track C, splatmap/tiled varijanta)

Svaki uspješno prepoznat folder postaje jedan HeightmapSource ili BasemapSource unos u listama koje se prikazuju u UI-u. Ako više foldera zadovoljava isti format (npr. dvije različite heightmap pripreme), korisnik bira aktivni kroz padajući izbornik; basemapovi se biraju kroz checkbox listu (moguće je odabrati više basemapova odjednom — npr. i ortofoto i tiled splatmap se mogu importati zajedno).

Ako se folder vegetation_masks nalazi direktno unutar root foldera, automatski se predlaže kao izvor za Vegetation tab.

Tab: Terrain

Nakon skeniranja, prikazuju se otkriveni izvori (DrawDiscoveredSources) s osnovnim podacima o aktivnom heightmap izvoru (broj tileova, rezolucija, raspon visina, unity origin — izravno očitano iz HeightmapMetadataJson.Settings).

Import Options (DrawImportOptions):

Parametar	Opis
Heightmap Resolution	`Low_513` ili `Medium_1025`. Ako je izabran 513, Unity terrain ga dobiva downsample-ovanjem iz izvornog 1025 raw-a u kodu (izvorna `.raw` datoteka iz Track A ostaje 1025)
Basemap Max Resolution	512/1024/2048/4096 px — gornja granica teksture koju Unity uzima od basemap izvora. Ako je izabrana rezolucija veća od izvorne rezolucije ortofoto izvora, prikazuje se upozorenje (Unity neće upscale-ati)
Tile Selection	`All` (svi tileovi), `FirstN` (ograniči na `Max Tiles`, korisno za brzi test import), `Region` (uvezi samo tileove unutar zadanog EPSG:3765/GPS pravokutnika)
Max Invalid Ratio	Slider 0–0.95 — najveći dopušteni udio nevažećih/no-data piksela u tileu da bi se svejedno importao (mirror istog praga korištenog u Track A pripremi)

Kad je Tile Selection = Region, otvara se dodatni Region Filter blok: bira se preset (Custom / Granice grada Zagreba / Centar grada — geografski presetovi definirani preko ZGConnectMapExtent), način unosa (GPS lat/lon ili direktan EPSG:3765 E/N), a klikom na "Odaberi na karti…" otvara se ZGConnectTileMapWindow — vizualni birač regije na karti. GPS unos se u pozadini pretvara u EPSG:3765 (ZGConnectCoordinates.WGS84ToEPSG3765), a odabrana regija se poravnava na tile grid (HlodGridZones.AlignRegionEpsg) kako bi granice regije uvijek padale na cijele granice tileova. Uživo se prikazuje koliko tileova upada u odabranu regiju.

Output (DrawOutputOptions):

Parametar	Opis
Output Folder	Ciljni Unity asset folder (zadano `Assets/Generated/ZGConnect`)
Skip Existing	Preskoči tileove koji su već importani (inkrementalni import)
Create CityDataset Asset	Stvori/ažuriraj `CityDataset` ScriptableObject koji referencira sve importane tileove — ovo je centralna asset-referenca koju kasnije koriste i Buildings/Vegetation tabovi i `TerrainStreamingController`
Create Scene Objects	Instanciraj stvarne Terrain GameObjecte u trenutnoj sceni
Add CityTile Component	Na svaki terrain GameObject doda `CityTile` komponentu (poveznica na tile metapodatke)
Set Terrain Neighbors	Postavi Unity terrain neighbor reference (za bešavno stitchanje susjednih terena — sjena, normale na rubovima)

Advanced (foldout, skriveno po defaultu): Flip Heightmap Vertically (usklađivanje orijentacije .raw heightmapa s Unity Terrain sustavom), Draw Instanced, Pixel Error (Unity terrain LOD parametar), Basemap Distance (udaljenost do koje se basemap textura prikazuje u punoj rezoluciji).

Klik na Import poziva RunImport(), koji sastavlja ZGConnectImportSettings iz svih gornjih polja i predaje ih u ZGConnectImporter.Import(heightmapMetadata, heightmapFolderPath, selectedBasemaps, settings, progressCallback). Ovo je metoda koja stvarno čita .raw heightmap datoteke i basemap teksture s diska i gradi Unity Terrain objekte/assete.

Scene Setup

Ispod Terrain taba nalazi se odvojena sekcija koja nije vezana za jedan konkretan import: provjerava postoji li već TerrainStreamingController u sceni. Ako ne postoji, gumb "Create ZGConnect Streamer" stvara novi GameObject s tom komponentom (CreateStreamer()) i, ako CityDataset asset već postoji na očekivanoj putanji ({OutputFolder}/Config/ZGConnectDataset.asset), automatski ga dodjeljuje na dataset polje kroz SerializedObject. Ovo je korak koji povezuje importani sadržaj s runtime streaming sustavom (klasičnom, scene-based varijantom).

Addressables Migration

Također ispod Terrain taba: ako CityDataset postoji, prikazuje status migracije (ZGConnectAddressablesMigrator.MigrationStatus) — koliko od ukupnog broja tileova je već registrirano kao Addressable asset. Gumb "Migrate to Addressables" (ZGConnectAddressablesMigrator.MigrateDataset) registrira preostale tileove, čime se omogućuje:

eliminacija editor/runtime freeze-a pri velikim datasetovima (asseti se ne moraju svi držati učitani odjednom)
per-tile oslobađanje memorije tijekom streaminga
priprema za remote content delivery (Addressables mogu poslužiti sadržaj s CDN-a/servera umjesto iz builda)

Nakon migracije potrebno je ručno pokrenuti Addressables build (Window → Asset Management → Addressables → Groups → Build → New Build → Default Build Script) — ovaj korak prozor ne radi automatski, samo registrira asset grupe.

Tab: Buildings

Buildings tab uvozi izlaz Track B pripreme (buildings_{tileId}.glb + JSON per tile) u aktivni CityDataset. Putanje su izvedene, ne unose se ručno:

datasetAssetPath = {OutputFolder}/Config/ZGConnectDataset.asset (mora prvo postojati — stvara ga Terrain import)
rawBuildingsFolder = {RootFolder}/building_meshes/ — sirovi GLB-ovi iz Track B
processedFolder = building_meshes/Processed/ — opcionalna, unaprijed "pečena" (baked) varijanta

Raw vs. Processed tok:

Postoje dva načina uvoza zgrada:

Direktan uvoz sirovih GLB-ova (_buildingsUseProcessed = false) — uvoz čita izravno iz building_meshes/. Moguće je odmah tijekom uvoza raditi i obradu površina (facade/roof), ili koristiti Fast Import za brzi bulk uvoz bez obrade površina.
Uvoz iz unaprijed pečenog "Processed" foldera (_buildingsUseProcessed = true) — prije samog uvoza pokreće se "Bake Processed GLBs" (RunBakeProcessedBuildings → ZGConnectImporter.BakeProcessedBuildings), koji sirove GLB-ove obrađuje i sprema gotove GLB-ove s već zapečenim UV-ima u building_meshes/Processed/. Sam uvoz iz Processed foldera je uvijek "fast" (bez dodatne obrade tijekom uvoza) jer je obrada već napravljena unaprijed.

Opcije obrade površina (dostupne i kod bake-a i kod direktnog uvoza sirovih GLB-ova):

Parametar	Opis
Fast Import	GLB → prefab samo s `BuildingData` komponentom, bez obrade facade/roof mesh-a. Namijenjeno brzom uvozu ~50 tileova odjednom; obrada površina se kasnije može pokrenuti ručno preko `ZG Connect → Buildings → Reprocess Surfaces On Selected Prefabs`
Process Facade / Roof Surfaces	Puni prolaz: facade UV remap + repeating (pločice) tekstura krovova. Isključuje se međusobno s Fast Import i s Roof Orthophoto UV
Roof Orthophoto UV (roofs only)	Mapira UV krovova na cijeli tile (0–1 raspon), tako da krov "pokupi" odgovarajući isječak ortofoto teksture terena kao svoju teksturu (fasade zadržavaju izvorni GLB UV). Zahtijeva da je ortofoto Track C izvor već uvezen ili odabran u skeniranim Terrain izvorima
Surface Settings	`BuildingSurfaceSettings` asset — materijali/teksture za facade i krov. Obavezan kad je uključena obrada površina. Može se generirati preko gumba "Generate Grid Placeholder Textures" (`BuildingSurfaceTextureGenerator.GenerateAll`) za brzi placeholder

Ostale opcije: Skip Existing (preskoči tileove koji već imaju building prefab), Attach BuildingData Component, Filter by Region (koristi isti EPSG:3765 raspon postavljen na Terrain tabu).

Dva gumba za pokretanje:

"Import Buildings" — uvozi sve tileove iz aktivnog foldera (raw ili processed, ovisno o toggleu) preko ZGConnectImporter.ImportBuildings(dataset, buildingsFolder, settings, progress)
"Import Buildings (skip processed)" — uvozi samo raw tileove koji još nemaju odgovarajući GLB u Processed folderu (korisno za inkrementalno dopunjavanje bez re-bake-anja svega)

Tab: Vegetation

Uvozi {tileId}_vegetation.png maske (Track C/D izlaz vegetacijskog OSM prolaza) u CityDataset, dodjeljujući svaki PNG odgovarajućem CityTileRecord.vegetationMask polju preko ZGConnectVegetationMaskImporter. Teksture se importaju s Unity postavkama linear + Read/Write + uncompressed — obavezno za runtime rasterizirano postavljanje vegetacije (sampling piksela u runtimeu).

Opcije: Skip tiles that already have a mask, Filter by region. Rezultat uvoza (RunVegetationImport → ZGConnectVegetationMaskImporter.Import) prikazuje statistiku: broj dodijeljenih maski, preskočenih (već postavljenih), izvan regije, PNG-ova bez odgovarajućeg tile-a u datasetu, i neprepoznatih imena datoteka.

Nakon uvoza maski, stvarno postavljanje vegetacije u sceni radi se na TerrainStreamingController komponenti — potrebno je uključiti Stream Vegetation i dodijeliti VegetationRuleSet te VegetationPrototypes (mesh + materijali na drvo_* assetima). Ovaj korak prozor samo napominje u UI-u, ne radi ga sam.

Dio 2: RealTime Asset Importer

ZGConnectRealtimeStreamerWindow ne populira scenu — umjesto toga pakira izabrani dataset u AssetBundle-ove pod StreamingAssets/ZGConnect/..., spremne za RealtimeStreamingController da ih učitava tijekom igranja (uključujući u gotovom buildu, bez potrebe za source assetima u projektu). Prozor ima dvije accordion sekcije: Parameters i Progress.

External dataset root i skeniranje

Isto kao kod Dataset Import Managera, korisnik postavlja root folder i klikom na "Scan" (ScanRoot) pokreće DatasetFolderScanner.Scan(_rootFolder), koji otkriva heightmap i basemap izvore (isti formati kao gore) te folder s vegetacijskim maskama. Odabir aktivnog heightmap izvora i uključenih basemapova radi se isto kao u Dataset Import Manageru.

Pack Options

Ovo je centralni dio prozora — svaki toggle kontrolira uključuje li se određena vrsta sadržaja u pack, i (za teže operacije) hoće li se ta vrsta unaprijed "peći" (bake) u gotove prefab/bundle oblike:

Parametar	Opis
Terrain (heightmap)	Uključi teren u pack
Pre-bake TerrainData AssetBundles	Unaprijed peče Unity `TerrainData` u AssetBundle za brz runtime load. Ako je uključeno, a nije uključen Ortho, prikazuje se upozorenje jer terrain bundle treba ortofoto texturu — ortofoto se automatski uključi tijekom pack-a ako postoji odabran ortofoto izvor
Ortho basemaps	Uključi ortofoto basemapove
Tiled basemaps	Uključi tiled/splatmap basemapove
Facade buildings	Uključi zgrade s facade obradom
Ortho-roof buildings	Uključi zgrade s roof-orthophoto UV varijantom
Pack building metadata binary (.bytes)	Kopira postojeće `building_meshes_bin` / `building_meshes_ortho_bin` binarne metapodatke ako postoje, inače ih generira iz `buildings_{tileId}.json` tijekom pack-a. Preporuka: unaprijed generirati binarne datoteke preko `ZG Connect → Convert Building Metadata to Binary` radi bržeg pack-a
Vegetation masks	Uključi vegetacijske maske
Building LOD1 boxes (pack-time)	Generira pojednostavljene LOD1 box geometrije zgrada tijekom pack-a
Bake building prefab bundles	Peče building prefabove (kombiniranje mesheva, colliders, materijali) izravno tijekom pack-a umjesto da se to prepusti runtime kontroleru
Building colliders (pack bake)	`Box (fast pack)` ili `Convex mesh (accurate physics)` — kompromis brzine pack-a naspram točnosti fizike
Uncompressed asset bundles	Brže arhiviranje, veće datoteke — koristno za lokalni razvoj
Bake vegetation instance bundles	Peče vegetacijske instance u bundle (koristi `VegetationRuleSet` i razriješene `VegetationPrototype`)
Heightmap resolution	513 ili 1025, isto značenje kao kod Dataset Import Managera
Ortho max resolution	512/1024/2048
Ortho Crunch compression	Uključuje Crunch kompresiju ortofoto tekstura tijekom bundle staginga — primjenjuje se samo kad je uključen Pre-bake TerrainData AssetBundles; viša kvaliteta usporava import tijekom staginga, isključivanje daje brži pack uz nešto veće bundleove
Skip existing packed tiles	Inkrementalno pakiranje — već pakirani tileovi/supertileovi/bundleovi se ponovno koriste, obrađuju se samo novi ili promijenjeni tileovi

Bake-at-pack koncept: kad su Pack building bundles i/ili Bake vegetation bundles uključeni, kombiniranje mesheva, generiranje collidera i postavljanje vegetacije se rade tijekom pack koraka (u editoru), a ne kasnije u runtimeu. To znači da runtime samo učitava već gotove, "lagane" bundleove — box collideri i skraćena LOD geometrija znatno smanjuju veličinu bundleova i vrijeme arhiviranja, po cijenu dužeg samog pack koraka u editoru.

Za bake korake potrebno je dodijeliti BuildingSurfaceSettings (materijali za facade/roof na kombiniranim meshevima) i VegetationRuleSet (pravila za razmještaj vegetacije + izvor VegetationPrototype popisa) — bez njih pack odbija krenuti uz jasnu poruku.

Region Filter

Kao i kod klasičnog importa, moguće je ograničiti pack na EPSG:3765 regiju. Za razliku od Dataset Import Managera, ovdje se granice regije uvijek poravnavaju na 4×4 tile grid (HlodGridZones.AlignRegionEpsg s HlodGridZones.PackRegionAlignFactor), kako bi granice pack-a uvijek padale na granice HLOD supertileova (veći grupirani blokovi tileova korišteni za streaming optimizaciju). "Open tile map picker" otvara isti vizualni birač karte kao kod klasičnog importa.

Pokretanje pack-a

Gumb "Pack Dataset" (PackDataset()):

Validira preduvjete (odabran heightmap izvor, potrebne bake postavke)
Poravna regiju na grid ako je filter uključen
Sastavlja skup ID-jeva tileova unutar regije ({left}_{bottom} format)
Gradi RealtimePackOptions iz svih gornjih polja
Pokreće RealtimeDatasetPackager.PackCoroutine(options, progressCallback, ...) kroz EditorCoroutineRunner — pack radi kao coroutine kako ne bi blokirao editor, uz live progress bar po fazama (RealtimePackProgressTracker — Master napredak + napredak po pojedinoj fazi: terrain, ortho, buildings, vegetation, itd.)
Po završetku, briše privremene staging assete (RealtimePackStagingUtility.CleanupAll()) i prikazuje broj upakiranih tileova. Kod greške, staging prefabovi se namjerno ne brišu, kako bi ih se moglo pregledati radi debugiranja

Rezultat se sprema u StreamingAssets/ZGConnect/ (točna putanja definirana u RuntimeStreamingPaths.PackedDatasetAssetRoot), zajedno s manifestom (StreamingDatasetManifest) koji popisuje sve upakirane tileove i njihov sadržaj — taj manifest kasnije čita RealtimeStreamingController da zna što je dostupno za streaming.

Inkrementalno pakiranje: kad je Skip existing packed tiles uključeno, dovoljno je proširiti EPSG regiju i pokrenuti pack ponovno — već upakirani tileovi, supertileovi i bundleovi se ne obrađuju iznova, obrađuju se samo novi ili promijenjeni. Postojeći manifest se čita preko RealtimePackReuseUtility.TryLoadExistingManifest.

Create Streamer in Scene

Odvojeni gumb koji stvara RealtimeStreamingController komponentu na novom GameObjectu i postavlja joj manifestRelativePath na zadanu putanju manifesta (RuntimeStreamingPaths.DefaultManifestRelativePath). Ovo je scene-setup ekvivalent onome što Dataset Import Manager radi za TerrainStreamingController, samo za realtime streaming sustav.

Sljedeći koraci

Ovim je opisan cijeli tok od pripremljenih Track A–D podataka do dva moguća oblika uvezenog sadržaja u Unity: klasičnog (scene-populating, preko Dataset Import Managera) i realtime streaming pack-a (preko RealTime Asset Importera). Koji put odabrati ovisi o namjeni: klasični import je prikladan za rad u editoru i manje regije koje trebaju ostati trajno u projektu kao asseti, dok realtime pack cilja finalni build i velike regije koje se streamaju s diska tijekom igranja.

Kako se sadržaj iz svakog od ova dva oblika zatim stvarno prikazuje i učitava tijekom igranja (TerrainStreamingController naspram RealtimeStreamingController — LOD, memory management, pozicioniranje oko igrača, itd.) opisano je u zasebnom dokumentu o runtime streamingu.