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

API リファレンス

@xrift/world-components で提供されるコンポーネント、フック、定数の一覧です。ワールド開発だけでなくアイテム開発からも利用できます(SpawnPoint / DevEnvironment / useSpawnPoint などワールド専用のものは各項目に注記しています)。

コンポーネント​

Interactable​

クリック/インタラクト可能なオブジェクトを作成します。

import { Interactable } from '@xrift/world-components';

<Interactable id="my-button" onInteract={() => console.log('clicked!')}>
<mesh>
<boxGeometry args={[1, 1, 1]} />
<meshStandardMaterial color="hotpink" />
</mesh>
</Interactable>

Props​

PropTypeDefaultDescription
idstring-一意の識別子(必須)
type'button'-インタラクションタイプ
onInteract(id: string) => void-インタラクト時のコールバック(IDが渡される)
interactionTextstring-ホバー時に表示するテキスト
enabledbooleantrueインタラクションの有効/無効
childrenReactNode-インタラクト対象のオブジェクト

Grabbable​

オブジェクトを「掴める」と宣言するラッパーコンポーネントです。Interactable と同じく、囲んだ対象を明示的にオプトインさせます。プレイヤーは掴んだオブジェクトを手に持って運び、任意の位置に置くことができます。

配下のメッシュを LAYERS.GRABBABLE(レイヤー14)に載せ、掴む土台(狙う・手に持つ・置く)はプラットフォーム側が担います。開発時は DevEnvironment に同梱のシステムで動作確認できます。

掴んでいる様子と離した位置は、プラットフォームがインスタンスの全員に共有します(sync、既定は true)。ワールド側で state を持たなくても、離した位置に留まり、後から入った人にも同じ位置で見えます。

import { Grabbable } from '@xrift/world-components';

function GrabbableBall() {
return (
<Grabbable
id="ball"
transform={{ position: { x: 2, y: 0.5, z: -2 }, rotation: { x: 0, y: 0, z: 0 } }}
>
{/* 子はローカル座標(原点基準)で書く */}
<mesh>
<sphereGeometry args={[0.3]} />
<meshStandardMaterial color="gold" />
</mesh>
</Grabbable>
);
}

transform は最初の位置です。誰かが動かした後は共有している位置が使われますが、ワールドが transform を変えたとき(初期位置に戻すボタンなど)は transform のほうが使われます。

transform と onMove の座標は、Grabbable を置いた親のローカル空間(通常の position prop と同じ)で扱われます。変形された親グループの下にネストしても内部でワールド座標へ変換されるため、離した位置がズレることはありません。

Props​

PropTypeDefaultDescription
idstring-一意の識別子(必須)。インスタンスの全員で同じ物を指すのに使われる
transformGrabbableTransform-対象の姿勢(必須)。親のローカル座標で指定し、ルート group に適用される(子は原点基準で書く)
onMove(transform: GrabResultTransform) => void-離した(確定)ときに新しい姿勢を受け取る。transform と同じ親ローカル座標で返る。sync={false} のときは state に反映して transform を更新する
syncbooleantrue掴んでいる様子と離した位置をインスタンスの全員に共有するか。自分の画面だけで動かしたい物は false にする
onUseStart(event: GrabUseEvent) => void-掴んでいる間に「使う」を押したときに呼ばれる(銃を撃つ・棒で殴る・ため始めるなど)。持っている本人の画面だけで呼ばれる
onUseEnd(event: GrabUseEvent) => void-「使う」を離したときに呼ばれる。押している途中で置いた・物が消えたときなどにも必ず呼ばれる
onGrab(event: GrabHoldEvent) => void-誰かが持ち上げたときに呼ばれる。自分・ほかの人のどちらでも、全員の画面で呼ばれる
onRelease(event: GrabHoldEvent) => void-手から離れたとき(置いた・やめた・持っていた人が退室した)に呼ばれる。全員の画面で呼ばれ、置いたときは onMove の後になる
enabledbooleantrue掴めるかどうか(false で一時的に無効化)
childrenReactNode-掴む対象のオブジェクト(ローカル座標で書く・必須)
sync= のとき

sync={false} の物は、ほかの人には掴んでいる様子も離した位置も見えません。位置はこれまでどおりワールド側で state に持ち、onMove で transform を更新してください。

const [transform, setTransform] = useState<GrabbableTransform>(INITIAL);

<Grabbable
id="my-cup"
sync={false}
transform={transform}
onMove={(next) => setTransform((prev) => ({ ...prev, ...next }))}
>
...
</Grabbable>

掴んでいる物を「使う」​

onUseStart / onUseEnd を書くと、掴んでいる間の操作で好きな動作を仕込めます。押したときと離したときの両方を受け取れるので、連射や「ためて放す」も作れます。物を持っている間は、インタラクトは動きません。

import { Grabbable, type GrabResultTransform, useInstanceEvent } from '@xrift/world-components';

function Gun() {
// ほかの人の画面にも弾を見せる(送った本人には届かないので、自分の画面には直接出す)
const emitShot = useInstanceEvent<{ from: GrabResultTransform['position'] }>('gun-shot', ({ payload }) => {
spawnBullet(payload.from);
});

return (
<Grabbable
id="gun"
transform={INITIAL}
onUseStart={({ transform }) => {
spawnBullet(transform.position);
emitShot({ from: transform.position });
}}
>
<GunModel />
</Grabbable>
);
}
  • 呼ばれるのは持っている本人の画面だけです。ほかの人に見せたい結果(弾・音・当たり)は、useInstanceEvent などでワールド側から送ってください
  • 引数の transform は使った瞬間の持っている物の姿勢で、transform / onMove と同じ親のローカル座標です。hand は使った手('left' / 'right'。PC・スマホは 'right')です
  • 押している途中で置いた・持ち替えた・物が消えた・カメラモードに入ったときも onUseEnd が呼ばれます。連射などは onUseEnd で止めれば、止まらなくなることはありません
interface GrabUseEvent {
hand: 'left' | 'right';
transform: GrabResultTransform;
}

GrabbableTransform / GrabResultTransform​

interface GrabbableTransform {
position: { x: number; y: number; z: number }; // 親のローカル座標(通常の position prop と同じ)
rotation: { x: number; y: number; z: number }; // オイラー角(ラジアン)
scale?: number; // 均一スケール(省略時は 1)
}

interface GrabResultTransform {
position: { x: number; y: number; z: number };
rotation: { x: number; y: number; z: number };
}

持ち上げた・離したとき​

持っている間は、children そのものが持っている人の手元へ動きます(コピーは作りません)。持ち上げたときと手から離れたときに onGrab / onRelease が呼ばれるので、持っている間だけ見た目や動きを変えられます。

子に物理(RigidBody など)を含む場合は、onGrab で当たり判定を外し、onRelease で戻してください。外さないと、持っている間も当たり判定が残ります。

function Crate() {
const [isHeld, setIsHeld] = useState(false);
const handleGrab = useCallback(() => setIsHeld(true), []);
const handleRelease = useCallback(() => setIsHeld(false), []);

return (
<Grabbable id="crate" transform={INITIAL} onGrab={handleGrab} onRelease={handleRelease}>
<mesh>
<boxGeometry args={[0.5, 0.5, 0.5]} />
<meshStandardMaterial color="#a2845e" />
</mesh>
{/* 見た目は残し、当たり判定だけ持っている間は外す */}
{!isHeld && (
<RigidBody type="fixed" colliders={false}>
<CuboidCollider args={[0.25, 0.25, 0.25]} />
</RigidBody>
)}
</Grabbable>
);
}
  • isMine は自分が持っている(持っていた)かです。音を鳴らすなど、持っている本人だけにしたい動作に使えます
  • 持っている人が入れ替わったときは、onRelease の後に onGrab が呼ばれます
interface GrabHoldEvent {
isMine: boolean;
}
操作方法
  • PC: 中央のクロスヘアで狙って G で右手に持ち、もう一度 G でいまの位置に置きます。持っている間のクリックが「使う」です。Esc やタブの切り替えでポインターロックが外れても、持ったままです
  • スマートフォン・タブレット: クロスヘアを掴める物に合わせると、インタラクトボタンの上に「掴む」ボタンが出ます。押すと持ち、「離す」に変わったボタンでいまの位置に置きます。持っている間はインタラクトボタンが「使う」ボタンに変わります(使う動作の無い物では薄く表示)
  • VR: グリップを握ると、手で触れている物を掴みます。触れていなければレイの先の物を掴みます。離すと置きます。持っている手のトリガーが「使う」です(もう片方の手のトリガーはこれまでどおりインタラクト)。レイで掴んだ物は右スティックの上下で遠ざけ・近づけます
  • ほかの人が持っている物は掴めません

DevEnvironment でも同じ PC の操作で動作確認できます(@xrift/world-components 0.61.1 以降)。

0.61.0 以降

onMove の省略と sync は @xrift/world-components 0.61.0 以降で使えます。onUseStart / onUseEnd は 0.62.0 以降、onGrab / onRelease は 0.64.0 以降です。0.64.0 からは持っている間に children そのものが動くので、renderGhost は使われません(渡しても無視されます)。


Seat​

オブジェクトを「座れる」と宣言するラッパーコンポーネントです。Interactable と同じく、囲んだ対象を明示的にオプトインさせます。プレイヤーが座ると、視点・姿勢・体の向きが座席に追従し、Space(VR は A ボタン)で降ります。

Seat は group として置きます。原点が座面(腰を置く点)、前方が -Z です。子は座面を原点としたローカル座標で書きます。

座面の姿勢は Seat を置いた場所のワールド行列から毎フレーム求められます。そのため、動く乗り物・回転台・傾いたグループの下にネストしても、プレイヤーはそのまま追従します。作者は置くだけで、姿勢を自分で渡す必要はありません。

import { Seat } from '@xrift/world-components';

function Stool() {
const height = 0.45;

return (
// 座面の高さに Seat を置く
<Seat id="stool-1" position={[2, height, -3]} rotation={[0, Math.PI / 2, 0]}>
{/* 子は座面が原点。箱は半分ぶん下げて描く */}
<mesh position={[0, -height / 2, 0]}>
<boxGeometry args={[0.5, height, 0.5]} />
<meshStandardMaterial color="saddlebrown" />
</mesh>
</Seat>
);
}

Props​

position / rotation など group のプロパティをそのまま指定できます(scale を除く。下記参照)。

PropTypeDefaultDescription
idstring-一意の識別子(必須)
exitOffsetSeatExitOffset{ forward: 0.6, right: 0, up: 0 }降車位置。座席から見た向き・ワールドのメートル
interactionTextstring'座る'狙ったときに表示するテキスト
enabledbooleantrue座れるかどうか(false で一時的に無効化。他の人が座っている間は自動で無効)
onEnter(occupant: SeatOccupant) => void-誰かが座ったときに呼ばれる(自分・他人の両方)
onLeave(occupant: SeatOccupant) => void-誰かが降りたときに呼ばれる(自分・他人の両方)
driverbooleanfalse囲んでいる Vehicle の運転席にする(0.52.0〜)
onControlInput(input: SeatControlInput, delta: number) => void-操縦入力。乗り物ではない座席(砲台・回転椅子など)で使う
childrenReactNode-座る対象のオブジェクト(座面を原点としたローカル座標で書く・必須)

