バンドルとウェブフロントエンド

Needle Engineはウェブコンポーネントとして構築されています。 これは、プロジェクトに@needle-tools/engineをインストールするだけでよいことを意味します。

npm i @needle-tools/engine

そしてHTMLからこのように使用します。

<script type="module">
  import '@needle-tools/engine';
</script>
<needle-engine src="path/to/your.glb"></needle-engine>

デフォルトのViteベースのプロジェクトテンプレートを使用すると、Needle Engineはデプロイ時にウェブアプリにバンドルされます。これにより、ファイルサイズの削減と読み込み時間の最適化が保証されます。

バンドルとツリーシェイキング

バンドルとは、プロジェクトを構成するすべてのCSS、JS、その他のファイルが、ビルド時に少ない、より小さなファイルに結合されることを意味します。これにより、多数の小さなスクリプトやコンポーネントをダウンロードする代わりに、必要最小限のコードを含む1つまたは少数のファイルのみがダウンロードされるようになります。Viteのドキュメントには、ウェブアプリをバンドルすべき理由について素晴らしい説明があります: Why Bundle for Production

ツリーシェイキングは、ウェブ開発における一般的な手法で、最終的なバンドルから未使用のコードを削除してファイルサイズを削減します。これはUnityにおける「コードストリッピング」に似ています。MSDNドキュメントには、ツリーシェイキングの良い説明があります。

Vite、Vue、React、Svelte、React Three Fiber...

Needle Engineは、フレームワークの選択に偏りがありません。デフォルトのテンプレートは、一般的なvite をバンドラーとして使用しています。そこから、Vue、Svelte、Nuxt、React、React Three Fiber、その他のフレームワークを追加でき、それらの多くに対するサンプルを用意しています。他のバンドラーを統合したり、全く使用しない（プレーンなHTMLとJavaScriptのみを使用する）ことも可能です。

Needle Engineと共に使用できる、以下のような技術スタックの例をいくつか紹介します。

  • Vite + HTML — これはデフォルトのテンプレートが使用しているものです！

  • Vite + Vue — これはNeedle Tools ウェブサイトが使用しているものです！ ダウンロード可能なサンプルはこちらで見つけられます。

  • Vite + Svelte

  • Vite + SvelteKit

  • Vite + React — プロジェクトを生成する際に選択できる、Unity統合に同梱された実験的なテンプレートがあります！

  • react-three-fiber — プロジェクトを生成する際に選択できる、Unity統合に同梱された実験的なテンプレートがあります！

  • Vercel & Nextjs — Nextjsプロジェクトの例はこちらで見つけられます。

  • CDN without any bundler — コードの例はこちらで見つけられます。

要するに、現在提供しているのは最小限のViteテンプレートですが、これを拡張したり、他のフレームワークに切り替えたりすることができます。 どのような方法で構築しているか、あなたのユースケースにおけるエクスペリエンスをどのように改善できるか、または例を提供できるか、ぜひお知らせください！

ヒント

一部のフレームワークでは、needle.config.jsonにカスタム設定が必要です。こちらで詳細を確認できます。通常、baseUrlを設定する必要があります。

Unityでカスタムプロジェクトテンプレートを作成するには？

他のバンドラー、ビルドシステムを使用したり、全く使用しないなど、独自のウェブプロジェクトテンプレートを作成して共有できます。

新しいテンプレートの作成

  1. Create/Needle Engine/Project Templateを選択して、テンプレートとして使用したいフォルダにProjectTemplateを追加します。
  2. 完了です！これほどシンプルです。

プロジェクトにNpmDefがある場合（つまり、プロジェクトがローカル参照を使用している場合）、依存関係はUnityから提供されます。 パッケージをnpmに公開し、バージョン番号で参照することも可能です。

PWAの作成

私たちのViteテンプレートから、Progressive Web App (PWA) を簡単に作成することをサポートしています。 PWAは、通常のウェブページやウェブサイトのようにロードされるウェブアプリケーションですが、オフラインでの動作、プッシュ通知、デバイスハードウェアへのアクセスなど、従来ネイティブモバイルアプリケーションでのみ利用可能だったユーザー機能を提供できます。

