Needle Engine Dokumentation
Downloads
  • What is Needle Engine?
  • Erfahrungsberichte
  • Get an overview

    • Samples and Showcase
    • Unsere Vision 🔮
    • Funktionsübersicht
    • Technischer Überblick
  • Resources

    • Pricing and Plans
    • Changelog
    • API Documentation
    • Support & Community
  • Integrations

    • Needle Engine für Unity
    • Needle Engine für Blender
    • Needle Engine als Web Component
    • Needle Engine auf Ihrer Website
    • Needle Cloud
  • Core Concepts

    • Struktur eines Needle Engine-Projekts
    • Everywhere Actions
    • Assets nach glTF exportieren
    • Frameworks, Bundler, HTML
    • Testen auf lokalen Geräten
    • Bereitstellung und Optimierung
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Netzwerkfunktionen
    • MaterialX
    • Editor Synchronisierung
  • Troubleshooting

    • Fehlerbehebung
    • Fragen und Antworten (FAQ) 💡
    • Support and Community
  • Videos

    • Tutorials on Youtube
    • Interviews on Youtube
  • Scripting Overview

    • Skripting in Needle Engine
    • Einführung in das Scripting für Unity-Entwickler
    • Needle-Kernkomponenten
    • Everywhere Actions
  • Components and Lifecycle

    • Komponenten erstellen und verwenden
    • @serializable und andere Decorators
    • Automatische Komponenten-Generierung
    • Scripting Beispiele
    • Community Contributions
    • Zusätzliche Module
  • Settings and APIs

    • <needle-engine> Konfiguration
    • needle.config.json
    • Needle Engine API
    • three.js API
Help
Samples
Pricing
  • Needle Website
  • Needle Cloud
  • Support Community
  • Discord Server
  • X/Twitter
  • YouTube
  • Newsletter
  • Email
  • Feedback
  • Github
  • English
  • 简体中文
  • Español
  • Português
  • Français
  • हिन्दी
  • 日本語
  • Deutsch
  • Tiếng Việt
Downloads
  • What is Needle Engine?
  • Erfahrungsberichte
  • Get an overview

    • Samples and Showcase
    • Unsere Vision 🔮
    • Funktionsübersicht
    • Technischer Überblick
  • Resources

    • Pricing and Plans
    • Changelog
    • API Documentation
    • Support & Community
  • Integrations

    • Needle Engine für Unity
    • Needle Engine für Blender
    • Needle Engine als Web Component
    • Needle Engine auf Ihrer Website
    • Needle Cloud
  • Core Concepts

    • Struktur eines Needle Engine-Projekts
    • Everywhere Actions
    • Assets nach glTF exportieren
    • Frameworks, Bundler, HTML
    • Testen auf lokalen Geräten
    • Bereitstellung und Optimierung
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Netzwerkfunktionen
    • MaterialX
    • Editor Synchronisierung
  • Troubleshooting

    • Fehlerbehebung
    • Fragen und Antworten (FAQ) 💡
    • Support and Community
  • Videos

    • Tutorials on Youtube
    • Interviews on Youtube
  • Scripting Overview

    • Skripting in Needle Engine
    • Einführung in das Scripting für Unity-Entwickler
    • Needle-Kernkomponenten
    • Everywhere Actions
  • Components and Lifecycle

    • Komponenten erstellen und verwenden
    • @serializable und andere Decorators
    • Automatische Komponenten-Generierung
    • Scripting Beispiele
    • Community Contributions
    • Zusätzliche Module
  • Settings and APIs

    • <needle-engine> Konfiguration
    • needle.config.json
    • Needle Engine API
    • three.js API
Help
Samples
Pricing
  • Needle Website
  • Needle Cloud
  • Support Community
  • Discord Server
  • X/Twitter
  • YouTube
  • Newsletter
  • Email
  • Feedback
  • Github
  • English
  • 简体中文
  • Español
  • Português
  • Français
  • हिन्दी
  • 日本語
  • Deutsch
  • Tiếng Việt
  • Getting Started

    • Downloads
    • Needle Engine for Unity
    • Needle Engine for Blender
    • Needle Engine as Web Component
    • Needle Engine on your Website
    • Needle Cloud
    • Custom integrations
    • Support and Community
  • Core Concepts

    • Struktur eines Needle Engine-Projekts
    • Everywhere Actions
    • Assets nach glTF exportieren
    • Frameworks, Bundler, HTML
    • Testen auf lokalen Geräten
    • Bereitstellung und Optimierung
  • Scripting

    • Skripting in Needle Engine
    • Einführung in das Scripting für Unity-Entwickler
    • Komponenten erstellen und verwenden
    • Automatische Komponenten-Generierung
    • Scripting Beispiele
    • Community Contributions
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Netzwerkfunktionen
    • MaterialX
    • Editor Synchronisierung
  • Troubleshooting

    • Fehlerbehebung
    • Fragen und Antworten (FAQ) 💡
    • Support and Community
  • Reference

    • Funktionsübersicht
    • Technischer Überblick
    • Needle-Kernkomponenten
    • needle.config.json
    • <needle-engine> Konfiguration
    • @serializable und andere Decorators