SeatOccupant​

interface SeatOccupant {
id: string; // プレイヤーの userId
isLocalUser: boolean; // 自分かどうか
}

表示名やアイコンは持ちません。必要なら useUsers() から id で引いてください(退席後は取れなくなります)。

操縦入力を受け取る(onControlInput)​

乗り物を作るなら Vehicle を使ってください(後述)。onControlInput は、砲台・回転椅子・クレーンのように「操縦入力は欲しいが、動かす乗り物は持たない」座席のためのものです。自分がその席に座っている間だけ、毎フレーム届きます。

<Seat
id="turret-1"
position={[0, 0.5, 0]}
onControlInput={(input, delta) => {
// 砲身だけ回す
barrelYaw.current -= input.right * TURN_RATE * delta;
}}
>
{/* ... */}
</Seat>

SeatControlInput​

interface SeatControlInput {
forward: number; // 前後。前が +1、後ろが -1(キーボードなら W / S)
right: number; // 左右。右が +1、左が -1(キーボードなら D / A)
}

渡されるのは「どれだけ動くか」ではなく**「どの向きに動かしたいか」**です。right を旋回(ハンドル)と解釈するか横滑りと解釈するかは、乗り物側が決めます。

生のキーイベントとの違い

window.addEventListener('keydown') で乗り物を作ることもできますが、onControlInput には3つの利点があります。

  • VR・モバイルでも同じ形で届く(サムスティック・仮想ジョイスティック)
  • 運転者だけに限定される。生のキーだと、乗っていない人が W を押しても自分の画面で乗り物が動いてしまい、他の人と位置がずれます
  • プレイヤーの移動と喧嘩しない(着席中は WASD が歩行に使われません)
動かすのは運転者のクライアントだけ

onControlInput(Vehicle なら onDrive)が呼ばれるのは運転者の画面だけです。全員で物理を回して一致させる作りにはなっていません。

そのため、状態は useInstanceState などで同期せず、運転者のローカル状態として持つのが正しいです。Vehicle を使っていれば姿勢は自動で同期されるので、二重管理になります。

SeatExitOffset​

interface SeatExitOffset {
forward?: number; // 前方(-Z 側)へ。既定 0.6
right?: number; // 右へ。既定 0
up?: number; // ワールド上方向へ。既定 0
}

forward / right は座席の水平方向の向き(yaw)だけで回ります。up はワールドの上方向です。傾いた乗り物から降りるときに「座席から見た上」へ出すと、宙返り中に地面へめり込むためです。

テーブル付きの椅子など、前方に降りられない座席で使います。

{/* 右側から降りる */}
<Seat id="booth-seat" exitOffset={{ forward: 0, right: 0.7 }}>
{/* ... */}
</Seat>
座面の高さと子の位置

Seat の原点は座面です。床に置いた箱を座席にする場合、Seat 自体を座面の高さに置き、子の箱をそこから下げて描きます。原点を床に合わせると、プレイヤーが床にめり込んで座ります。

scale は指定できません

座面は位置と向きだけで決まり、着席時の腰・目線の高さはプレイヤーのアバターの実寸から決まるため、座席を拡大しても意味がありません。見た目を大きくしたい場合は children 側を拡大してください。

親グループを拡大している場合、座面の位置と向きは正しく求まりますが、exitOffset の距離は拡大されません(常にワールドのメートル)。

占有

同じ座席に他のプレイヤーが座っている間は自動的に enabled={false} 相当になり、「座る」のプロンプトが出ません。ほぼ同時に座った場合は両者が座れることがあります(見た目が重なるだけで、状態は壊れません)。

開発環境で座れます(0.53.0〜)

DevEnvironment には単独プレイヤー用の座席システムが入っているので、npm run dev のまま座って試せます。座席を狙ってクリックで着席、Space で降車します。Vehicle の運転席に座れば WASD で操縦できます。多人数での見え方や同期の確認は XRift 上で行ってください。


Vehicle​

乗り物です。中に Seat を置き、ひとつに driver を付けると運転できるようになります。

姿勢を所有するのは Vehicle です。 作者は onDrive で「どう動かしたいか」だけを書けばよく、同期は意識しなくて構いません。

  • 運転者のクライアント: onDrive の結果で動き、その姿勢が同期に流れる
  • それ以外のクライアント: onDrive は呼ばれず、届いた姿勢が当たる

車体ごと動くので、空いている同乗席も正しい位置に来ます。流れる姿勢も1台につき1本です。

import { Seat, Vehicle } from '@xrift/world-components';

const SPEED = 3; // m/s
const TURN_RATE = 1.8; // rad/s

function Cart() {
return (
<Vehicle
id="cart-1"
position={[0, 0, -5]}
onDrive={(input, delta, vehicle) => {
// 車体の前方へ進む。傾いていれば坂に沿う
vehicle.translateZ(-input.forward * SPEED * delta);
// 今の向きから相対に回る
vehicle.rotateY(-input.right * TURN_RATE * delta);
}}
>
{/* 車体(乗り物のローカル座標で書く) */}
<mesh position={[0, 0.25, 0]}>
<boxGeometry args={[1.2, 0.3, 2]} />
<meshStandardMaterial color="tomato" />
</mesh>

{/* 運転席 */}
<Seat id="cart-1-driver" driver position={[0, 0.45, -0.35]} exitOffset={{ forward: 0, right: -1.2 }}>
<mesh><boxGeometry args={[0.5, 0.1, 0.5]} /><meshStandardMaterial color="steelblue" /></mesh>
</Seat>

{/* 同乗席。運転はできないが車体と一緒に動く */}
<Seat id="cart-1-back" position={[0, 0.45, 0.55]} exitOffset={{ forward: 0, right: 1.2 }}>
<mesh><boxGeometry args={[0.5, 0.1, 0.5]} /><meshStandardMaterial color="seagreen" /></mesh>
</Seat>
</Vehicle>
);
}
Prop型既定値説明
idstring-乗り物の一意な ID(必須)
onDrive(input: SeatControlInput, delta: number, vehicle: THREE.Group) => void-乗り物を動かす。自分が運転席に座っている間だけ毎フレーム呼ばれる

position や rotation などの group のプロパティもそのまま渡せます。

vehicle(onDrive の第3引数)​

three.js の Group そのものです。書き換えるとそのまま乗り物が動きます。

  • vehicle.rotateY(rad) — 旋回
  • vehicle.translateZ(-distance) — 車体の前方へ前進(傾いていれば坂に沿う)
  • vehicle.quaternion — 直接いじれば坂・バンク・宙返りも表現できる
坂道は translateZ に任せる

position.x / position.z に「向きから求めた成分」を足す書き方だと傾きが捨てられ、坂で浮いたり埋まったりします。translateZ は車体の前方軸に沿って動くので、坂への追従が何もしなくても付いてきます。

props で動かさないこと

position / rotation は初期位置・初期の向きです。走り出したあとの姿勢は Vehicle が持ちます(運転者のクライアントでは onDrive、それ以外では届いた姿勢)。変化する値を position に渡すと、そのどちらかと喧嘩します。

driver は Vehicle の中だけ

Vehicle の外の Seat に driver を付けても運転席にはならず、普通の椅子として扱われます(開発時は console に警告が出ます)。

停めた場所は覚えられます

運転者が降りたあとの位置はインスタンスに残るので、後から入室した人にも「停まっている場所」が見えます。初期位置に戻って見えることはありません。

0.52.0 以降

Vehicle と Seat の driver は @xrift/world-components 0.52.0 以降で使えます。


Mirror​

リアルタイム反射面を作成します。

import { Mirror } from '@xrift/world-components';

<Mirror position={[0, 1, -5]} />

Props​

PropTypeDefaultDescription
position[number, number, number]-位置
rotation[number, number, number]-回転
size[number, number]-サイズ
colornumber-色(数値形式、例: 0xb5b5b5)
textureResolutionnumber-テクスチャ解像度
lodDistancenumber10LOD切り替え距離(この距離より遠いとき低解像度に切り替え)

VideoScreen​

同期された動画再生を行うスクリーンを作成します。

import { VideoScreen } from '@xrift/world-components';

<VideoScreen src="/videos/intro.mp4" position={[0, 2, -3]} />

VideoPlayer​

VideoScreen をベースにしたUIコントロール付きのビデオプレイヤーです。再生/停止ボタン、プログレスバー、音量バーなどVR対応のコントロールUIを備えています。

import { VideoPlayer } from '@xrift/world-components';

<VideoPlayer
id="my-video"
url="https://example.com/video.mp4"
position={[0, 2, -5]}
width={4}
/>

Props​

PropTypeDefaultDescription
idstring-スクリーンの一意なID(必須)
position[number, number, number][0, 2, -5]スクリーンの位置
rotation[number, number, number][0, 0, 0]スクリーンの回転
widthnumber4スクリーンの幅(高さは16:9で自動計算)
urlstring-動画のURL(省略可)
playingbooleantrue初期再生状態
volumenumber1初期音量(0〜1)
sync'global' | 'local''global'同期モード

機能​

  • URL入力ボタン: 🔗 アイコンをクリックするとURL入力オーバーレイが表示され、動画ソースを動的に切り替え可能
  • 再生/停止ボタン: ▶/|| アイコンで再生状態を切り替え
  • プログレスバー: 20セグメントに分割された進捗バー。クリックで動画の最初に戻る
  • 音量バー: 0-100%を10刻みで調整。🔈/🔇アイコンでミュート状態を表示
  • VR対応: Interactable を使用したVRコントローラー操作に対応
同期モード

sync プロパティで同期モードを選択できます:

  • 'global': 全ユーザー間で再生状態を同期(デフォルト)
  • 'local': 各ユーザーが独立して再生を制御

LiveVideoPlayer​

HLS/DASH などのライブストリーミング再生に対応したビデオプレイヤーです。VideoPlayer と同様のUIコントロールを備えつつ、ライブ配信向けに最適化されています。

import { LiveVideoPlayer } from '@xrift/world-components';

<LiveVideoPlayer
id="my-live"
url="https://example.com/live/stream.m3u8"
position={[0, 2, -5]}
width={4}
/>

Props​

PropTypeDefaultDescription
idstring-スクリーンの一意なID(必須)
position[number, number, number][0, 2, -5]スクリーンの位置
rotation[number, number, number][0, 0, 0]スクリーンの回転
widthnumber4スクリーンの幅(高さは16:9で自動計算)
urlstring-ストリームのURL(HLS/DASH対応)
playingbooleanfalse初期再生状態
volumenumber1初期音量(0〜1)
sync'global' | 'local''global'同期モード

機能​

  • URL入力ボタン: 🔗 アイコンをクリックするとURL入力オーバーレイが表示され、ストリームソースを動的に切り替え可能
  • 再生/停止ボタン: ▶/|| アイコンで再生状態を切り替え
  • 音量バー: 0-100%を10刻みで調整。🔈/🔇アイコンでミュート状態を表示
  • VR対応: Interactable を使用したVRコントローラー操作に対応
