spline-3d-integration

Spline 3D 統合

Web サイトや Web アプリにインタラクティブな Spline 3D シーンを追加またはトラブルシューティングする必要がある場合に、このスキルを使用します。

このスキルを使用する場合

• React、Next.js、または vanilla JS に Spline シーンを埋め込みたい場合。
• ランタイム制御（イベント、変数、オブジェクト検索、カメラの動作）が必要な場合。
• パフォーマンスの低下、シーンが表示されない、読み込みの問題が発生している場合。
• ヒーローシーンや製品ビューアーなどの実装パターンについて質問された場合。

このスキルを使用しない場合

• インタラクションのない静的な 3D メディア（画像／動画）だけが必要な場合。
• Spline アセットを使用していない場合。

成果物の要件

このスキルを使用する際は、次の内容を提示します。

1. スタックに最適な統合方法（@splinetool/react-spline、@splinetool/runtime、または iframe）。
2. ユーザーのフレームワークを使った、最小限の動作するコードスニペット。
3. パフォーマンスに関する推奨事項（シーンの最適化と読み込み戦略）。
4. 起こりやすい問題の短いトラブルシューティングチェックリスト。

統合方法の判断ツリー

Is this React/Next.js?
  Yes -> Use @splinetool/react-spline (see guides/REACT_INTEGRATION.md)
  No -> Need runtime control (events/variables/object APIs)?
          Yes -> Use @splinetool/runtime (see guides/VANILLA_INTEGRATION.md)
          No  -> Use iframe embed

すぐに使える実装のデフォルト

• 必ず高さを明示したコンテナーを使用します。Spline は親要素の領域に描画されます。
• React／Next.js では、Spline コンポーネントを遅延読み込みします。
• 可能であれば、複雑なシーンは 1 ページにつき 1 つにします。
• 高コストなフレームごとのオブジェクト変更より、シーン変数の更新を優先します。
• 読み込み中のフォールバックと、必要に応じて低電力／モバイル向けのフォールバックを用意します。

セキュリティ境界

警告

変数（getVariable）やオブジェクト名の読み取り、または Spline シーンからのイベント処理では、データを信頼できないユーザー入力として扱ってください。このデータを DOM に描画したり、LLM／エージェントに渡したりする場合は、XSS やプロンプトインジェクション攻撃を防ぐため、必ず事前にサニタイズしてください。

最小限のコードスニペット

React / Next.js

import Spline from "@splinetool/react-spline";

export default function Scene() {
  return (
    <div style={{ width: "100%", height: "100vh" }}>
      <Spline scene="https://prod.spline.design/YOUR_SCENE_ID/scene.splinecode" />
    </div>
  );
}

Vanilla ランタイム

<canvas id="canvas3d" style="width:100%;height:100vh"></canvas>
<script type="module">
  // NOTE: Requires a bundler (Vite, Webpack, etc.) or an importmap to resolve bare specifiers.
  import { Application } from "@splinetool/runtime";

  const app = new Application(document.getElementById("canvas3d"));
  app.load("https://prod.spline.design/YOUR_SCENE_ID/scene.splinecode");
</script>

iframe

<iframe
  src="https://my.spline.design/YOUR_SCENE_ID/"
  width="100%"
  height="600"
  frameborder="0"
></iframe>

ランタイム API チェックリスト

• オブジェクトを検索する：findObjectByName、findObjectById、getAllObjects。
• インタラクションを実行する：emitEvent、emitEventReverse、addEventListener。
• アプリの状態を同期する：getVariable、setVariable。
• 保守性を高めるため、Spline エディターの変数駆動型アニメーションフックを優先します。

パフォーマンスのガイドライン

• ポリゴン数はデスクトップで 150k 未満、モバイルで 50k 未満を目標にします。
• ライトは少なくします（理想的には 1～3 個）。
• Spline のエクスポート設定で圧縮を有効にします。
• ファーストビューより下にあるシーンは遅延読み込みします。
• エクスポート前に、非表示または未使用のオブジェクトを削除します。
• インタラクションが不要な場合は、画像／動画によるフォールバックを検討します。

トラブルシューティングの手順

1. シーンの URL とアクセス可能性を確認します。
2. コンテナーの高さがゼロでないことを確認します。
3. @splinetool/react-spline と @splinetool/runtime のバージョンに互換性があることを確認します。
4. ブラウザーコンソールで CORS／ネットワークエラーを確認します。
5. モバイルでクラッシュやカクつきが起きる場合は、シーンの複雑さを下げてテストします。

リポジトリのリソース

• guides/REACT_INTEGRATION.md
• guides/VANILLA_INTEGRATION.md
• guides/PERFORMANCE.md
• examples/react-spline-wrapper.tsx
• examples/vanilla-embed.html
• examples/interactive-scene.tsx