シンプルな UI プラグインを作成してインストールする

プラグインプレイグラウンドにあらかじめ用意されたファイルを使って、Welcome ウィジェットを作成し、ビューアで実行し、ボタンでカメラを東京に移動させます。その後、同じウィジェットを ZIP ファイルとしてエクスポートし、Re:Earth Visualizer にインストールして、シーンに追加します。ローカルのセットアップは不要です。

作るもの

完成した Welcome ウィジェットには短いメッセージと「Fly to Tokyo」ボタンが含まれます。ボタンをクリックすると、プラグインにメッセージが送信され、カメラが東京に移動してウィジェットのステータスメッセージが更新されます。完成したプラグインは ZIP ファイルとしてエクスポートされ、Visualizer プロジェクトにインストールされます。

前提条件

• Re:Earth Visualizer のアカウントと、少なくとも 1 つの Visualizer プロジェクト
• モダンなデスクトップブラウザ
• HTML と JavaScript の基本的な知識
• ローカルの開発ツールは不要です

ステップ 1 — プラグインプレイグラウンドを開く

プラグインプレイグラウンドは、Re:Earth Visualizer に組み込まれたブラウザベースのエディタです。ローカルに何もインストールせずに、プラグインを書いて、プレビューし、エクスポートできます。

1. Re:Earth Visualizer を開いてサインインします。
2. 左サイドバーの エディター → プラグイン に移動します。
3. プラグインプレイグラウンド をクリックしてエディターを開きます。
4. ファイルツリーの Custom セクションで My Plugin を選択します。すでに reearth.yml マニフェストとサンプルエクステンションファイルが含まれています。既存のマニフェストとウィジェットファイルを編集します。

ステップ 2 — プラグインマニフェストを編集する

reearth.yml をクリックし、内容を以下に置き換えます：

id: welcome-widget-plugin
name: Welcome Widget
version: 1.0.0
extensions:
  - id: demo-widget
    type: widget
    name: Welcome
    description: A simple welcome widget
    widgetLayout:
      defaultLocation:
        zone: outer
        section: left
        area: top

Re:Earth プラグインには 1 つ以上のエクステンションを含めることができます。このチュートリアルでは、ウィジェットエクステンション — Visualizer のメインビューに表示されるユーザーインターフェースコンポーネント — を作成します。その位置はウィジェットアラインシステムで調整できます。マニフェストがエクステンションを宣言し、対応する JavaScript ファイルがその UI と動作を提供します。ここでは、エクステンション ID demo-widget が demo-widget.js に対応します。この名前は正確に一致させてください。

プラグインの構造とエクステンションタイプの違いについて詳しく学ぶ。

マニフェストに Welcome という名前のウィジェットが宣言されました。エクステンション ID demo-widget は既存のファイル demo-widget.js と一致しています。ウィジェットが正しく動作するよう、これらの名前は正確に一致させてください。

ステップ 3 — ウィジェットのコードを編集する

demo-widget.js を選択してコードパネルで開きます。JavaScript エディターでコードを編集してください。ライブプレイグラウンドでは、このファイルの HTML エディター コントロールが無効になっています。

その内容を以下に置き換えます：

const html = `
  <div style="font-family: sans-serif; padding: 16px; background: #1e1e2f; color: white; border-radius: 8px; width: 220px;">
    <h2 style="margin: 0 0 8px;">👋 Welcome</h2>
    <p id="status" style="margin: 0 0 12px; font-size: 13px;">Click the button to fly to Tokyo.</p>
    <button id="flyBtn" style="background: #4f8cff; border: none; color: white; padding: 6px 12px; border-radius: 4px; cursor: pointer;">Fly to Tokyo</button>
    <script>
      document.getElementById('flyBtn').addEventListener('click', () => {
        parent.postMessage({ action: 'flyToTokyo' }, '*');
      });
      window.addEventListener('message', (e) => {
        if (e.source !== parent) return;
        if (!e.data || e.data.action !== 'flying') return;
        document.getElementById('status').textContent = e.data.text;
      });
    <\/script>
  </div>
`;

reearth.ui.show(html, { width: 250, height: 150 });

reearth.extension.on("message", (msg) => {
  if (msg && msg.action === "flyToTokyo") {
    reearth.camera.flyTo(
      { lat: 35.6764, lng: 139.65, height: 8000, heading: 0, pitch: -1.3, roll: 0 },
      { duration: 3 }
    );
    reearth.ui.postMessage({ action: "flying", text: "Flying to Tokyo… 🗼" });
  }
});

ウィジェットコードの仕組み

プラグイン API はエクステンション側のグローバル reearth オブジェクトを通じて利用できます。ウィジェット UI は iframe 内で別々に動作するため、2 つのサイドはメッセージでやり取りします：

