Bundling und Web Frontends

Needle Engine ist als Web Component aufgebaut. Das bedeutet, installiere einfach @needle-tools/engine in deinem Projekt und füge <needle-engine src="path/to/your.glb"> überall in deinem Webprojekt ein.

• Installation via npm: npm i @needle-tools/engine

Mit unserer Standard-Vite-basierten Projektvorlage wird Needle Engine bei der Bereitstellung zu einer Web-App gebündelt. Dies sorgt für kleinere Dateien, Tree-Shaking (ähnlich dem Code-Stripping in Unity) und optimiert die Ladezeiten. Anstatt zahlreiche kleine Skripte und Komponenten herunterzuladen, wird nur eines oder wenige heruntergeladen, die den minimal benötigten Code enthalten.

Vite (unser Standard-Bundler) erklärt gut, warum Web-Apps für die Produktion gebündelt werden sollten: Why Bundle for Production

Vite, Vue, React, Svelte, React Three Fiber...

Needle Engine ist unvoreingenommen bezüglich der Wahl des Frameworks. Unsere Standardvorlage verwendet das beliebte vite als Bundler. Von dort aus kannst du vue, svelte, nuxt, react, react-three-fiber oder andere Frameworks hinzufügen, und wir haben Beispiele für viele davon. Du kannst auch andere Bundler integrieren oder gar keinen verwenden – einfach reines HTML und Javascript.

Hier sind einige Beispiel-Tech-Stacks, die möglich sind und mit denen wir Needle Engine verwenden:

• Vite + HTML – Das verwendet unsere Standardvorlage!

• Vite + Vue – Das verwendet die Website von Needle Tools! Ein Beispiel zum Herunterladen findest du hier.

• Vite + Svelte

• Vite + SvelteKit

• Vite + React – Es gibt eine experimentelle Vorlage, die mit der Unity-Integration geliefert wird und die du bei der Projekterstellung auswählen kannst!

• react-three-fiber – Es gibt eine experimentelle Vorlage, die mit der Unity-Integration geliefert wird und die du bei der Projekterstellung auswählen kannst!

• Vercel & Nextjs – Ein Beispielprojekt für Nextjs findest du hier.

• CDN ohne Bundler – Ein Codebeispiel findest du hier.

Kurz gesagt: Wir stellen derzeit eine minimale Vite-Vorlage bereit, aber du kannst sie erweitern oder zu anderen Frameworks wechseln – Sag uns, was und wie du baust, und wie wir die Erfahrung für deinen Anwendungsfall verbessern oder ein Beispiel bereitstellen können!

Tree-shaking zur Reduzierung der Bundle-Größe

Tree-shaking bezieht sich auf eine gängige Praxis beim Bundling von Webanwendungen (siehe MSDN docs). Es bedeutet, dass Codepfade und Features, die in deinem Code nicht verwendet werden, aus der endgültigen gebündelten Javascript-Datei(en) entfernt werden, um die Dateigröße zu reduzieren. Siehe unten zu Features, die Needle Engine enthält und wie du sie entfernen kannst:

Erstellen einer PWA

Wir unterstützen die einfache Erstellung einer Progressive Web App (PWA) direkt aus unserer Vite-Vorlage. PWAs sind Webanwendungen, die wie normale Webseiten oder Websites laden, aber Benutzerfunktionen wie Offline-Arbeit, Push-Benachrichtigungen und Zugriff auf Geräte-Hardware bieten können, die traditionell nur für native mobile Anwendungen verfügbar sind. Standardmäßig verfügen mit Needle erstellte PWAs über Offline-Unterstützung und können optional automatisch aktualisiert werden, wenn du eine neue Version deiner App veröffentlichst.

1. Installiere das Vite PWA plugin in deinem Webprojekt: npm install vite-plugin-pwa --save-dev
2. Ändere deine vite.config.js wie unten gezeigt. Stelle sicher, dass du dasselbe pwaOptions-Objekt sowohl an needlePlugins als auch an VitePWA übergibst.

