メインコンテンツまでスキップ

テンプレート詳細

metatellのプラグインは、企業ごとに2D UIを差し替えるための機能です。
このページでは、各テンプレートの役割と開発方法をまとめています。

📦 GitHubテンプレートリポジトリ: https://github.com/urth-inc/metatell-plugin-template

プラグインの役割と適用ポイント​

metatell本体では、次の順序でModule Federationプラグインを読み込みます。

  1. ルームのプラグイン情報を取得し、init({ remotes })でリモートを登録
  2. 各プラグインをsrc = "{versionId}/{type}"形式に変換
  3. 画面ごとの差し込みポイントでloadRemote(src)し、module.CustomXXXを描画

適用ルール（重要）​

AdditionalToolbarButton と CustomOverlay は複数適用可能です。
上記以外は単一適用です。

テンプレート一覧​

type置き換えるUI表示タイミング複数適用公開コンポーネント名
AdditionalToolbarButtonツールバー追加ボタン入室後可AdditionalToolbarButton
CustomOverlay画面固定オーバーレイ入室後可CustomOverlay
CustomEntryPanel入室前パネル入室前不可CustomEntryPanel
CustomProfileModalプロフィール編集モーダルプロフィール編集時不可CustomProfileModal
CustomLeaveButton退出ボタン・退出モーダル導線入室後不可CustomLeaveButton
CustomChatButtonチャットボタン・チャットUI入室後不可CustomChatButton
CustomMegaphoneButtonメガホンボタン入室後不可CustomMegaphoneButton
CustomWebCameraButtonWebカメラボタン入室後不可CustomWebCameraButton
CustomTutorialチュートリアル表示入室後不可CustomTutorial
CustomNearestUserProfile最寄り利用者表示入室後不可CustomNearestUserProfile
CustomExitScreen退室/エラー画面ルーム離脱時不可CustomExitScreen

共通開発フロー​

1. テンプレートを選ぶ​

git clone https://github.com/urth-inc/metatell-plugin-template.git
cd metatell-plugin-template/<テンプレート名>

2. 依存関係をインストール​

npm install

3. 開発用ローカル環境を起動​

npm run dev
  • Webpack系テンプレート: http://localhost:3004
  • CustomExitScreen（Vite）: http://localhost:5173

4. package.jsonのメタデータを設定​

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My metatell plugin"
}

5. ビルド​

npm run build

dist/plugin.zipを管理画面に登録します。
npm run dev/npm run build実行時にVERSION_IDは再生成されます（同一ID固定ではありません）。

各テンプレート詳細​

AdditionalToolbarButton​

何を置き換えるか​

標準ツールバーに、追加ボタンを挿入します。

差し込み位置​

入室後のツールバー追加領域です。

受け取るProps​

type AdditionalToolbarButtonProps = {}

開発時の注意点​

複数適用可能です。

  • エクスポート名はAdditionalToolbarButtonにしてください。

CustomOverlay​

何を置き換えるか​

画面固定のカスタムオーバーレイUIを描画します。

差し込み位置​

入室後の画面固定オーバーレイ領域です。

受け取るProps​

type CustomOverlayProps = {}

開発時の注意点​

複数適用可能です。

  • エクスポート名はCustomOverlayにしてください。

CustomEntryPanel​

何を置き換えるか​

入室前のエントリーパネル全体を置き換えます。

差し込み位置​

入室前のエントリーパネル領域です。

受け取るProps​

type CustomEntryPanelProps = {
  roomName: string | undefined
  logoUrl: string | undefined
  showJoinRoom: boolean
  isRoomFull: boolean
  onJoinRoom: () => void
  showEnterOnDevice: boolean
  onEnterOnDevice: () => void
  showSpectate: boolean
  onSpectate: () => void
  showOptions: boolean
  onOptions: () => void
  leftImage: React.ReactNode
  rightImage: React.ReactNode
  leftMessage: string
  rightMessage: string
  termsOfServiceUrl: string | undefined
  privacyPolicyUrl: string | undefined
  audioSetupContainer: React.ReactNode
}

開発時の注意点​

  • エクスポート名はCustomEntryPanelにしてください。 音声デバイス設定UIとしてaudioSetupContainerが渡されます。

CustomProfileModal​

何を置き換えるか​

プロフィール編集モーダルのUIを置き換えます。

差し込み位置​

プロフィール編集モーダル領域です。

受け取るProps​

type CustomProfileModalProps = {
  isOpen: boolean
  onClose: () => void
  displayName: string
  bio: string
  avatarId: string | undefined
  avatarThumbnailUrl: string | undefined
  selectedAvatarId: string | undefined
  selectedAvatarThumbnailUrl: string | undefined
  openAvatarSelectModal: () => void
  saveProfile: (arg: { displayName?: string; bio?: string; avatarId?: string }) => void
}

開発時の注意点​

  • エクスポート名はCustomProfileModalにしてください。
  • 既存の保存処理はsaveProfile経由で呼び出してください。

CustomLeaveButton​

何を置き換えるか​

退出ボタンと退出モーダル表示導線を置き換えます。

差し込み位置​

入室後の右側ツールバー（退出導線）です。

受け取るProps​

type CustomLeaveButtonProps = {
  destinationUrl: string
  showDefaultModal: () => void
}