VideoPlayer との違い

LiveVideoPlayer はライブストリーミング向けに設計されているため、プログレスバー(シーク機能)がありません。録画済み動画の再生には VideoPlayer を使用してください。


ScreenShareDisplay​

画面共有の映像を3D空間内にスクリーンとして表示します。ScreenShareContext から映像と状態を取得します。

import { ScreenShareDisplay } from '@xrift/world-components';

<ScreenShareDisplay id="screen-1" position={[0, 2, -5]} />

Props​

PropTypeDefaultDescription
idstring-スクリーンの一意なID(必須)
position[number, number, number][0, 0, 0]スクリーンの位置
rotation[number, number, number][0, 0, 0]スクリーンの回転
widthnumber4スクリーンの幅(高さは16:9で自動計算)
targetFpsnumber-テクスチャ更新のターゲットFPS
placeholderImageUrlstring-未共有時に表示するプレースホルダー画像のURL
アスペクト比の維持

映像のアスペクト比は自動的に維持されます。16:9以外の映像でも黒帯が入り正しく表示されます。

プレースホルダー画像

placeholderImageUrl を指定すると、画面共有していない間、指定した画像をスクリーンに表示できます。画像はスクリーン内に収まるように表示され(contain)、読み込みに失敗した場合は背景色とガイドテキストの表示にフォールバックします。

画像はWebGLテクスチャとして読み込むため、CORS を許可している画像URLを指定してください(xrift にアップロードした画像はそのまま使えます)。

制限事項

共有できる画面はワールドにつき1つまでです。ScreenShareDisplay を複数配置することは可能ですが、すべて同じ画面が表示されます。


SpawnPoint​

ワールド内でプレイヤーが出現する地点を指定します。

ワールド専用

SpawnPoint はワールドレベルのスポーン位置を設定するコンポーネントです。アイテム内で使用することは想定されていません。

import { SpawnPoint } from '@xrift/world-components';

<SpawnPoint />
<SpawnPoint position={[0, 0, 5]} yaw={180} />

Props​

PropTypeDefaultDescription
position[number, number, number][0, 0, 0]スポーン位置
yawnumber0スポーン時の向き(度数法 0-360)
開発時ヘルパー

開発環境では、半透明の円柱(下から上にかけて透明度が増すグラデーション)と矢印でスポーン位置と方向を視覚化します。本番ビルドではヘルパーは表示されません。

SpawnPoint ヘルパー

複数のSpawnPoint

複数の SpawnPoint を配置した場合、最後に設定されたものが有効になります。


TextInput​

3D空間内でテキスト入力を可能にするコンポーネントです。children方式で外観を自由にカスタマイズできます。

import { TextInput } from '@xrift/world-components';

<TextInput
id="my-input"
value={inputValue}
onSubmit={handleSubmit}
placeholder="テキストを入力..."
>
<mesh>
<boxGeometry args={[1, 0.5, 0.1]} />
<meshStandardMaterial color="#333" />
</mesh>
</TextInput>

Props​

PropTypeDefaultDescription
idstring-入力フィールドの一意なID(必須)
childrenReactNode-3Dオブジェクト(外観)(必須)
placeholderstring-プレースホルダーテキスト
maxLengthnumber-最大文字数
valuestring-現在の値
onSubmit(value: string) => void-入力完了時のコールバック
interactionTextstring'クリックして入力'インタラクション時に表示するテキスト
disabledbooleanfalse入力を無効にするか

仕組み​

TextInput コンポーネントは以下のアーキテクチャで動作します:

  1. TextInput: children として渡された3Dオブジェクトをクリック可能な入力フィールドとして表示
  2. オーバーレイ入力: クリック時に2Dのテキスト入力UIがオーバーレイとして表示され、実際の入力を受け付けます
  3. XRiftContext連携: world-componentsはXRiftContext経由でオーバーレイ表示をリクエストします
外観のカスタマイズ

children に任意の3Dオブジェクトを渡すことで、入力フィールドの外観を自由にカスタマイズできます。ボタン風のデザインや、ワールドの世界観に合わせた見た目を実現できます。

関連するContext/Hook

プラットフォーム側では以下のAPIを使用してTextInputの動作を実装しています:

  • TextInputContext
  • useTextInputContext
  • TextInputContextValue
  • TextInputRequest

TagBoard​

ユーザーが選択したタグをローカル/グローバルに扱い、ボードUI(TagSelector)と各ユーザー頭上へのタグ表示(TagDisplay)を提供するコンポーネントです。

import { TagBoard } from '@xrift/world-components';

<TagBoard
instanceStateKey="main-tag-board"
position={[0, 1.5, -3]}
/>

Props​

PropTypeDefaultDescription
tagsTag[]デフォルトタグ一覧表示・選択対象のタグ
columnsnumber3表示列数
titlestring"タグ選択"タイトル文言
instanceStateKeystring-インスタンス状態のキー(必須、複数ボード設置時の識別用)
position[number, number, number][0, 0, 0]ボードの位置
rotation[number, number, number][0, 0, 0]ボードの回転
scalenumber1全体スケール

Tag 型定義​

interface Tag {
id: string; // タグの一意識別子
label: string; // 表示ラベル
color: string; // 色(HEX形式)
}

デフォルトタグ一覧​

tags プロパティを省略した場合、以下のタグが使用されます:

[
{ color: "#2ECC71", id: "want-talk", label: "話したい" },
{ color: "#3498DB", id: "want-listen", label: "聞きたい" },
{ color: "#95A5A6", id: "silent", label: "無言" },
{ color: "#1ABC9C", id: "developer", label: "開発者" },
{ color: "#2980B9", id: "student", label: "学生" },
{ color: "#F1C40F", id: "beginner", label: "初心者" },
{ color: "#9B59B6", id: "dont-know", label: "なんもわからん" },
{ color: "#8BC34A", id: "working", label: "作業中" },
{ color: "#BF7B41", id: "away", label: "離席中" },
{ color: "#FF9800", id: "cat", label: "ねこ" },
]

使用例​

カスタムタグを使用​
import { TagBoard, type Tag } from '@xrift/world-components';

const customTags: Tag[] = [
{ id: "frontend", label: "フロントエンド", color: "#61DAFB" },
{ id: "backend", label: "バックエンド", color: "#68A063" },
{ id: "design", label: "デザイン", color: "#FF6B6B" },
{ id: "pm", label: "PM", color: "#9B59B6" },
];

export const MyWorld = () => {
return (
<TagBoard
tags={customTags}
columns={2}
title="あなたの役割は?"
instanceStateKey="role-tag-board"
position={[0, 1.5, -3]}
rotation={[0, 0, 0]}
scale={1.2}
/>
);
};
複数のTagBoardを設置する場合

instanceStateKey は同一ワールド内で一意である必要があります。複数の TagBoard を設置する場合は、それぞれ異なる instanceStateKey を指定してください。

依存関係
  • UsersContext が必要です(ユーザー情報の取得に使用)
  • 内部で useInstanceState フックを使用しています(タグ選択状態の同期)

DevEnvironment​

ローカル開発用の環境を提供するコンポーネントです。ワールドテンプレートの dev.tsx で使用します。

ワールド専用

DevEnvironment はワールド開発プロジェクトで npm run dev を実行した際のローカル確認用です。World.tsx などの実際のワールドコンテンツ内では使用しないでください。また、アイテム開発では使用しません(アイテムテンプレートは独自の dev.tsx を持ちます)。

import { DevEnvironment, XRiftProvider } from '@xrift/world-components'
import { World } from './World'
import xriftConfig from '../xrift.json'

createRoot(rootElement).render(
<StrictMode>
<XRiftProvider baseUrl="/">
<DevEnvironment
physicsConfig={xriftConfig.world?.physics}
camera={{ near: xriftConfig.world?.camera?.near, far: xriftConfig.world?.camera?.far }}
>
<World />
</DevEnvironment>
</XRiftProvider>
</StrictMode>
)

Props​

PropTypeDefaultDescription
childrenReactNode-ワールドコンテンツ(必須)
camera{ position?: [x, y, z]; fov?: number; near?: number; far?: number }{ fov: 50, near: 0.01, far: 1000 }カメラ設定
moveSpeednumber5.0移動速度
shadowsbooleantrueシャドウの有効/無効
spawnPosition[x, y, z][0.11, 1.6, 7.59]スポーン位置
respawnThresholdnumber-10リスポーンのY座標閾値
physicsConfigPhysicsConfig-物理設定
itemsRecord<string, ComponentType>-<Item itemId> に差し込むローカルのアイテム(itemId → コンポーネント)。指定の無い ID は xriftDev() の中継経由で本番のバンドルを読む

CameraConfig​

camera prop で設定可能なクリッピング距離です。xrift.json の world.camera 設定と対応しています。

PropTypeDefaultDescription
nearnumber0.01nearクリッピング距離
farnumber1000farクリッピング距離

PhysicsConfig​

PropTypeDefaultDescription
gravitynumber9.81重力加速度
allowInfiniteJumpbooleantrue無限ジャンプの許可
respawnThresholdnumber-10この高さを下回るとリスポーン(DevEnvironment の respawnThreshold prop を指定するとそちらが優先)

提供する機能​

  • ファーストパーソンプレイヤー: 物理ベースのWASD移動・ジャンプ・リスポーン
  • 視点操作: PointerLockControls による視点操作
  • インタラクション: INTERACTABLE レイヤーへのレイキャスト + クリックインタラクション
  • 掴む(Grabbable): GRABBABLE レイヤーへのレイキャスト + 視点前方への追従・確定
  • 座る・操縦(Seat / Vehicle): 単独プレイヤー用の座席システム。座席を狙ってクリックで着席、着席中は WASD が操縦入力になり、Space で降車
  • クロスヘアUI: 画面中央のクロスヘア(ヒット時ハイライト)
  • 案内UI: ポインターロック状態の案内UI
  • 操作説明UI: 操作方法を表示するUI

操作方法​

操作説明
クリックポインターロック開始 / インタラクト / 座席に座る
WASD / 矢印キー移動(着席中は操縦)
Space / Eジャンプ(着席中は降りる)
G掴む / いまの位置に置く(Grabbable 対象)
クリック(掴み中)掴んでいる物を使う(onUseStart / onUseEnd。インタラクトはしない)
ESCポインターロック解除(掴み中も持ったまま)
前提条件

@react-three/rapier(^2.0.0)のインストールが必要です(optional peerDependency)。


Portal​

他のワールドやインスタンスへ移動するポータルを表示するコンポーネントです。渦巻きシェーダーエフェクト、移動先のサムネイルとワールド名(インスタンス指定のときはインスタンス名と人数も)、パーティクル、グロー、クリック可能な台座で構成されます。

行き先は worldId か instanceId のどちらか一方で指定します。基本は worldId を使ってください。 台座をクリックすると確認モーダル(useConfirm)を経て移動します。

  • worldId: そのワールドの入れるインスタンスへ移動します。合流できる公開インスタンスがあればそこへ、無ければ新しく作られたインスタンスへ、プラットフォームが振り分けます。
  • instanceId: 指定したインスタンスへ直接移動します。XRift Plus の常設インスタンス専用です。通常のインスタンスは全員が退出してから 5 分で削除されるため、ID で指定するとポータルが行き先を失います。