デフォルトでは、Needleで作成されたPWAはオフラインサポートを備えており、アプリの新しいバージョンを公開したときにオプションで自動的にリフレッシュできます。

  1. ウェブプロジェクトにVite PWA pluginをインストールします: npm install vite-plugin-pwa --save-dev
  2. 以下のようにvite.config.jsを修正します。同じpwaOptionsオブジェクトをneedlePluginsとVitePWAの両方に渡すようにしてください。
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...

デフォルトですべてのアセットはキャッシュされます

デフォルトでは、ビルドフォルダ内のすべてのアセットがPWAプリキャッシュに追加されることに注意してください。多くの動的なアセットを持つ大規模なアプリケーションの場合、これは望ましい動作ではないかもしれません（YouTube PWAがユーザーがアプリを開くたびにすべてのビデオをキャッシュすることを想像してください！）。この動作をカスタマイズする方法については、その他のPWAオプションを参照してください。

PWAのテスト

PWAをテストするには、ページをデプロイします。たとえば、DeployToFTPコンポーネントを使用します。 次に、デプロイされたページをブラウザで開き、PWA機能が期待通りに動作するか確認します。

  • アプリがインストール可能として表示されるか
  • アプリがオフラインで動作するか
  • アプリがpwabuilder.comによってオフライン対応PWAとして検出されるか

PWAはService Workerを使用してリソースをキャッシュし、オフラインサポートを提供します。Service Workerは開発中に使用するのがやや難しく、通常はビルドに対してのみ有効になります（たとえば、DeployTo...コンポーネントを使用する場合）。

開発用にPWAサポートを有効にするには、vite.config.jsのoptionsオブジェクトに以下を追加します。

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

開発モードのPWAはオフライン使用をサポートしないことに注意してください。試みると予期しない動作を引き起こす可能性があります。

実行中のアプリを自動的に更新する

ウェブサイトは通常、ページをリフレッシュすると新しいコンテンツや更新されたコンテンツを表示します。

博物館、トレードショー、公共展示、またはその他の長期実行シナリオなど、新しいバージョンが公開されたときにページを自動的にリフレッシュして再ロードしたい場合があります。

自動更新を有効にするには、pwaOptionsオブジェクトのupdateIntervalプロパティに、アプリが更新をチェックすべき期間（ミリ秒単位）を設定します。更新が検出されると、ページは自動的に再ロードされます。

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

定期的な再ロードとユーザーデータ

ユーザーがフォームや再ロードによって失われる可能性のある他のデータとやり取りするアプリケーションでは、自動再ロードを使用することは推奨されません。これらのアプリケーションでは、再ロードプロンプトを表示することが推奨されます。 自動再ロードの代わりに再ロードプロンプトを実装する方法の詳細については、Vite PWA plugin documentationを参照してください。

その他のPWAオプション

Needleは内部でVite PWA pluginを使用しているため、提供されているすべてのオプションとフックを使用できます。 たとえば、カスタムのアプリタイトルやテーマカラーを持つ部分的なマニフェストを提供できます。

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

部分的なキャッシング、カスタムService Worker、または異なる更新戦略のような複雑な要件の場合、needlePluginsから{ pwa: pwaOptions }オプションを削除し、Vite PWA pluginを介して直接PWA機能を追加できます。

外部JavaScriptからのNeedle Engineとコンポーネントへのアクセス

公開したコードは、バンドル後にJavaScriptからアクセスできます。これにより、編集中に既知のデータと実行時にのみ既知のデータ（動的にロードされるファイル、ユーザー生成コンテンツなど）が分離されているビューアやその他のアプリケーションを構築できます。 エンジンの外部の通常のJavaScriptからコンポーネントにアクセスする方法については、通常のJavaScriptとの相互運用セクションを参照してください。

ローディング表示のカスタマイズ

needle engine component referenceのローディング表示セクションを参照してください。

ビルトインスタイル

Needle Engineのローディング表示は、ライトまたはダークのスキンを使用できます。 表示を変更するには、<needle-engine>ウェブコンポーネントのloading-style属性を使用します。 オプションはlightとdark（デフォルト）です。

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

カスタムローディングスタイル — PRO機能

needle engine component referenceのローディング表示セクションを参照してください。

custom loading

Page automatically translated using AI AIによる自動翻訳ページ