import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig(async ({ command }) => {

    // Create the pwaOptions object.
    // You can edit or enter PWA settings here (e.g. change the PWA name or add icons).
    /** @type {import("vite-plugin-pwa").VitePWAOptions} */
    const pwaOptions = {};

    const { needlePlugins } = await import("@needle-tools/engine/plugins/vite/index.js");

    return {
        plugins: [
            // pass the pwaOptions object to the needlePlugins and the VitePWA function
            needlePlugins(command, needleConfig, { pwa: pwaOptions }),
            VitePWA(pwaOptions),
        ],
        // the rest of your vite config...

PWAs testen

Um deine PWA zu testen, deploye die Seite, zum Beispiel mit der DeployToFTP-Komponente. Öffne dann die deployed Seite in einem Browser und prüfe, ob die PWA-Features wie erwartet funktionieren:

• die App wird als installierbar angezeigt
• die App funktioniert offline
• die App wird von pwabuilder.com als offline-fähige PWA erkannt

PWAs verwenden Service Worker, um Ressourcen zu cachen und Offline-Unterstützung bereitzustellen. Service Worker sind während der Entwicklung etwas schwieriger zu verwenden und werden typischerweise nur für Builds aktiviert (z. B. wenn du eine DeployTo...-Komponente verwendest).

Du kannst die PWA-Unterstützung für die Entwicklung aktivieren, indem du Folgendes zum Options-Objekt in deiner vite.config.js hinzufügst.

const pwaOptions = {
  // Note: PWAs behave different in dev mode.
  // Make sure to verify the behaviour in production builds!
  devOptions: {
    enabled: true,
  }
};

Bitte beachte, dass PWAs im Entwicklungsmodus keine Offline-Nutzung unterstützen – ein Versuch kann zu unerwartetem Verhalten führen.

Automatische Aktualisierung laufender Apps

Websites zeigen normalerweise neue oder aktualisierte Inhalte beim Seiten-Refresh an.

In einigen Situationen möchtest du, dass die Seite automatisch aktualisiert und neu geladen wird, wenn eine neue Version veröffentlicht wurde – wie zum Beispiel in einem Museum, auf einer Messe, auf öffentlichen Displays oder in anderen langlebigen Szenarien.

Um automatische Updates zu aktivieren, setze die updateInterval-Eigenschaft im pwaOptions-Objekt auf eine Dauer (in Millisekunden), in der die App nach Updates suchen soll. Wenn ein Update erkannt wird, wird die Seite automatisch neu geladen.

const pwaOptions = {
  updateInterval: 15 * 60 * 1000, // 15 minutes, in milliseconds
};

Weitere PWA-Optionen

Da Needle unter der Haube das Vite PWA plugin verwendet, kannst du alle von diesem bereitgestellten Optionen und Hooks nutzen. Zum Beispiel kannst du ein teilweises Manifest mit einem benutzerdefinierten App-Titel oder einer benutzerdefinierten Themenfarbe bereitstellen:

const pwaOptions = {
  // manifest options provided here will override the defaults
  manifest: {
    name: "My App",
    short_name: "My App",
    theme_color: "#B2D464",
  }
};

Für komplexe Anforderungen wie partielles Caching, benutzerdefinierte Service Worker oder verschiedene Aktualisierungsstrategien kannst du die Option { pwa: pwaOptions } aus needlePlugins entfernen und die PWA-Funktionalität direkt über das Vite PWA plugin hinzufügen.

Zugriff auf Needle Engine und Komponenten aus externem Javascript

Code, den du exponierst, kann nach dem Bundling aus JavaScript aufgerufen werden. Dies ermöglicht den Aufbau von Viewern und anderen Anwendungen, bei denen es eine Trennung zwischen Daten gibt, die zur Bearbeitungszeit bekannt sind, und Daten, die erst zur Laufzeit bekannt sind (z. B. dynamisch geladene Dateien, vom Benutzer generierte Inhalte). Für den Zugriff auf Komponenten aus regulärem Javascript außerhalb der Engine siehe den Abschnitt Interop mit regulärem Javascript.

Anpassen des Ladebildschirms

Siehe den Abschnitt Loading Display in der Needle Engine Komponentenreferenz.

Eingebaute Stile

Die Lade-Optik von needle-engine kann einen hellen oder dunklen Skin verwenden. Um die Optik zu ändern, verwende das loading-style-Attribut auf der <needle-engine> Webkomponente. Optionen sind light und dark (Standard):

<needle-engine loading-style="light"></needle-engine>

Benutzerdefinierter Lade-Stil — PRO Feature

Bitte siehe den Abschnitt Loading Display in der Needle Engine Komponentenreferenz.

Page automatically translated using AI