Assets, Animationen, Prefabs, Materialien, Lightmaps exportieren...

Fügen Sie Ihrer Unity-Szene eine ExportInfo-Komponente hinzu, um ein neues Webprojekt aus einem Template zu generieren, einen Link zu einem vorhandenen Webprojekt herzustellen, in das Sie exportieren möchten, Abhängigkeiten zu anderen Bibliotheken und Paketen einzurichten und Ihr Projekt bereitzustellen.

Standardmäßig wird Ihre Szene beim Speichern exportiert. Diese Einstellung kann geändert werden, indem Auto Export in der ExportInfo-Komponente deaktiviert wird.

📦 glTF-Dateien exportieren

Um Meshes, Materialien, Animationen, Texturen (...) zu exportieren, erstellen Sie ein neues GameObject in Ihrer Hierarchie und fügen Sie ihm eine GltfObject-Komponente hinzu. Dies ist die Wurzel einer neuen glTF-Datei. Sie wird jedes Mal exportiert, wenn Sie eine Änderung an der Szene vornehmen und speichern.

Nur Skripte und Daten auf und innerhalb dieser Wurzelobjekte werden exportiert. Skripte und Daten außerhalb davon werden nicht exportiert.

Fügen Sie Ihrem Wurzelobjekt einen Würfel als Kind hinzu und speichern Sie Ihre Szene. Beachten Sie, dass der Ausgabeordner assets/ (siehe project structure) nun eine neue .glb-Datei mit demselben Namen wie Ihr Wurzel-GameObject enthält.

Sie können die Einstellung Smart Export (über Edit/Project Settings/Needle) aktivieren, um nur zu exportieren, wenn eine Änderung in der Hierarchie dieses Objekts erkannt wird.

Wie man verhindert, dass bestimmte Objekte exportiert werden

Objekte mit dem Tag EditorOnly werden beim Export ignoriert, einschließlich ihrer Kindhierarchie. Beachten Sie, dass dies dem Deaktivieren von Objekten vorzuziehen ist, da deaktivierte Objekte weiterhin exportiert werden, falls sie später wieder eingeschaltet werden.

Lazy loading und mehrere Level / Szenen

Wenn Sie Ihre Anwendung in mehrere Level oder Szenen aufteilen möchten, können Sie einfach die Komponente SceneSwitcher verwenden. Sie können Ihre Anwendung dann in mehrere Szenen oder Prefabs strukturieren und diese dem SceneSwitcher-Array hinzufügen, um zur Laufzeit geladen und entladen zu werden. Dies ist eine großartige Möglichkeit, um nicht alle Inhalte auf einmal laden zu müssen und die Ladezeiten gering zu halten (zum Beispiel haben wir das bei needle.tools gemacht, indem wir jeden Abschnitt unserer Website in eine eigene Szene unterteilt und diese nur bei Bedarf geladen haben)

Empfohlene Komplexität pro glTF

  • Max. 50 MB Exportgröße unkomprimiert (endet normalerweise bei ~10-20 MB komprimiert)
  • Max. 500k vertices (weniger, wenn Sie auch mobiles VR anvisieren)
  • Max. 4x 2k lightmaps

Sie können Szenen und Prefabs in mehrere glTF-Dateien aufteilen und diese dann bei Bedarf laden (nur wenn benötigt). Dies hält die Ladeleistung schnell und die Dateigröße klein. Siehe den Abschnitt AssetReference section in the Scripting docs.

Die hier empfohlene Szenenkomplexität soll eine gute Leistung auf einer Reihe von webfähigen Geräten und Bandbreiten gewährleisten. Es gibt keine technische Einschränkung darüber hinaus, als die Fähigkeiten Ihres Geräts.

Prefabs

Prefabs können als einzelne glTF-Dateien exportiert und zur Laufzeit instanziiert werden. Um ein Prefab als glTF zu exportieren, referenzieren Sie einfach ein Prefab-Asset (aus dem Projektbrowser und nicht in der Szene) from one of your scripts.

Das Exportieren von Prefabs funktioniert auch mit Verschachtelung: Eine Komponente in einem Prefab kann ein anderes Prefab referenzieren, das dann ebenfalls exportiert wird. Dieser Mechanismus ermöglicht es, Szenen so leichtgewichtig wie möglich zu gestalten und zuerst die wichtigsten Inhalte zu laden und das Laden zusätzlicher Inhalte zu verzögern.