ポータル(サムネイルのあたり)を狙ってインタラクトすると、行き先のワールドの詳細がダッシュボードで開き、インスタンス一覧から入る先を選べます。instanceId 指定のときは、そのインスタンスのワールドが開きます。ワールド側で設定することはありません。ゲストはインタラクトできません。

import { Portal } from '@xrift/world-components'

function MyWorld() {
return (
<Portal
worldId="7d3f0a2b-5c4e-4b8a-9f1d-6e2c8b4a0d35"
position={[5, 0, 0]}
rotation={[0, Math.PI / 2, 0]}
/>
)
}

Props​

PropTypeDefaultDescription
worldIdstring-移動先のワールドID。instanceId とはどちらか一方だけ指定します
instanceIdstring-移動先のインスタンスID。常設インスタンス専用。worldId とはどちらか一方だけ指定します
position[number, number, number][0, 0, 0]ポータルの座標
rotation[number, number, number][0, 0, 0]ポータルの回転
disabledbooleanfalseポータルを無効にする
ワールドIDの確認方法

ワールドIDはワールドページのURLに含まれる UUID です。例えば https://app.xrift.net/world/7d3f0a2b-5c4e-4b8a-9f1d-6e2c8b4a0d35 の場合、7d3f0a2b-5c4e-4b8a-9f1d-6e2c8b4a0d35 がワールドIDです。インスタンスIDも同じように https://app.xrift.net/instance/<ID> の URL から確認できます。

インスタンスの寿命

インスタンスは人がいる間だけ存在し、全員が退出してから 5 分で自動的に削除されます。削除されたインスタンスの URL を開くと「このインスタンスは削除されました」と表示され、ワールドページへ案内されます。残り続けるのは XRift Plus の常設インスタンスだけなので、instanceId はそれにだけ使ってください。

内部で使用するフック

Portal は worldId 指定のとき useWorld、instanceId 指定のとき useInstance で行き先の情報を取得します。移動には useInstanceContext の navigateToWorld / navigateToInstance を使っています。

worldId の指定は @xrift/world-components 0.63.0 以降で利用できます。インタラクトでワールドの詳細を開く動作は 0.65.0 以降(instanceId 指定は 0.66.0 以降)です。


Item​

ユーザー作成アイテムをワールドに最初から置くコンポーネントです。アイテムの本体はプラットフォームが読み込みます(本番は xrift-frontend、ローカル開発は DevEnvironment)。

import { Item } from '@xrift/world-components'

function MyWorld() {
return (
<>
<Item placementId="lamp-left" itemId="2a69ded4-d913-4359-8c1f-eac83a982b0c" position={[2, 0, -3]} />
<Item
placementId="lamp-right"
itemId="2a69ded4-d913-4359-8c1f-eac83a982b0c"
position={[-2, 0, -3]}
rotation={[0, Math.PI / 2, 0]}
scale={1.5}
/>
</>
)
}

Props​

PropTypeDefaultDescription
placementIdstring-この配置の id(必須)。ワールド内で一意にする。itemId が「何を置くか」、placementId が「どの配置か」。アイテム側に useItem().id として渡り、共有状態のキーに使われるので、位置を動かしても変えないこと
itemIdstring-置くアイテムの ID(必須)
position[number, number, number][0, 0, 0]座標
rotation[number, number, number][0, 0, 0]回転(ラジアン)
scalenumber1倍率
xrift.json に宣言が必要

置くアイテムの ID は xrift.json の world.items にも書いてください。宣言の無い ID は本番では読まれず、仮の箱(Item: not declared in xrift.json)が出ます。宣言できるのは自分が作ったアイテムか、ライブラリに入れたアイテムだけです。

宣言し忘れは 2 か所で止まります。ローカル開発(xriftDev())では宣言の無い ID は本番と同じ仮の箱になり、xrift upload ではビルド成果物の <Item itemId> と宣言を突き合わせ、足りない ID があればアップロード前にエラーで止まります。

アイテム ID の確認方法

アイテム ID はマイアイテムやマーケットの URL に含まれる UUID です。例えば https://app.xrift.net/marketplace/2a69ded4-d913-4359-8c1f-eac83a982b0c の場合、2a69ded4-... がアイテム ID です。

ローカル開発での動作​

npm run dev では DevEnvironment が本番と同じバンドルを読みます。そのために vite.config.ts に @xrift/sdk/vite の xriftDev() を追加し、xrift login 済みにしてください(CLI のトークンを開発サーバーが付けて API に問い合わせます。トークンはブラウザには出ません)。

// vite.config.ts
import { xriftDev } from '@xrift/sdk/vite'

export default defineConfig({
plugins: [react(), xriftDev(), federation({ /* ... */ })],
})

ローカル開発でも、xrift.json の world.items に無い ID は本番と同じ「宣言されていない」の仮の箱になります。xrift.json に追記してページをリロードすれば読まれます(開発サーバーの再起動は不要)。

アイテムとワールドを同時に作っているときや、まだアップロードしていないときは、DevEnvironment の items にローカルのコンポーネントを差し込めます。この ID も world.items に宣言が必要です(宣言が無ければ同じ仮の箱になります)。

import { Item as MyLamp } from '../../my-lamp/src/Item'

<DevEnvironment items={{ '2a69ded4-d913-4359-8c1f-eac83a982b0c': MyLamp }}>
<World />
</DevEnvironment>
アイテムから見た設置者

<Item> で置いたアイテムの useItem().placedBy は null です(ワールドの一部で、置いた人がいないため)。


Skybox​

グラデーションの空の背景を作成します。

import { Skybox } from '@xrift/world-components';

<Skybox topColor={0x87ceeb} bottomColor={0xffffff} />

Props​

PropTypeDefaultDescription
topColornumber0x87ceeb上側の色
bottomColornumber0xffffff下側の色
offsetnumber0グラデーションの開始位置
exponentnumber1グラデーションのかかり具合

Video180Sphere​

180度の VR 動画を半球に投影して再生するコンポーネントです。

import { Video180Sphere } from '@xrift/world-components';

<Video180Sphere
url="https://example.com/vr-video-180.mp4"
position={[0, 1.5, 0]}
radius={5}
loop
/>

Props​

PropTypeDefaultDescription
urlstring-180度動画の URL(必須)
position[number, number, number][0, 0, 0]位置
rotation[number, number, number][0, 0, 0]回転
scalenumber | [number, number, number]-スケール
playingbooleantrue再生状態
mutedboolean-ミュート状態(自動再生の制限を回避するには true にする)
volumenumber1音量(0〜1)
radiusnumber-半球の半径
segmentsnumber-ジオメトリの分割数
loopboolean-ループ再生
placeholderColorstring'black'動画の読み込み前に表示する色
onEnded() => void-再生終了時のコールバック
onLoadedMetadata(event: { duration: number }) => void-メタデータ読み込み時のコールバック
onProgress(event: { currentTime: number }) => void-再生位置の更新時のコールバック

BillboardY​

子要素をカメラに対してY軸回転のみで追従させるコンポーネントです。drei の <Billboard> は全軸で回転しますが、BillboardY はY軸のみ回転するため「上方向」が維持されます。炎、パーティクル、ネームプレート、看板などに最適です。

Mirror(Reflector)と併用しても、鏡の中で正しい向きで表示されます。

import { BillboardY } from '@xrift/world-components'

function NamePlate() {
return (
<BillboardY position={[0, 2, 0]}>
<mesh>
<planeGeometry args={[2, 0.5]} />
<meshStandardMaterial color="#333" />
</mesh>
</BillboardY>
)
}

Props​

<group> と同じ Props を受け取ります(position, rotation, scale など)。

フックとして使う

useBillboardY フックを使うと、任意の Object3D に対してY軸ビルボードを適用できます。詳しくはuseBillboardYを参照してください。


EntryLogBoard​

インスタンスへの入退室ログを3D空間のボードに表示します。

import { EntryLogBoard } from '@xrift/world-components';

<EntryLogBoard
position={[3, 1.5, -2]}
rotation={[0, -0.5, 0]}
maxEntries={10}
/>

Props​

PropTypeDefaultDescription
stateNamespacestring-インスタンス状態のキー(複数ボード設置時の識別用)
maxEntriesnumber-最大表示件数
formatTimestamp(timestampMs: number) => string-タイムスタンプのフォーマット関数(epoch ミリ秒を受け取る)
displayNameFallbackstring-表示名が取得できない場合のフォールバック
labelsPartial<Labels>-ラベル文言のカスタマイズ(join、leave)
colorsPartial<Colors>-色設定のカスタマイズ(join、leave、background、text)
position[number, number, number][0, 0, 0]ボードの位置
rotation[number, number, number][0, 0, 0]ボードの回転
scalenumber1全体スケール
onJoin(entry: LogEntry) => void-入室時のコールバック
onLeave(entry: LogEntry) => void-退室時のコールバック
内部で使用するフック

EntryLogBoard は自分の入室ログを自身で書き込み、ログを useInstanceState で同期します。 時刻は共有時計(useServerClock)の epoch ミリ秒で保持し、user-left イベントの受信に useInstanceEvent を使用しています。


フック​

useInstanceState​

インスタンス内の全ユーザー間で状態を同期します。React の useState と同じインターフェースです。

import { useInstanceState } from '@xrift/world-components';

function Counter() {
const [count, setCount] = useInstanceState('counter', 0);

return (
<mesh onClick={() => setCount(count + 1)}>
{/* count は全ユーザーで同期される */}
</mesh>
);
}

引数​

引数TypeDescription
keystring状態の一意な識別子
initialValueT初期値

戻り値​

[value: T, setValue: (newValue: T) => void] - useState と同じ形式


useInstanceEvent​

インスタンスイベントの送受信を行うフックです。プラットフォームイベント(user-joined, user-left)の受信や、ワールド独自のカスタムイベントの送受信ができます。

import { useInstanceEvent } from '@xrift/world-components';

// プラットフォームイベントの受信(受信のみ、emit 不可)
useInstanceEvent('user-joined', ({ userId }) => {
console.log('User joined:', userId)
})

// カスタムイベントの送受信
const emitReaction = useInstanceEvent<{ emoji: string }>('reaction', ({ payload, senderId }) => {
console.log(`${senderId} reacted:`, payload.emoji)
})
emitReaction({ emoji: '👍' })

引数​

引数TypeDescription
eventNamestringイベント名
callback(event: InstanceEvent<T>) => voidイベント受信時のコールバック(プラットフォームイベントは下の表の型)

戻り値​

(data: T) => void - イベント送信関数。送った値は、受け取る側で payload に入ります。プラットフォーム予約イベント(user-joined, user-left)の場合は no-op になります。

受け取るデータ​

カスタムイベントは、送った値を payload に入れた InstanceEvent<T> で届きます。

プロパティType説明
payloadT送り手が送った値
senderIdstring送った人の userId。サーバーが付けるので偽れない
timestampnumber送った時刻(useServerClock と同じインスタンス共有時計の ms)