1. reearth.ui.show(...) が HTML をウィジェットの iframe として表示します。
2. ボタンハンドラーは iframe 内で実行されます。iframe から Plugin API を直接呼び出せないため、parent.postMessage(...) が flyToTokyo アクションをエクステンションに送信します。
3. reearth.extension.on("message", ...) がエクステンション側でアクションを受信します。
4. reearth.camera.flyTo(...) が Visualizer カメラを東京に移動します。
5. reearth.ui.postMessage(...) が新しいステータスを iframe に送り返し、window.addEventListener("message", ...) がテキストを更新します。

詳しくはプラグインシステムの仕組みをご覧ください。

ステップ 4 — プレイグラウンドで実行してテストする

1. プレイグラウンドのツールバーで Run（三角形の再生ボタン）をクリックします。
2. プレイグラウンドのビューアに Welcome カードが表示されることを確認します。
3. Fly to Tokyo をクリックすると、カメラが東京にアニメーションし、ステータステキストが「Flying to Tokyo… 🗼」に変わるはずです。

コードを変更した後は、Run を再度クリックして最新バージョンをビューアに読み込んでください。

ノート

ウィジェットが表示されない場合は、マニフェストのエクステンション id が demo-widget であり、JavaScript ファイルの名前が同じ（demo-widget.js）であることを確認してください。

ステップ 5 — プラグインをエクスポートする

1. プレイグラウンドで My Plugin を選択します。
2. Export（プラグインパネル上部のダウンロードアイコン）をクリックします。
3. ダウンロードした ZIP ファイルを解凍せずに保存します。

ZIP にはルートに reearth.yml と demo-widget.js が含まれており、これが Re:Earth Visualizer が想定する正確な構造です。Re:Earth はプラグイン ZIP ファイルを最大 10 MB まで受け付けます。

ステップ 6 — Re:Earth Visualizer に ZIP をインストールする

1. Visualizer プロジェクトを開きます。
2. プロジェクト設定 を開き、プラグイン を選択します。
3. 個人インストール を開きます。
4. PC から ZIP ファイルをアップロード を選択します。
5. プレイグラウンドからエクスポートした ZIP を選択します。
6. 成功通知が表示されるまで待ちます。

注意

ID welcome-widget-plugin のプラグインがすでにインストールされている場合は、この ZIP をアップロードする前にそのコピーをアンインストールしてください。

ステップ 7 — ウィジェットをシーンに追加する

1. Visualizer エディターに戻ります。
2. ウィジェット を開きます。
3. ウィジェットを追加 をクリックします。
4. Welcome を選択します。
5. Fly to Tokyo をクリックして、カメラが動くことを確認します。

プラグインのフルワークフローが完了しました：編集 → プレビュー → エクスポート → インストール → 使用。

トラブルシューティング

インストールが失敗する

• reearth.yml のインデントとスペルを確認してください。
• プラグイン ID が 100 文字以内で、英数字・_・- のみを使用し、reearth を含まないことを確認してください。
• 同じ ID のプラグインがすでにインストールされていないことを確認してください。
• reearth.yml がプラグインのルートにあり、ZIP に余分な外側のディレクトリが含まれていないことを確認してください。
• ZIP が壊れている可能性がある場合は、再度エクスポートしてください。

有効にしてもウィジェットが表示されない

• マニフェストのエクステンション ID が demo-widget であることを確認してください。
• エクスポートされた JavaScript ファイルが demo-widget.js であることを確認してください。
• シーンが保存されていることを確認してください。
• ブラウザの開発者ツールを開いてコンソールのエラーを確認してください。

カメラが動かない

• iframe が parent.postMessage(...) でメッセージを送信していることを確認してください。
• プラグインが reearth.extension.on("message", ...) でリッスンしていることを確認してください。
• 両サイドで同じアクション名 flyToTokyo を使用していることを確認してください。

ステータステキストが更新されない

• <script> タグ内の window.addEventListener('message', ...) は e.source !== parent のメッセージをフィルタリングします。
• プレイグラウンドのプレビューではこのチェックは自動的に通過します。デプロイされたシーンでも同様に動作します。プラグイン iframe の親は常に Visualizer ホストだからです。

マニフェストと JS ファイル名が一致しない

• reearth.yml のエクステンション id は、JS ファイル名（.js なし）と完全に一致する必要があります。demo-widget → demo-widget.js。

完了チェックリスト

• Run をクリックすると Welcome ウィジェットがプレイグラウンドに表示される
• ボタンをクリックするとカメラが東京に向かって動き始める
• プラグインが ZIP ファイルとしてエクスポートされる
• ZIP が正常にインストールされる
• Welcome ウィジェットが Visualizer シーンに追加できる