Scene Assets

Ähnlich wie Prefab assets können Sie andere Scene assets referenzieren. Erstellen Sie dazu in Unity eine Komponente mit einem UnityEditor.SceneAsset-Feld und fügen Sie diese einem Ihrer GameObjects innerhalb eines GltfObject hinzu. Die referenzierte Szene wird nun als separate glTF-Datei exportiert und kann als AssetReference aus TypeScript geladen/deserialisiert werden.

Sie können weiterhin in einer referenzierten Szene arbeiten und Ihre Haupt-Exporter-Szene/Website aktualisieren. Beim Speichern der Szene oder beim Wechsel des Play-Modus erkennen wir, ob die aktuelle Szene von Ihrem derzeit laufenden Server verwendet wird, und lösen dann einen erneuten Export nur für dieses glb aus. (Diese Prüfung erfolgt anhand des Namens - wenn eine glb in Ihrem Ordner <web_project>/assets/ existiert, wird sie erneut exportiert und die Hauptszene lädt sie neu.)

Ein Beispiel auf unserer website: Jeder Abschnitt ist als separate Szene eingerichtet und wird beim Export in mehrere glb-Dateien gepackt, die wir bei Bedarf laden:

2022-08-22-172605_Needle_Website_-Website-_Windows,_Mac,Linux-_U

Laden eines Prefabs oder einer Szene aus einem benutzerdefinierten Skript

Wenn Sie ein Prefab aus einem Ihrer Skripte referenzieren und laden möchten, können Sie einen Typ AssetReference deklarieren. Hier ist ein minimales Beispiel:

import { Behaviour, serializable, AssetReference } from "@needle-tools/engine";

export class MyClass extends Behaviour {

    // if you export a prefab or scene as a reference from Unity you'll get a path to that asset
    // which you can de-serialize to AssetReference for convenient loading
    @serializable(AssetReference)
    myPrefab?: AssetReference;
    
    async start() {
      // directly instantiate
      const myInstance = await this.myPrefab?.instantiate();

      // you can also just load and instantiate later
      // const myInstance = await this.myPrefab.loadAssetAsync();
      // this.gameObject.add(myInstance)
      // this is useful if you know that you want to load this asset only once because it will not create a copy
      // since ``instantiate()`` does create a copy of the asset after loading it
    }  
}

🏇 Animationen exportieren

Needle Engine unterstützt eine beträchtliche und leistungsstarke Untermenge von Unitys Animationsfunktionen:

  • Timeline inkl. Aktivierungs-Tracks, Animations-Tracks, Track-Offsets
  • Animator inkl. Übergänge zwischen Top-Level-States
    • Blend trees werden derzeit nicht unterstützt.
    • Sub state machines werden derzeit nicht unterstützt.
  • AnimationClips inkl. Loop-Modi
  • Prozedurale Animationen können per Skripting erstellt werden

Needle Engine ist einer der Ersten, die die neue glTF extension KHR_ANIMATION_POINTER unterstützen. Das bedeutet, dass fast alle Eigenschaften, einschließlich Skriptvariablen, animierbar sind.

Eine aktuelle Einschränkung ist, dass Materialien beim Export nicht dupliziert werden – wenn Sie dasselbe Material mit unterschiedlichen Farben animieren möchten, müssen Sie das Material derzeit in zwei Teile aufteilen.

🌍 Skybox exportieren

Die Unity Skybox und benutzerdefinierte Reflexionen (falls vorhanden) werden beim Export in eine Textur gebacken und automatisch innerhalb der NEEDLE_lightmaps extension exportiert.

Um die Skybox-Auflösung zu ändern, können Sie Ihrer Szene eine Komponente SkyboxExportSettings hinzufügen.

image

Wenn Sie nicht möchten, dass die Skybox überhaupt in einer glb-Datei exportiert wird, können Sie die Option Embed Skybox auf Ihrer GltfObject-Komponente deaktivieren.

image

✨ Materialien exportieren

Physically Based Materials (PBR)

Standardmäßig werden Materialien beim Export in glTF-Materialien konvertiert. glTF unterstützt ein physikalisch basiertes Materialmodell und verfügt über eine Reihe von Extensions, die helfen, komplexe Materialien darzustellen.

Für volle Kontrolle darüber, was exportiert wird, wird dringend empfohlen, die von UnityGltf bereitgestellten glTF-Materialien zu verwenden:

  • UnityGLTF/PBRGraph
  • UnityGLTF/UnlitGraph

Im Zweifelsfall den PBRGraph shader verwenden.

Das PBRGraph-Material hat viele Funktionen, weitaus mehr als die "Standard" oder "Lit" shaders provided by Unity. Diese Funktionen umfassen Oberflächeneffekte wie clearcoat, sheen, iridescence und volumetrische Effekte wie transmission, refraction und dispersion.