プラットフォームイベントは、次のデータがそのまま届きます。

イベント名届くデータ説明
user-joined{ userId: string, isGuest: boolean }ユーザーがインスタンスに入室
user-left{ userId: string }ユーザーがインスタンスから退室

届く相手​

  • カスタムイベントは、送った本人には届きません。インスタンス内のほかの参加者にだけ届きます。自分の画面にも反映するときは、送るときに自分でも処理してください(下のリアクションの例)
  • 入室処理が終わる前に送ったイベントは、終わってから届けられます。入室直後に送っても消えません
  • 後から入室した人には、それより前のイベントは届きません。後から来た人にも見せたい状態は useInstanceState を使ってください

ユースケース​

リアクション機能​
import { useInstanceEvent } from '@xrift/world-components';
import { useCallback, useState } from 'react';

type Reaction = { emoji: string };

function ReactionSystem() {
const [reactions, setReactions] = useState<Reaction[]>([]);

// ほかの参加者のリアクション
const emitReaction = useInstanceEvent<Reaction>('reaction', ({ payload }) => {
setReactions(prev => [...prev, payload]);
});

const sendReaction = useCallback((emoji: string) => {
const reaction = { emoji };
emitReaction(reaction);
// 自分には届かないので、自分の分はここで足す
setReactions(prev => [...prev, reaction]);
}, [emitReaction]);

return (
<mesh onClick={() => sendReaction('👍')}>
<boxGeometry args={[1, 1, 0.2]} />
<meshStandardMaterial color="yellow" />
</mesh>
);
}
入退室の検知​
import { useInstanceEvent } from '@xrift/world-components';

function JoinLeaveNotifier() {
useInstanceEvent('user-joined', ({ userId, isGuest }) => {
console.log('User joined:', userId, isGuest);
});

useInstanceEvent('user-left', ({ userId }) => {
console.log('User left:', userId);
});

return null;
}
カスタムイベントとインスタンスステートの使い分け
  • useInstanceEvent: 一時的なイベント通知(リアクション、エフェクトトリガーなど)に適しています。
  • useInstanceState: 永続的な同期状態(カウンター、ON/OFF状態など)に適しています。
開発環境での動作

開発環境(DevEnvironment)にはほかの参加者が居ないので、送ったカスタムイベントはどこにも届きません(本番と同じく、送った本人にも届きません)。受け取る側の動きは、本番で 2 つのタブから同じインスタンスに入って確かめてください。


useServerClock​

インスタンス内の全端末で一致する時計(サーバ時刻)を提供します。端末の Date.now() は互いに 0.1〜数秒ズレているため、カウントダウン・同時演出・動画の再生位置合わせ・全員で揃う周期アニメーションなど、「同じタイミング」を要する処理には必ずこちらを使います。

import { useServerClock } from '@xrift/world-components';
import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';
import type { Mesh } from 'three';

// 全員の画面で同じ位相で動く床(通信ゼロ。後から入った人も即座に一致する)
function MovingFloor() {
const { now } = useServerClock();
const floor = useRef<Mesh>(null);

useFrame(() => {
if (!floor.current) return;
// 位置を「時刻の関数」として書く。状態を持たないので同期処理そのものが不要
floor.current.position.y = 1 + Math.sin(now() / 1000) * 0.5;
});

return (
<mesh ref={floor}>
<boxGeometry args={[2, 0.2, 2]} />
<meshStandardMaterial color="skyblue" />
</mesh>
);
}

引数​

引数TypeDescription
options.require'media' | 'motion'(省略可)用途に応じた精度要件。trustworthy の判定に使われます

戻り値​

PropertyTypeDescription
now() => numberサーバ時刻の推定値(ms)。値ではなく関数なので useFrame の中から再レンダーなしで呼べます。初回同期前は Date.now() にフォールバック
uncertaintynumber推定誤差の上界(ms)。経過時間による劣化を含みます。未同期なら Infinity
syncedbooleanいま同期が有効か。切断中は false になりますが now() は直前の推定を返し続けます
trustworthybooleanrequire で指定した精度要件を満たしているか。省略時は synced と同じ
timeJumpCountnumber時刻が飛んだ回数。差分を積算する作りの場合はこの変化で基準を取り直します(下記)
lastTimeJumpMsnumber直近に飛んだ量(ms)。負なら時刻が戻りました

精度プリセット​

プリセット要求精度用途
media±300ms動画・音楽の再生位置合わせ
motion±100ms周期アニメーション(動く床・観覧車)、同時演出

実測ではデスクトップ・Quest(Wi-Fi)とも ±40ms 程度で、どちらのプリセットも満たします。

時刻が「飛ぶ」ことがある​

通常の補正は徐々に寄せるため時刻は巻き戻りませんが、スリープ復帰や初回同期の完了時には飛びます。上の例のように位置を毎フレーム時刻から計算する(stateless な)作りなら、何もしなくても次のフレームで自己回復します。速度や差分を積算する作りの場合だけ、timeJumpCount の変化を見て基準を取り直してください。

const { now, timeJumpCount } = useServerClock();
const seen = useRef(timeJumpCount);

useFrame(() => {
if (seen.current !== timeJumpCount) {
seen.current = timeJumpCount;
resetBaseline(); // 時刻が飛んだので基準を取り直す
}
// ...
});

動画の再生位置合わせに使う場合​

原則は「補正のコストが誤差より大きいなら補正しない」です。シークはバッファの破棄と再取得(= 再生停止)を伴うため、小さなズレの補正に使ってはいけません。

const clock = useServerClock({ require: 'media' });

useFrame(() => {
if (!clock.trustworthy) return; // 精度が出ていないなら同期を諦める(再生継続を優先)
const target = ((clock.now() - epoch) / 1000) % duration;
const diff = target - video.currentTime;
if (Math.abs(diff) < 0.3) {
video.playbackRate = 1; // dead band。戻し忘れると振動し続けるので注意
return;
}
if (Math.abs(diff) < 5) {
video.playbackRate = 1 + Math.sign(diff) * 0.05; // 映像を止めずに吸収
return;
}
if (isBuffered(video, target)) video.currentTime = target; // バッファ内のときだけシーク
// バッファ外なら何もしない(同期より再生継続を優先)
});
公平性が要る用途には使えません

早押しやゴール判定には使わないでください。通信経路の行き帰りが非対称なぶんの誤差はクライアント側から検出できず、セッション中ほぼ一定なので繰り返しても平均化されません(= 回線条件で同じ人が毎回勝ちます)。勝敗の判定はサーバー側で裁定する設計にしてください。

開発環境での動作

開発環境ではデフォルト実装(synced: false・now() はローカル時計)が使われるため、trustworthy は常に false です。同期ロジックを開発中に動かすには、dev エントリで XRiftProvider に同期済みのフェイク実装を注入してください。

<XRiftProvider
baseUrl="/"
serverClockImplementation={{
now: () => Date.now(),
uncertainty: 10,
synced: true,
timeJumpCount: 0,
lastTimeJumpMs: 0,
}}
>

@xrift/world-components 0.47.0 以降で利用できます。


useScreenShareContext​

画面共有の状態を取得するフックです。

import { useScreenShareContext } from '@xrift/world-components';

function MyComponent() {
const { videoElement, isSharing, startScreenShare, stopScreenShare } = useScreenShareContext();

return (
<button onClick={isSharing ? stopScreenShare : startScreenShare}>
{isSharing ? '共有を停止' : '共有を開始'}
</button>
);
}

戻り値​

PropertyTypeDescription
videoElementHTMLVideoElement | null表示する映像のvideo要素
isSharingboolean自分が共有中かどうか
startScreenShare() => void共有開始
stopScreenShare() => void共有停止

useSpawnPoint​

プラットフォーム側がスポーン地点情報を取得するためのフックです。

import { useSpawnPoint } from '@xrift/world-components';

function MyPlatform() {
const spawnPoint = useSpawnPoint();
// spawnPoint: { position: [x, y, z], yaw: number }
}

戻り値​

PropertyTypeDescription
position[number, number, number]スポーン位置
yawnumberスポーン時の向き(度数法)
使用先

このフックは xrift-frontend(プラットフォーム)側での使用を想定しています。ワールド開発者は SpawnPoint コンポーネントを使用してください。


useUsers​

ワールドに参加しているユーザー情報と位置情報を取得するフックです。自分自身(ローカルユーザー)と他の参加者(リモートユーザー)の情報にアクセスできます。

import { useUsers } from '@xrift/world-components';

function ParticipantCount() {
const { localUser, remoteUsers, getMovement, getLocalMovement } = useUsers();

const totalCount = (localUser ? 1 : 0) + remoteUsers.length;

return (
<div>
<p>参加者数: {totalCount}人</p>
</div>
);
}

戻り値​

PropertyTypeDescription
localUserUser | null自分自身のユーザー情報
remoteUsersUser[]他の参加者のユーザー情報の配列
getMovement(id: string) => PlayerMovement | undefined指定ユーザーの位置情報を取得
getLocalMovement() => PlayerMovement自分の位置情報を取得
getAvatarHeight?(id: string) => AvatarHeight | undefined指定ユーザーのアバター高さ情報を取得
getLocalAvatarHeight?() => AvatarHeight自分のアバター高さ情報を取得

User 型​

interface User {
id: string; // ユーザーID
displayName: string; // 表示名
userIconUrl: string | null; // アバターアイコンURL
isGuest: boolean; // ゲストかどうか
}

PlayerMovement 型​

interface PlayerMovement {
position: { x: number; y: number; z: number };
direction: { x: number; z: number };
horizontalSpeed: number;
verticalSpeed: number;
rotation: { yaw: number; pitch: number };
isGrounded: boolean;
isJumping: boolean;
isInVR?: boolean;
vrTracking?: VRTrackingData;
}

AvatarHeight 型​

interface AvatarHeight {
height: number; // アバターの全身の高さ(メートル)
eyeHeight: number; // 地面からアバターの目の位置までの高さ(メートル)
}
デフォルト値

プラットフォーム側が getAvatarHeight / getLocalAvatarHeight を実装していない場合、デフォルト値として height: 1.5、eyeHeight: 1.35 が返されます。optional プロパティのため、呼び出し時はオプショナルチェーン(?.)を使用してください。

useFrame 内での位置情報取得​

getMovement() と getLocalMovement() は useFrame 内で毎フレーム呼び出すことができます。これらの関数は再レンダリングを発生させずに最新の位置情報を取得できます。

import { useUsers } from '@xrift/world-components';
import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';
import { Group } from 'three';

function FollowCamera() {
const groupRef = useRef<Group>(null);
const { getLocalMovement } = useUsers();

useFrame(() => {
const movement = getLocalMovement();
if (!groupRef.current) return;

// 自分の位置の少し上にオブジェクトを配置
groupRef.current.position.set(
movement.position.x,
movement.position.y + 3,
movement.position.z
);
});

return (
<group ref={groupRef}>
<pointLight intensity={1} />
</group>
);
}

ユースケース​

ユーザーの頭上にHUDを表示​
import { useUsers } from '@xrift/world-components';
import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';
import { Group } from 'three';
import { Text } from '@react-three/drei';