開発時の注意点​

  • エクスポート名はCustomLeaveButtonにしてください。
  • 既定モーダルを使う場合はshowDefaultModalを呼び出してください。

CustomChatButton​

何を置き換えるか​

チャットボタンとチャットUI（モーダル）を置き換えます。

差し込み位置​

入室後の中央ツールバー（チャット導線）です。

受け取るProps​

type MessageGroup = {
  id: number
  type: "chat" | "join" | "entered" | "leave" | "display_name_changed" | "hub_name_changed"
  timestamp: number
  sender?: string
  senderSessionId?: string
  messages?: { id: number; body: string; timestamp: number }[]
  name?: string
  hubName?: string
  oldName?: string
  newName?: string
}

type CustomChatButtonProps = {
  toggleDefaultModal: () => void
  canSpawnMessages: boolean
  onUploadFiles: (event: React.ChangeEvent<HTMLInputElement>) => void
  sendMessage: (message: string) => void
  messageGroups: MessageGroup[]
}

開発時の注意点​

  • エクスポート名はCustomChatButtonにしてください。
  • spawnChatMessageは渡されません。

CustomMegaphoneButton​

何を置き換えるか​

メガホン機能のボタンUIを置き換えます。

差し込み位置​

入室後の中央ツールバー（メガホン導線）です。

受け取るProps​

type CustomMegaphoneButtonProps = {
  canMegaphone: boolean
  isActiveMegaphone: boolean
  muteMegaphone: () => Promise<void>
  unmuteMegaphone: () => Promise<void>
  mySessionId: string | undefined
  messageDispatch: EventTarget
  temporalMegaphone: boolean
  requestMegaphone: () => void
  grantMegaphone: () => Promise<void>
  revokeMegaphone: () => Promise<void>
  approveMegaphoneRequest: (sessionId: string) => void
  denyMegaphoneRequest: (sessionId: string) => void
}

開発時の注意点​

  • エクスポート名はCustomMegaphoneButtonにしてください。
  • 承認/却下フローの両方に対応してください。

CustomWebCameraButton​

何を置き換えるか​

Webカメラ共有ボタンを置き換えます。

差し込み位置​

入室後の中央ツールバー（Webカメラ導線）です。

受け取るProps​

type CustomWebCameraButtonProps = {
  isSharingCamera: boolean
  canShareCamera: boolean
  canShareCameraToAvatar: boolean
  stopSharingCamera: () => void
  startSharingCamera: () => void
  startSharingCameraToAvatar: () => void
}

開発時の注意点​

  • エクスポート名はCustomWebCameraButtonにしてください。
  • ロール制御ON/OFFどちらでも期待通り動作するように実装してください。

CustomTutorial​

何を置き換えるか​

入室後に表示されるチュートリアルUIを置き換えます。

差し込み位置​

入室後のチュートリアル表示領域です。

受け取るProps​

type CustomTutorialProps = {
  showMicrophone: boolean
  showMegaphone: boolean
  showVideo: boolean
  showShare: boolean
  showPlace: boolean
  showReaction: boolean
  showChat: boolean
}

開発時の注意点​

  • エクスポート名はCustomTutorialにしてください。
  • 各ボタン表示可否フラグに応じてチュートリアル内容を出し分けてください。

CustomNearestUserProfile​

何を置き換えるか​

最寄り利用者のプロフィール表示UIを置き換えます。

差し込み位置​

入室後の最寄り利用者プロフィール表示領域です。

受け取るProps​

type User = {
  sessionId: string
  displayName: string
  biography: string
  avatarThumbnailUrl: string
  distance: number
}

type CustomNearestUserProfileProps = {
  user: User | undefined
}

開発時の注意点​

  • エクスポート名はCustomNearestUserProfileにしてください。
  • userがundefinedの場合の非表示処理を実装してください。

CustomExitScreen​

何を置き換えるか​

退室・接続失敗・アクセス拒否時に表示する終了画面を置き換えます。

差し込み位置​

退室・接続失敗・アクセス拒否時の終了画面領域です。

受け取るProps​

type ExitReasonType =
  | "exited"
  | "left"
  | "closed"
  | "denied"
  | "kicked"
  | "connectError"
  | "sceneError"

type ExitScreenContentByReason = Record<
  ExitReasonType,
  {
    title: string
    message: string
    buttonLabel: string
    buttonUrl?: string
    action: "reload" | "home" | "navigate"
  }
>

type CustomExitScreenProps = {
  reason: ExitReasonType
  contentByReason: ExitScreenContentByReason
  onPrimaryAction: () => void
  logoUrl?: string
}

reason一覧​

  • exited: 退出（フォールバック）
  • left: 通常退出
  • closed: ルームクローズ
  • denied: アクセス拒否
  • kicked: 強制退出
  • connectError: 接続エラー
  • sceneError: シーン読み込みエラー

mfMeta.supportedReasonsの扱い​

mfMeta.supportedReasonsをエクスポートすると、対応しないreason時は既定UIにフォールバックされます。

開発時の注意点​

  • エクスポート名はCustomExitScreenにしてください（default exportでも問題ありません）。 CustomExitScreenテンプレートのみViteで、開発ポートは5173です。
に最終更新