Andere shaders that can be exported directly (with conversion):

  • Universal Render Pipeline/Lit
  • Universal Render Pipeline/Unlit
  • Standard (Built-in Render Pipeline)
  • Autodesk Interactive (Built-in Render Pipeline)
  • Unlit (Built-in Render Pipeline)

Andere Materialien werden über eine Eigenschaftsnamen-Heuristik konvertiert. Das bedeutet, dass Sie je nach den Eigenschaftsnamen, die Ihre Materialien und shaders verwenden, entweder die Eigenschaften Ihres custom shader's umbenennen müssen, um die Eigenschaftsnamen von Universal Render Pipeline/Lit oder PBRGraph zu verwenden, oder das Material als Custom Shader exportieren müssen.

Custom Shaders

Um benutzerdefinierte Unlit-shaders (z. B. mit ShaderGraph erstellt) zu exportieren, fügen Sie dem shader, den Sie exportieren möchten, ein ExportShader Asset Label hinzu. Asset Labels sind am unteren Rand des Inspektors zu sehen.

2022-08-22-172029_Needle_Website_-CustomShaders-_Windows,_Mac,_Lin

Einschränkungen

  • Wir unterstützen derzeit nur benutzerdefinierte Unlit-shaders — Lit shader conversion is not officially supported.
  • Benutzerdefinierte Lit shaders sind derzeit experimentell. Nicht alle Rendering-Modi werden unterstützt.
  • Der Empfang von Schatten auf benutzerdefinierten shaders wird nicht unterstützt
  • Skinned meshes mit benutzerdefinierten shaders werden nicht unterstützt
  • Da es beim Übergang von Unity zu three.js und glTF mehrere Koordinatensystemänderungen gibt, können einige Änderungen erforderlich sein, damit erweiterte Effekte funktionieren. Wir versuchen, Daten beim Export zu konvertieren, erfassen aber möglicherweise nicht alle Fälle, in denen Konvertierungen erforderlich sind.
    • UV coordinates in Unity start at the bottom left; in glTF they start at the top left.
    • X axis values are flipped in glTF compared to Unity. This is a variant of a left-handed to right-handed coordinate system change. Data used in shaders may need to be flipped on X to display correctly.

Nicht Teil der glTF-Spezifikation

Beachten Sie, dass Custom Shaders nicht offiziell Teil der glTF-Spezifikation sind. Unsere Implementierung von custom shaders uses an extension called KHR_techniques_webgl, that stores the WebGL shader code directly in the glTF file. Die resultierenden assets will work in viewers based on Needle Engine.

💡 Lightmaps exportieren

2022-08-22-171650_Needle_-_Google_Chrome

Um lightmaps zu exportieren, generieren Sie einfach lightmaps in Unity. Lightmaps werden automatisch exportiert.

Beim Arbeiten an mehreren Szenen deaktivieren Sie "Auto Generate" und bake lightmaps explizit. Andernfalls verwirft Unity temporary lightmaps on scene change.

Empfohlene Lightmap-Einstellungen

  • Lightmap Encoding: Normal Quality (adjust in Project Settings > Player)
  • Progressive GPU (faster and usually accurate enough for small scenes)
  • Non-Directional Lightmaps
  • Max Lightmap Size 2k (you can go higher, but expect large files)
  • Max 4x 2k lightmaps per scene (you can go higher, but expect large files)
  • Compress Lightmaps OFF (increases quality; otherwise will be compressed again at export time)

2022-08-22-171356_Needle_Website_-Lightmaps-_Windows,_Mac,Linux-

Mischen von Baked und Non-Baked Objekten

Es gibt keine 100%ige Übereinstimmung zwischen der Art und Weise, wie Unity Lichter und Umgebung handhabt, und wie three.js dies tut. Zum Beispiel hat Unity völlig separate code paths for lightmapped and non-lightmapped objects (lightmapped objects don't receive ambient light since that is already baked into their maps), and three.js doesn't distinguish in that way.

Das bedeutet, um beste Ergebnisse zu erzielen, empfehlen wir derzeit spezifische Einstellungen, wenn Sie baked und non-baked objects in einer Szene mischen:

Environment Lighting: Skybox
Ambient Intensity: 1
Ambient Color: black

2021.3+20220826-175324-SqBL-Unity_pMXa-needle

2020.3+20220826-175514-tnGc-Unity_mycs-needle

Wenn Sie keine baked objects in Ihrer Szene haben, sollten auch die folgenden Einstellungen korrekte Ergebnisse liefern:

Environment Lighting: Color
Ambient Color: any

Seite automatisch übersetzt mit AI

Suggest changes
Zuletzt aktualisiert: 15.08.25, 08:05
Prev
Everywhere Actions
Next
Frameworks, Bundler, HTML