function UserHUD({ user, getMovement, getAvatarHeight }) {
const groupRef = useRef<Group>(null);

useFrame(() => {
const movement = getMovement(user.id);
if (!movement || !groupRef.current) return;

// アバターの高さを取得し、頭の上にHUDを配置
const avatarHeight = getAvatarHeight?.(user.id);
const headOffset = (avatarHeight?.height ?? 1.5) + 0.2;

groupRef.current.position.set(
movement.position.x,
movement.position.y + headOffset,
movement.position.z
);
});

return (
<group ref={groupRef}>
<Text fontSize={0.2}>{user.displayName}</Text>
</group>
);
}

function UserHUDs() {
const { remoteUsers, getMovement, getAvatarHeight } = useUsers();

return (
<>
{remoteUsers.map(user => (
<UserHUD key={user.id} user={user} getMovement={getMovement} getAvatarHeight={getAvatarHeight} />
))}
</>
);
}
近くにいるユーザーを検出​
import { useUsers } from '@xrift/world-components';
import { useFrame } from '@react-three/fiber';
import { useState } from 'react';

function ProximityDetector() {
const { remoteUsers, getMovement, getLocalMovement } = useUsers();
const [nearbyUsers, setNearbyUsers] = useState<string[]>([]);

useFrame(() => {
const myPos = getLocalMovement().position;
const nearby: string[] = [];

remoteUsers.forEach(user => {
const movement = getMovement(user.id);
if (!movement) return;

const distance = Math.sqrt(
Math.pow(myPos.x - movement.position.x, 2) +
Math.pow(myPos.y - movement.position.y, 2) +
Math.pow(myPos.z - movement.position.z, 2)
);

if (distance < 5) {
nearby.push(user.displayName);
}
});

// 配列の内容が変わった場合のみ更新
if (JSON.stringify(nearby) !== JSON.stringify(nearbyUsers)) {
setNearbyUsers(nearby);
}
});

return null;
}
ユーザー間の距離を計算​
import { useUsers } from '@xrift/world-components';
import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';
import { Line } from '@react-three/drei';

function DistanceLine({ targetUser, getMovement, getLocalMovement }) {
const lineRef = useRef<any>(null);

useFrame(() => {
const myPos = getLocalMovement().position;
const targetMovement = getMovement(targetUser.id);
if (!targetMovement || !lineRef.current) return;

lineRef.current.geometry.setPositions([
myPos.x, myPos.y + 1, myPos.z,
targetMovement.position.x, targetMovement.position.y + 1, targetMovement.position.z
]);
});

return (
<Line
ref={lineRef}
points={[[0, 0, 0], [0, 0, 0]]}
color="yellow"
lineWidth={2}
/>
);
}
パフォーマンスのヒント

getMovement() と getLocalMovement() は useFrame 内で毎フレーム呼び出しても問題ありません。これらは内部的にキャッシュされた値を返すため、パフォーマンスへの影響は最小限です。

remoteUsers の更新タイミング

remoteUsers 配列はユーザーの参加/離脱時のみ更新されます。ユーザーの位置情報の変化では再レンダリングは発生しません。位置情報は常に getMovement() を使用して取得してください。


useViewpoint​

自分のカメラが一人称か三人称かを返すフックです。PC・スマホではプレイヤーがマウスホイール(スマホは2本指のピンチ)で一人称と三人称を切り替えられます。頭に付ける演出(ゴーグルの枠・被り物など)を三人称では消す、三人称のときだけ自分の頭上に目印を出す、といった出し分けに使います。

import { useViewpoint } from '@xrift/world-components';

// 一人称のときだけゴーグルの枠を出し、三人称では頭上に矢印を出す
function MyHeadEffect() {
const { isThirdPerson } = useViewpoint();
return isThirdPerson ? <ArrowAboveMe /> : <GogglesFrame />;
}

毎フレームの処理では、再レンダーを待たずに最新の値が取れる getViewpoint() を使います。

import { useViewpoint } from '@xrift/world-components';
import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';
import { BackSide, type Mesh } from 'three';

// 目の周りを薄く色付けする(三人称では自分のアバターまで覆ってしまうので消す)
function VisorTint() {
const { getViewpoint } = useViewpoint();
const tint = useRef<Mesh>(null);

useFrame(({ camera }) => {
if (!tint.current) return;
tint.current.position.copy(camera.position);
tint.current.visible = getViewpoint() === 'first-person';
});

return (
<mesh ref={tint}>
<sphereGeometry args={[0.3, 16, 16]} />
<meshBasicMaterial color="orange" transparent opacity={0.15} side={BackSide} depthWrite={false} />
</mesh>
);
}

戻り値​

PropertyTypeDescription
viewpoint'first-person' | 'third-person'いまの視点。切り替わると再レンダーされます
isThirdPersonboolean三人称か(viewpoint === 'third-person')
getViewpoint() => 'first-person' | 'third-person'いまの視点を返す関数。値ではなく関数なので useFrame の中から再レンダーなしで呼べ、切り替えたそのフレームから正しい値を返します

一人称を返す場面​

次の場合は、プレイヤーが三人称を選んでいても 'first-person' を返します。

  • VR: VR は常に一人称です
  • カメラモード(撮影)のプレビュー中: 撮影用の別カメラに一時的に切り替わっているだけなので、プレイヤーの視点としては一人称のままです。撮る瞬間だけワールドの演出が切り替わって、写したいものが消えるのを防ぎます

DevEnvironment は三人称を持たないので、ローカル開発では常に 'first-person' です。

対応バージョン

@xrift/world-components 0.58.0 以降で使えます。


useTeleport​

自分自身のアバターを指定した座標に瞬間移動させるフックです。ポータル、エレベーター、ワープゾーンなどのユースケースに対応します。

import { useTeleport } from '@xrift/world-components';

function MyComponent() {
const { teleport } = useTeleport();

const handleTeleport = useCallback(() => {
teleport({ position: [50, 0, 30], yaw: 180 });
}, [teleport]);
}

API​

interface TeleportDestination {
position: [number, number, number]
yaw?: number // 度数法(0-360)省略時は現在の向きを維持
}

const { teleport } = useTeleport()

パラメータ(TeleportDestination)​

パラメータ型必須説明
position[number, number, number]Yesテレポート先の座標 [x, y, z]
yawnumberNoテレポート後の向き(度数法 0-360)。省略時は現在の向きを維持

使用例​

ポータルでテレポート​
import { useTeleport, Interactable } from '@xrift/world-components'
import { useCallback } from 'react'

function MyWorld() {
const { teleport } = useTeleport()

const handlePortal = useCallback(() => {
teleport({ position: [50, 0, 30], yaw: 180 })
}, [teleport])

return (
<Interactable id="portal" onInteract={handlePortal}>
<mesh>
<torusGeometry />
<meshStandardMaterial color="purple" />
</mesh>
</Interactable>
)
}
yaw の省略

yaw を省略するとテレポート後もプレイヤーの現在の向きが維持されます。特定の方向を向かせたい場合のみ指定してください。


useConfirm​

ユーザーに確認モーダルを表示するフックです。ワールド移動など重要なアクションの前に確認を求めることができます。

import { useConfirm } from '@xrift/world-components';

function MyComponent() {
const { requestConfirm } = useConfirm();

const handleAction = async () => {
const ok = await requestConfirm({ message: 'ワールドを移動しますか?' });
if (ok) {
// 確認された場合の処理
}
};
}

戻り値​

PropertyTypeDescription
requestConfirm(options: ConfirmOptions) => Promise<boolean>確認モーダルを表示し、結果を返す

ConfirmOptions​

PropertyType必須Description
messagestringYesユーザーに表示するメッセージ
titlestringNoダイアログのタイトル
confirmLabelstringNo確認ボタンのラベル
cancelLabelstringNoキャンセルボタンのラベル

使用例​

外部サイトへの遷移前に確認​
import { useConfirm, Interactable } from '@xrift/world-components'

function ExternalLink() {
const { requestConfirm } = useConfirm()

const handleClick = async () => {
const ok = await requestConfirm({
title: '外部サイトへ移動',
message: '外部サイトへ移動します。よろしいですか?',
confirmLabel: '移動する',
cancelLabel: 'キャンセル',
})
if (ok) {
window.open('https://example.com', '_blank')
}
}

return (
<Interactable id="external-link" onInteract={handleClick}>
<mesh>
<boxGeometry args={[1, 1, 0.2]} />
<meshStandardMaterial color="cyan" />
</mesh>
</Interactable>
)
}
iOS Safari のポップアップブロック回避

iPhone 等のモバイルブラウザでは、ユーザー操作を起点としない window.open や外部サイトへの遷移がブロックされます。useConfirm で確認ダイアログを挟むことで、ユーザー操作起点のイベントチェーンを作り、ブラウザのポップアップブロックを回避できます。

Portal コンポーネントとの関係

Portal コンポーネントは内部で useConfirm を使用しています。Portal を使う場合は useConfirm を直接呼ぶ必要はありません。


useInstance​

インスタンス情報の取得と確認付き遷移を提供するフックです。内部で useConfirm を使い、遷移前に確認モーダルを表示します。

ID を固定して参照できるのは常設インスタンスだけ

インスタンスは全員が退出してから 5 分で自動的に削除されるため、通常のインスタンスの ID をワールドに埋め込んでも、すぐに参照先が無くなります。ID を固定して使えるのは XRift Plus の常設インスタンスだけです。ワールド単位で移動させたいときは Portal の worldId か、useInstanceContext の navigateToWorld を使ってください。

import { useInstance } from '@xrift/world-components'

function MyComponent() {
const { info, navigateWithConfirm } = useInstance('target-instance-id')

if (!info) return null

return (
<mesh onClick={navigateWithConfirm}>
{/* インスタンス名: {info.name} */}
</mesh>
)
}

引数​

引数TypeDescription
instanceIdstring取得するインスタンスのID

戻り値​

PropertyTypeDescription
infoInstanceInfo | nullインスタンス情報(取得前は null)
navigateWithConfirm() => Promise<void>確認モーダル付きでインスタンスへ遷移

InstanceInfo 型​

フィールドTypeDescription
idstringインスタンスID
namestringインスタンス名
descriptionstring | null説明
currentUsersnumber現在のユーザー数
maxCapacitynumber最大収容人数
isPublicboolean公開かどうか
allowGuestsbooleanゲスト許可
owner{ id, displayName, userIconUrl? }オーナー情報(任意)
worldWorldInfo所属ワールドの情報

useWorld​

ワールド情報の取得を提供するフックです。

import { useWorld } from '@xrift/world-components'

function MyComponent() {
const { info } = useWorld('target-world-id')

if (!info) return null

return (
<mesh>
{/* ワールド名: {info.name} */}
</mesh>
)
}

引数​

引数TypeDescription
worldIdstring取得するワールドのID

戻り値​

PropertyTypeDescription
infoWorldInfo | nullワールド情報(取得前は null)

WorldInfo 型​

