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

xrift.json 設定

プロジェクトルートの xrift.json でワールドの設定を行います。

設定例​

{
"world": {
"distDir": "./dist",
"title": "My World",
"description": "サンプルワールドです",
"thumbnailPath": "thumbnail.png",
"buildCommand": "npm run build",
"ignore": [
"**/.DS_Store",
"**/Thumbs.db",
"**/*.map"
],
"camera": {
"near": 0.1,
"far": 1000
},
"outputBufferType": "UnsignedByteType",
"permissions": {
"allowedDomains": ["api.example.com"],
"allowedCodeRules": ["no-network-without-permission"]
}
}
}

設定項目​

フィールド型説明
distDirstringアップロードするビルド成果物のディレクトリ
titlestringワールドのタイトル(未設定の場合、アップロード時に入力)
descriptionstringワールドの説明(未設定の場合、アップロード時に入力)
thumbnailPathstringサムネイル画像のパス(distDir からの相対パス)
buildCommandstringアップロード前に実行するビルドコマンド
ignorestring[]アップロードから除外するファイルの glob パターン
physicsobjectワールドの物理設定
cameraobjectワールドのカメラクリッピング設定
outputBufferTypestringWebGLRenderer の出力バッファタイプ
itemsstring[]ワールドに最初から置くアイテム(<Item itemId>)の id の一覧
permissionsobjectワールドが必要とする権限設定

各項目の詳細​

distDir​

アップロード対象のディレクトリを指定します。

{
"world": {
"distDir": "./dist"
}
}

title / description​

ワールドのタイトルと説明を設定します。これらはオプショナルですが、設定しておくと xrift upload world 実行時のプロンプトでデフォルト値として使用されます。

{
"world": {
"title": "My Awesome World",
"description": "インタラクティブな3Dワールドです"
}
}

thumbnailPath​

ワールドのサムネイル画像を指定します。distDir からの相対パスで指定します。

{
"world": {
"distDir": "./dist",
"thumbnailPath": "thumbnail.png"
}
}

この場合、dist/thumbnail.png がサムネイルとして使用されます。

推奨サイズ: 1280x720 ピクセル

buildCommand​

xrift upload world 実行時に、アップロード前に自動実行されるコマンドです。

{
"world": {
"buildCommand": "npm run build"
}
}

これを設定しておくと、手動でビルドする必要がなくなります。

ignore​

アップロードから除外するファイルを glob パターンで指定します。

{
"world": {
"ignore": [
"**/.DS_Store",
"**/Thumbs.db",
"**/*.map"
]
}
}

physics​

ワールドの物理動作をカスタマイズできます。

設定型デフォルト説明
gravitynumber9.81重力の強さ(正の値、地球=9.81、月=1.62)
allowInfiniteJumpbooleantrue無限ジャンプを許可するか
allowFlybooleantrue浮遊モード(フライモード)を許可するか
respawnThresholdnumber-10この高さ(Y 座標)を下回るとスポーン地点へ戻す

基本設定​

{
"world": {
"physics": {
"gravity": 9.81,
"allowInfiniteJump": true
}
}
}

アスレチックワールド(無限ジャンプ禁止)​

{
"world": {
"physics": {
"allowInfiniteJump": false
}
}
}

浮遊モードを禁止する​

アスレチックや迷路など、飛んで越えられると困るワールドで使います。

{
"world": {
"physics": {
"allowFly": false
}
}
}

リスポーンする高さを変える​

床が -10 より低い位置にあるワールドや、下へ落ちていく演出のあるワールドでは、リスポーンする高さを下げます。

{
"world": {
"physics": {
"respawnThreshold": -100
}
}
}
警告

respawnThreshold はスポーン地点より低くしてください。スポーン地点より高いと、戻った瞬間にまた下回るため、リスポーンが繰り返されて動けなくなります。

低重力ワールド(月の重力)​

{
"world": {
"physics": {
"gravity": 1.62
}
}
}

高重力ワールド(木星の重力)​

{
"world": {
"physics": {
"gravity": 24.79
}
}
}

camera​

ワールドのカメラクリッピング距離をカスタマイズできます。

設定型説明
nearnumberニアクリップ距離(カメラに近すぎるオブジェクトを非表示にする距離)
farnumberファークリップ距離(カメラから遠すぎるオブジェクトを非表示にする距離)

基本設定​

{
"world": {
"camera": {
"near": 0.1,
"far": 1000
}
}
}

広大なワールド(遠くまで描画)​

{
"world": {
"camera": {
"far": 5000
}
}
}

精密なワールド(近距離の描画精度を上げる)​

{
"world": {
"camera": {
"near": 0.01
}
}
}

outputBufferType​

WebGLRenderer の出力バッファタイプを指定します。ポストプロセッシングや HDR レンダリングの精度に影響します。