フィールドTypeDescription
idstringワールドID
namestringワールド名
descriptionstring | null説明
thumbnailUrlstring | nullサムネイルURL
isPublicboolean公開かどうか
instanceCountnumberインスタンス数
totalVisitCountnumber総訪問数
uniqueVisitorCountnumberユニーク訪問者数
favoriteCountnumberお気に入り数
owner{ id, displayName, userIconUrl? }オーナー情報(任意)
permissions{ allowedDomains: string[], allowedCodeRules: string[] } | undefinedワールドが必要とする権限(詳細)

useInstanceContext​

インスタンス情報の取得と、ワールドやインスタンスへの移動を提供する Context を取得するフックです。Portal や useInstance の内部でも使われています。確認モーダルは出さないので、移動前に確認を取りたいときは useConfirm と組み合わせてください。

import { useInstanceContext, useConfirm, Interactable } from '@xrift/world-components'

function WorldGate() {
const { navigateToWorld } = useInstanceContext()
const { requestConfirm } = useConfirm()

const handleEnter = async () => {
const ok = await requestConfirm({ message: 'ハブワールドへ移動しますか?' })
if (ok) await navigateToWorld('7d3f0a2b-5c4e-4b8a-9f1d-6e2c8b4a0d35')
}

return (
<Interactable id="world-gate" onInteract={handleEnter}>
<mesh>
<torusGeometry />
<meshStandardMaterial color="purple" />
</mesh>
</Interactable>
)
}

戻り値​

PropertyTypeDescription
navigateToWorld(worldId: string) => void | Promise<void>指定したワールドへ移動します。入るインスタンス(公開インスタンスに合流、無ければ新規作成)はプラットフォームが決めます。ポータルの行き先は原則こちらを使ってください。満員やレート制限などで失敗すると reject されます
navigateToInstance(instanceId: string) => void | Promise<void>指定したインスタンスへ移動します。常設インスタンス専用です。失敗すると reject されます
getInstanceInfo(instanceId: string) => Promise<InstanceInfo>インスタンス情報を取得します
開発環境での動作

DevEnvironment ではデフォルト実装が使われ、移動は行わずコンソールにログを出します。実際の移動は XRift 上で確認してください。

navigateToWorld は @xrift/world-components 0.63.0 以降で利用できます。


useVoiceVolumeOverride​

ユーザーごとのボイスチャット音量をオーバーライドするフックです。ステージや壇上にいるユーザーの声を全体に届けるなどのユースケースに対応します。

import { useVoiceVolumeOverride } from '@xrift/world-components';

function StagePodium() {
const { setOverride, clearOverride } = useVoiceVolumeOverride();

// ステージに乗ったユーザーの声を全員に届ける
const handleEnter = (userId: string) => {
setOverride(userId, 1.0);
};
const handleLeave = (userId: string) => {
clearOverride(userId);
};
}

戻り値​

PropertyTypeDescription
setOverride(userId: string, volume: number) => void指定ユーザーのボリュームをオーバーライド
clearOverride(userId: string) => voidオーバーライドを解除
clearAll() => voidすべてのオーバーライドを解除
getOverrides() => ReadonlyMap<string, number>現在のオーバーライド一覧を取得
旧名称からの移行

v0.34.0 で useAudioVolume から useVoiceVolumeOverride にリネームされました。旧名称は @deprecated として引き続き使用可能ですが、新しい名前への移行を推奨します。


useBillboardY​

対象の Object3D を毎フレームカメラに向けてY軸のみ回転させるフックです。BillboardY コンポーネントの内部で使用されていますが、任意の Object3D に適用したい場合に直接使えます。

内部では sentinel Mesh の onBeforeRender を使用しているため、Mirror(Reflector)の virtualCamera でも正しい回転が適用されます。

import { useBillboardY } from '@xrift/world-components'
import type { Group } from 'three'

function CustomBillboard() {
const ref = useBillboardY<Group>()

return (
<group ref={ref}>
<mesh>
<planeGeometry args={[1, 1.5]} />
<meshBasicMaterial map={fireTexture} />
</mesh>
</group>
)
}

戻り値​

PropertyTypeDescription
refRefObject<T>対象の Object3D にアタッチする ref

関連​

  • BillboardY コンポーネント — このフックを <group> でラップしたもの
  • getBillboardYRotation(cameraWorldPos, targetWorldPos) — 回転角度を計算する純粋関数(InstancedMesh などで手動計算する場合に使用)

useDefaultFont​

UIKit(@pmndrs/uikit)用の多言語 MSDF フォントをロードするフックです。ロード完了時に uikit のグローバルプロパティとしても登録されるため、Container に fontFamilies を明示的に渡さなくても fontFamily="ja" が使えます。

import { useDefaultFont } from '@xrift/world-components'
import type { FontLocale } from '@xrift/world-components'

const FONT_LOCALES: FontLocale[] = ['ja']

function MyUIComponent() {
const fontFamilies = useDefaultFont(FONT_LOCALES)

return (
<Container fontFamilies={fontFamilies}>
<Text fontFamily="ja">こんにちは</Text>
</Container>
)
}

引数​

引数TypeDescription
localesFontLocale[]ロードするフォントのロケール配列

戻り値​

FontFamilies | undefined — ロード完了後に FontFamilies を返す。ロード中は undefined。

FontLocale​

type FontLocale = 'ja'
グローバル登録

モジュール読み込み時にフォントが自動的にフェッチされ、setGlobalProperties で uikit にグローバル登録されます。そのため、Container に fontFamilies を渡さなくても fontFamily="ja" が利用可能です。明示的に渡す場合はロード中の undefined ハンドリングが不要になります。


useFileInput​

ファイル選択ダイアログを表示するフックです。3Dオブジェクトのクリックをトリガーに、ブラウザのファイルピッカー(ドラッグ&ドロップ対応のオーバーレイUI)を開くことができます。

import { useFileInput } from '@xrift/world-components';

function MyComponent() {
const { requestFileInput } = useFileInput();

const handleClick = () => {
requestFileInput({
id: 'avatar-upload',
accept: '.vrm',
maxSize: 30 * 1024 * 1024,
onSelect: (files) => console.log('選択:', files),
});
};
}

戻り値​

PropertyTypeDescription
requestFileInput(request: FileInputRequest) => voidファイル選択ダイアログを表示する

FileInputRequest​

PropertyType必須Description
idstringYes入力の一意なID
acceptstringNo受け入れるファイルタイプ(例: '.vrm', 'image/*')
multiplebooleanNo複数ファイル選択を許可するか
maxSizenumberNo最大ファイルサイズ(バイト単位)
onSelect(files: File[]) => voidYesファイル選択完了時のコールバック
onCancel() => voidNoキャンセル時のコールバック
onError(error: FileInputError) => voidNoエラー時のコールバック

FileInputError​

PropertyTypeDescription
type'file_too_large' | 'invalid_type'エラー種別
messagestringエラーメッセージ

使用例​

VRMファイルのアップロード​
import { useFileInput, Interactable } from '@xrift/world-components'
import { useState } from 'react'

function AvatarUploader() {
const { requestFileInput } = useFileInput()
const [fileName, setFileName] = useState('')

const handleClick = () => {
requestFileInput({
id: 'avatar-upload',
accept: '.vrm',
maxSize: 30 * 1024 * 1024, // 30MB
onSelect: (files) => {
setFileName(files[0].name)
// ファイルをアップロードする処理...
},
onError: (error) => {
console.error(error.message)
},
})
}

return (
<Interactable id="upload-button" onInteract={handleClick} interactionText="アバター変更">
<mesh>
<boxGeometry args={[1, 0.5, 0.1]} />
<meshStandardMaterial color="#7b2d8b" />
</mesh>
</Interactable>
)
}
ドラッグ&ドロップ対応

ファイル選択オーバーレイはドラッグ&ドロップにも対応しています。ユーザーはクリックでファイルを選択するか、ファイルをドロップゾーンにドラッグして追加できます。

VRセッション中の動作

VRセッション中にファイル選択がリクエストされた場合、自動的にVRセッションが終了してからファイルピッカーが表示されます。


useSharedFile​

インスタンスの共有ファイルをアップロード・一覧取得・ロック(削除保護)・情報更新・削除するフックです。3D空間内から画像やドキュメントをアップロードし、他のユーザーと共有できます。

import { useSharedFile } from '@xrift/world-components';

function MyComponent() {
const { uploadSharedFile, getSharedFiles, setSharedFileLock, updateSharedFile } = useSharedFile();

const handleUpload = async (file: File) => {
const result = await uploadSharedFile(file, (progress) => {
console.log(`${progress}%`);
});
console.log('URL:', result.publicUrl);
// アップロード直後にロックして誤削除を防ぐ
await setSharedFileLock(result.id, true);
};
}

戻り値​

PropertyTypeDescription
uploadSharedFile(file: File, onProgress?: (progress: number) => void, options?: UploadSharedFileOptions) => Promise<SharedFileInfo>ファイルをアップロードする
getSharedFiles() => Promise<SharedFileInfo[]>共有ファイル一覧を取得する
setSharedFileLock(fileId: string, locked: boolean) => Promise<SharedFileInfo>ロック状態(削除保護)を設定する
updateSharedFile(fileId: string, updates: UpdateSharedFileParams) => Promise<SharedFileInfo>ファイル情報(fileName / description / metadata)を更新する
deleteSharedFile(fileId: string) => Promise<void>ファイルを削除する

SharedFileInfo​

PropertyTypeDescription
idstringファイルの一意なID
fileNamestringファイル名
contentTypestringMIMEタイプ
fileSizenumberファイルサイズ(バイト)
publicUrlstring公開URL
lockedbooleanロック中(削除保護)かどうか
descriptionstring | null説明文
metadataRecord<string, string> | null構造化メタデータ
createdAtstring作成日時(ISO 8601)

UploadSharedFileOptions​

アップロード時に任意で付与できる情報です。

PropertyTypeDescription
descriptionstring説明文(500文字以内)
metadataRecord<string, string>フラットな key-value のメタデータ(20件以内、キー1〜64文字、値500文字以内)

UpdateSharedFileParams​

updateSharedFile に渡す更新内容です。description / metadata は null を指定するとクリアできます。

PropertyTypeDescription
fileNamestringファイル名
descriptionstring | null説明文(null でクリア)
metadataRecord<string, string> | nullメタデータ(null でクリア)
注記

ロック中(locked: true)のファイルは deleteSharedFile による削除も updateSharedFile による更新も拒否されます。削除・更新したい場合は先に setSharedFileLock(fileId, false) でロックを解除してください。

使用例​

画像のアップロードと一覧表示​
import { useSharedFile, useFileInput, Interactable } from '@xrift/world-components'
import { useCallback, useState } from 'react'

function SharedFileUploader() {
const { uploadSharedFile, getSharedFiles } = useSharedFile()
const { requestFileInput } = useFileInput()
const [status, setStatus] = useState('')

const handleUpload = useCallback(() => {
requestFileInput({
id: 'shared-file-upload',
accept: 'image/*',
maxSize: 10 * 1024 * 1024, // 10MB
onSelect: async (files) => {
const file = files[0]
if (!file) return
try {
const result = await uploadSharedFile(file, (progress) => {
setStatus(`アップロード中: ${progress}%`)
})
setStatus(`完了: ${result.fileName}`)
} catch (e) {
setStatus(`エラー: ${e instanceof Error ? e.message : String(e)}`)
}
},
})
}, [requestFileInput, uploadSharedFile])

const handleList = useCallback(async () => {
const files = await getSharedFiles()
setStatus(`${files.length}件のファイル`)
}, [getSharedFiles])

return (
<>
<Interactable id="upload-btn" onInteract={handleUpload} interactionText="アップロード">
<mesh>
<boxGeometry args={[1, 0.5, 0.1]} />
<meshStandardMaterial color="#d4a017" />
</mesh>
</Interactable>
<Interactable id="list-btn" onInteract={handleList} interactionText="一覧表示">
<mesh position={[1.5, 0, 0]}>
<boxGeometry args={[1, 0.5, 0.1]} />
<meshStandardMaterial color="#c47f17" />
</mesh>
</Interactable>
</>
)
}
説明文・メタデータ付きアップロードとロック​

来場者がアップロードしたファイルを永続展示するようなケースでは、アップロード時に説明文・メタデータを付与し、直後にロックすることで誤削除を防げます。

import { useSharedFile } from '@xrift/world-components'

function ExhibitUploader() {
const { uploadSharedFile, setSharedFileLock, updateSharedFile, deleteSharedFile } = useSharedFile()

const handleExhibitUpload = async (file: File) => {
// 説明文・メタデータを付与してアップロード
const result = await uploadSharedFile(file, undefined, {
description: '展示品A',
metadata: { exhibit: 'pedestal-1' },
})

// アップロード直後にロックして誤削除を防ぐ
await setSharedFileLock(result.id, true)

return result.publicUrl
}

const handleUpdateDescription = async (fileId: string) => {
// ロック中は更新できないため、一度解除してから更新して再ロック
await setSharedFileLock(fileId, false)
await updateSharedFile(fileId, { description: '展示品B' })
await setSharedFileLock(fileId, true)
}

const handleRemoveExhibit = async (fileId: string) => {
// 展示を取り下げてファイル実体も削除(ロック中は先に解除する)
await setSharedFileLock(fileId, false)
await deleteSharedFile(fileId)
}

// ...
}

useItem​

配置されたアイテムの固有IDと設置者の情報を取得するフックです。同じアイテムが複数配置された場合でも、配置ごとに異なるIDが返されます。

import { useItem } from '@xrift/world-components';

function MyItem() {
const { id, placedBy } = useItem();
// id は配置ごとにユニーク
// placedBy はこのアイテムを設置したユーザー(特定できない場合は null)
}

戻り値​

PropertyTypeDescription
idstring配置オブジェクトの固有ID(UUID)
placedByItemPlacer | null設置者。プレビュー中(配置前)は自分。永続シーン由来などで設置者を特定できない場合は null

ItemPlacer​

PropertyTypeDescription
idstring設置者の userId。サーバーが確定した値で、常に入ります
displayNamestring | null表示名。設置者が退室済みなどでプロフィールを解決できない場合は null
avatarUrlstring | nullアイコン URL。解決できない場合は null
isLocalUserboolean自分(ローカルユーザー)が設置したものか
注記

useItem は ItemProvider 内でのみ使用可能です。Provider 外で呼び出すと例外がスローされます。プラットフォームが ItemProvider を自動的に提供するため、アイテム開発者が Provider を設定する必要はありません。

設置者の判定は id で行う

placedBy.id はバックエンドが確定した userId なので、クライアント側で偽装できません。「設置者だけが操作できる」ようにしたい場合は isLocalUser(自分かどうか)や id の比較で判定してください。一方 displayName / avatarUrl はインスタンス内の参加者情報から都度解決されるため、設置者が退室すると null になります。表示用途にとどめ、判定に使わないでください。

placedBy は @xrift/world-components 0.49.0 以降で利用できます。

設置者だけが操作できるアイテム​
import { useCallback } from 'react';
import { Interactable, useItem, useInstanceState } from '@xrift/world-components';

function PlacerOnlyCounter() {
const { id, placedBy } = useItem();
const [count, setCount] = useInstanceState(`count-${id}`, 0);

const handleReset = useCallback(() => {
// 設置者だけがリセットできる
if (!placedBy?.isLocalUser) return;
setCount(0);
}, [placedBy, setCount]);

return (
<Interactable id={`reset-${id}`} onInteract={handleReset}>
<mesh>
<boxGeometry args={[0.5, 0.5, 0.5]} />
<meshStandardMaterial color={placedBy?.isLocalUser ? 'orange' : 'gray'} />
</mesh>
</Interactable>
);
}
設置者の名前を表示する​
import { Text } from '@react-three/drei';
import { useItem } from '@xrift/world-components';

function OwnerLabel() {
const { placedBy } = useItem();
// 退室済みなどで表示名が引けない場合のフォールバックを用意する
const label = placedBy?.displayName ?? '(不明なユーザー)';

return (
<Text position={[0, 1.2, 0]} fontSize={0.1} anchorX="center">
{`設置者: ${label}`}
</Text>
);
}
配置ごとのステート管理​
import { useItem, useInstanceState } from '@xrift/world-components';

function VotingBox() {
const { id } = useItem();
const [votes, setVotes] = useInstanceState(`votes-${id}`, 0);

return (
<Interactable id={`vote-${id}`} onInteract={() => setVotes(votes + 1)}>
<mesh>
<boxGeometry args={[1, 1, 0.2]} />
<meshStandardMaterial color="green" />
</mesh>
</Interactable>
);
}

useWorldStorage​

ワールド単位のKV永続化(World Storage)を提供するフックです。ランキング・ワールド内通貨・登録情報などを、インスタンスをまたいで永続化できます。

import { useWorldStorage } from '@xrift/world-components';

function MyComponent() {
const storage = useWorldStorage();

const saveProgress = async () => {
// 共有KV(ワールドに1つの共有値)
await storage.shared.set('event_phase', '第2章');
const visits = await storage.shared.increment('total_visits', 1);

// ユーザー別KV(書き込みは自分の値のみ)
await storage.player.set('coins', 340);
const coins = await storage.player.get('coins');
};
}

戻り値​

PropertyTypeDescription
sharedSharedWorldStorage共有KV(ワールドに1つの共有値)。インスタンス参加中の認証ユーザーなら誰でも書ける
playerPlayerWorldStorageユーザー別KV。書き込みは自分の値のみ、読み取りは他人の値も可

SharedWorldStorage​

MethodTypeDescription
get(key: string) => Promise<unknown>値を取得する。存在しない場合は undefined
list() => Promise<WorldStorageEntry[]>すべてのキーと値を取得する
set(key: string, value: unknown) => Promise<void>値を保存する
increment(key: string, delta: number) => Promise<number>数値を加算し、加算後の値を返す(同時実行でも加算がロストしない)
delete(key: string) => Promise<void>値を削除する(冪等)

PlayerWorldStorage​

MethodTypeDescription
get(key: string, options?: { userId?: string }) => Promise<unknown>値を取得する。userId を指定すると他のユーザーの値を読める
list(options?: { userId?: string }) => Promise<WorldStorageEntry[]>すべてのキーと値を取得する。userId 指定で他のユーザーの値も可
set(key: string, value: unknown) => Promise<void>自分の値を保存する
increment(key: string, delta: number) => Promise<number>自分の値に数値を加算し、加算後の値を返す
delete(key: string) => Promise<void>自分の値を削除する(冪等)

制約・指針​

項目内容
保存タイミング「ゲームイベントの節目」で保存する。毎フレームの同期は useInstanceState などの揮発性の状態同期を使う
容量ワールドごと合計 10MB / 1エントリ 100KB
キー数共有 256キー / ユーザーあたり 64キー
キー形式/^[A-Za-z0-9_.\-:]{1,128}$/
レートリミット書き込みはユーザーごと 30回/分
読み取り公開(認証不要で API から読める)。秘密情報を入れないこと
ゲスト読み取りのみ(書き込みは WorldStorageError になる)
加算通貨・スコアの加算は set ではなく increment を使う

WorldStorageError​

操作が失敗すると WorldStorageError が投げられます。code プロパティで原因を判別できます。

CodeDescription
QUOTA_EXCEEDEDワールド合計容量(10MB)を超過
LIMIT_EXCEEDEDキー数上限を超過(共有: 256キー / ユーザーあたり: 64キー)
ENTRY_TOO_LARGE1エントリの上限(100KB)を超過
TYPE_MISMATCHincrement 対象の既存値が数値でない
INVALID_KEYキー形式が不正
NOT_IN_WORLDワールドのインスタンスに参加していない状態での書き込み
RATE_LIMITEDレートリミット超過
UNAUTHORIZED未認証(ゲスト)での書き込み
UNKNOWNその他のエラー

使用例​

来場者数カウンター​
import { useWorldStorage, Interactable } from '@xrift/world-components'
import { Text } from '@react-three/drei'
import { useEffect, useState } from 'react'

function VisitCounter() {
const storage = useWorldStorage()
const [visits, setVisits] = useState<number | null>(null)

useEffect(() => {
// 入場時に一度だけカウントアップ
storage.shared.increment('total_visits', 1).then(setVisits)
}, [storage])

return (
<Text position={[0, 2, 0]} fontSize={0.2} color="white">
{visits === null ? '...' : `累計来場者数: ${visits}`}
</Text>
)
}
ユーザー別のコイン管理​
import { useWorldStorage, WorldStorageError } from '@xrift/world-components'

function useCoins() {
const storage = useWorldStorage()

const addCoins = async (amount: number) => {
try {
// 同時実行でも加算がロストしないよう increment を使う
return await storage.player.increment('coins', amount)
} catch (e) {
if (e instanceof WorldStorageError && e.code === 'UNAUTHORIZED') {
console.log('ゲストは書き込みできません')
return null
}
throw e
}
}

return { addCoins }
}
注記

World Storage は永続化ストレージです。毎フレーム更新されるような値の同期には useInstanceState / useInstanceEvent を使い、World Storage への保存はゲームイベントの節目(クリア時、購入時など)に行ってください。


定数​

LAYERS​

Three.js のレイヤーシステムを活用した定数です。カメラやRaycasterのレイヤー設定に使用します。

import { LAYERS } from '@xrift/world-components';
定数名値説明
LAYERS.DEFAULT0デフォルトレイヤー(すべてのオブジェクトが初期状態で属する)
LAYERS.FIRST_PERSON_ONLY9一人称視点のみ表示(VRMFirstPerson用)
LAYERS.THIRD_PERSON_ONLY10三人称視点のみ表示(VRMFirstPerson用)
LAYERS.INTERACTABLE11インタラクト可能オブジェクト(Raycast対象)
LAYERS.GRABBABLE14掴めるオブジェクト(Grabbable のRaycast対象)

関連する型​

type LayerName = 'DEFAULT' | 'FIRST_PERSON_ONLY' | 'THIRD_PERSON_ONLY' | 'INTERACTABLE' | 'GRABBABLE';
type LayerNumber = 0 | 9 | 10 | 11 | 14;

ユースケース​

  • Raycasterでインタラクション対象を検出する際のレイヤー設定
  • VRモードでの一人称/三人称の表示切り替え