値説明
UnsignedByteType8bit 整数(デフォルト。通常のレンダリングに適する)
HalfFloatType16bit 浮動小数点(HDR やポストプロセッシングに適する)
FloatType32bit 浮動小数点(最高精度。GPU 負荷が高い)
{
"world": {
"outputBufferType": "HalfFloatType"
}
}

items​

ワールドに最初から置くアイテム(<Item itemId>)の id を宣言します。ここに書いた id だけが本番で読まれます(入室時の先読みと、訪問者側での配信 URL の解決がこの一覧から行われます)。

{
"world": {
"items": [
"2a69ded4-d913-4359-8c1f-eac83a982b0c",
"a454d074-7f1c-416a-b181-19a63b79f432"
]
}
}
  • 宣言できるのは 自分が作ったアイテムか、ライブラリに入れたアイテム だけです(マーケットで入手してください)。それ以外を書くとアップロードが失敗します
  • 50 個までです
  • 作者が新しい版を出すと、ワールドに置いたアイテムも自動で新しくなります
  • xrift upload はビルド成果物の <Item itemId> を拾って宣言と突き合わせ、宣言に無い id があればアップロード前に止めます。<Item> で使っていない id が拾われた誤検知のときだけ xrift upload --skip-item-scan で飛ばせます
  • ローカル開発(xriftDev())でも宣言に無い id は本番と同じ「宣言されていない」の仮の箱になります。追記してリロードすれば効きます

アイテムの置き方は world-components の Item を参照してください。

permissions​

ワールドが必要とする権限を宣言します。ここで宣言された権限は、ユーザーがインスタンスに入室する際に承認画面として表示されます。

設定型説明
allowedDomainsstring[]ワールドが通信する外部ドメインのリスト
allowedCodeRulesstring[]緩和が必要なコードセキュリティルールのリスト

基本設定​

{
"world": {
"permissions": {
"allowedDomains": ["api.example.com", "cdn.example.com"],
"allowedCodeRules": ["no-navigator-access", "no-network-without-permission"]
}
}
}

allowedDomains​

ワールドのコードが通信する外部ドメインを指定します。@xrift/code-security のコード解析により、許可されていないドメインへの通信は検出・ブロックされます。

allowedCodeRules​

@xrift/code-security のコード検査で止められるルールのうち、ワールドの機能に必要なものを宣言して緩和します。宣言したルールは入室時の承認画面に表示され、訪問者が同意して入室します。緩和できるのは次の「緩和できるルール」だけです。

緩和できるルール​
ルール緩和される内容
no-new-functionFunction コンストラクタによるコードの動的生成
no-string-timeoutsetTimeout / setInterval への文字列引数
no-javascript-blobJavaScript の Blob を使ったスクリプトの動的生成
no-obfuscation難読化されたコードパターン
no-network-without-permission接続先をコードから読み取れない fetch や WebSocket 等の通信(接続先が文字列で書かれている通信は allowedDomains で照合されます)
no-rtc-connectionWebRTC(RTCPeerConnection)による接続(下記)
no-dangerous-dominnerHTML やスクリプト要素の挿入
no-navigator-access位置情報・カメラ・マイク・クリップボード等へのアクセス
no-global-overridewindow / document 等のグローバルオブジェクトの書き換え
緩和できないルール​

次のルールは allowedCodeRules に書いても緩和されず、違反があるとアップロードが通りません。

ルール禁止される内容
no-evaleval() による文字列のコード実行
no-external-import外部 URL からの JavaScript モジュール読み込み
no-storage-accesslocalStorage / sessionStorage へのアクセス
no-cookie-accessCookie の読み書き
no-indexeddb-accessIndexedDB へのアクセス
no-storage-event他タブのストレージ変更イベントの監視
no-sensitive-api-overridefetch 等のセキュリティ上重要な API の書き換え
no-prototype-pollution組み込みオブジェクトのプロトタイプ変更

データを保存したいときは useWorldStorage を使ってください。

allowedDomains に無い接続先への通信(no-unauthorized-domain)も、ルールの緩和では許可できません。接続先を allowedDomains に足してください。

WebRTC を使う​

RTCPeerConnection を使うには no-rtc-connection の宣言が要ります。WebRTC では接続相手に IP アドレスが伝わるため、入室時の承認画面で「WebRTC 接続」として訪問者の同意を取ります。

{
"world": {
"permissions": {
"allowedDomains": ["stun.l.google.com"],
"allowedCodeRules": ["no-rtc-connection"]
}
}
}
  • iceServers に書いた STUN / TURN サーバーのホストは allowedDomains と照合されます。ライブラリが既定で使う STUN / TURN サーバーも同じなので、そのホストも書いてください
  • iceServers を変数や API の応答から渡すと接続先を確かめられないため、no-network-without-permission の宣言も要ります