XRift World Development Guide

A guide for creating and modifying WebXR worlds for the XRift platform.

References

• [API Reference](references/api-reference.md) - Full specification of all hooks, components, and constants in @xrift/world-components
• [Code Templates](references/code-templates.md) - Implementation patterns for GLB models, textures, Skybox, interactions, and more
• [Type Definitions](references/type-definitions.md) - Type definitions for User, PlayerMovement, VRTrackingData, TeleportDestination, WorldInfo, InstanceInfo, ConfirmOptions, Tag, VideoState, LogEntry, PhysicsConfig, CameraConfig, VoiceVolumeOverrideContextValue

Critical Rules (Must Follow)

1. Always use baseUrl from useXRift() when loading assets
2. Place asset files in the public/ directory
3. baseUrl includes a trailing /, so join with ${baseUrl}path (${baseUrl}/path is WRONG)

// Correct
const { baseUrl } = useXRift()
const model = useGLTF(`${baseUrl}robot.glb`)

// Wrong
const model = useGLTF('/robot.glb')           // Absolute path - NG
const model = useGLTF(`${baseUrl}/robot.glb`) // Extra / - NG

Project Overview

• Purpose: WebXR worlds for the XRift platform
• Tech Stack: React Three Fiber + Rapier physics engine + Module Federation
• How It Works: Uploaded to CDN, dynamically loaded by the frontend

Project Structure

xrift-world-template/
├── public/              # Asset files (place directly, no subdirectories needed)
│   ├── model.glb
│   ├── texture.jpg
│   └── skybox.jpg
├── src/
│   ├── components/      # 3D components
│   ├── World.tsx        # Main world component
│   ├── dev.tsx          # Development entry point
│   ├── index.tsx        # Production export
│   └── constants.ts     # Constants
├── .triplex/            # Triplex (3D editor) config
├── xrift.json           # XRift CLI config
├── vite.config.ts       # Build config (Module Federation)
└── package.json

xrift.json Configuration

physics (Physics Settings)

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

Examples:

• Obstacle course world: "allowInfiniteJump": false to add fall risk
• Low gravity world: "gravity": 1.62 (Moon gravity) for floaty movement
• High gravity world: "gravity": 24.79 (Jupiter gravity) for heavy movement

camera (Camera Settings)

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

Examples:

• Vast world: "far": 5000 to render distant objects
• Precise world: "near": 0.01 for higher near-range rendering precision

outputBufferType (Output Buffer Type)

Specifies the output buffer type for WebGLRenderer. Affects post-processing and HDR rendering precision.

{
  "outputBufferType": "HalfFloatType"
}

permissions (Permission Settings)

Declares permissions required by the world. Declared permissions are shown to users as an approval screen when entering an instance.

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

allowedCodeRules

Rules defined by @xrift/code-security analyzer. By default, unsafe operations are blocked but can be relaxed when required.

Command Reference

# Development
npm run dev        # Start dev server (http://localhost:5173)
npm run build      # Production build
npm run typecheck  # Type checking

# XRift CLI
xrift login        # Authenticate
xrift create world # Create new world project
xrift upload       # Upload (auto-detect from xrift.json)
xrift whoami       # Check logged-in user
xrift logout       # Log out

Development Environment

Run npm run dev to start the dev server. You can navigate and test the world in first-person view.

Interactable component click behavior can also be tested in the dev environment (the center Raycaster detects the LAYERS.INTERACTABLE layer).

dev.tsx Structure

src/dev.tsx is the development-only entry point. It is not included in the production build.

Note: XRiftProvider is not needed in production (the frontend wraps it automatically).

Dependencies

Required (peerDependencies)

• react / react-dom ^19.0.0
• three ^0.182.0
• @react-three/fiber ^9.3.0
• @react-three/drei ^10.7.3
• @react-three/rapier ^2.1.0

XRift-specific

• @xrift/world-components - XRift hooks and components

Module Federation Shared パッケージ

ホスト（xrift.net）と shared で共有されるパッケージ。ワールドの vite.config.ts で shared に宣言すれば、ワールドチャンクにバンドルされずホストから提供される。

three/addons の注意

• three/addons バレルを shared にすると Lottie 由来の eval がバンドルに含まれるため、サブパス単位で shared にしている
• ワールド側でも three/addons/loaders/DRACOLoader.js のようにサブパスで import & shared 宣言する

// vite.config.ts — shared の設定例（xrift-world-template 準拠）
federation({
  name: 'xrift_world_template',
  filename: 'remoteEntry.js',
  exposes: {
    './World': './src/index.tsx',
  },
  shared: {
    react: { singleton: true, requiredVersion: '^19.0.0' },
    'react-dom': { singleton: true, requiredVersion: '^19.0.0' },
    'react-dom/client': { singleton: true },
    'react/jsx-runtime': { singleton: true },
    three: { singleton: true, requiredVersion: '^0.176.0' },
    // three/addons はバレルではなくサブパス単位で宣言する
    'three/addons/loaders/DRACOLoader.js': { singleton: true },
    '@react-three/fiber': { singleton: true, requiredVersion: '^9.3.0' },
    '@react-three/rapier': { singleton: true, requiredVersion: '^2.1.0' },
    '@react-three/drei': { singleton: true, requiredVersion: '^10.7.3' },
    '@xrift/world-components': { singleton: true, requiredVersion: '^0.1.0' },
  },
}),

Troubleshooting

"useXRift must be used within XRiftProvider"

Cause: Not wrapped with XRiftProvider

Solution:

• Check that src/dev.tsx uses XRiftProvider
• When using Triplex: check .triplex/provider.tsx

Assets fail to load

Cause: Not using baseUrl, or incorrect path concatenation

Solution:

// Correct
const { baseUrl } = useXRift()
const model = useGLTF(`${baseUrl}robot.glb`)

// Wrong
const model = useGLTF('/robot.glb')
const model = useGLTF(`${baseUrl}/robot.glb`)

Physics not working

Cause: Not wrapped with Physics component, or missing RigidBody

Solution:

<Physics>
  <RigidBody type="fixed">  {/* or "dynamic" */}
    <mesh>...</mesh>
  </RigidBody>
</Physics>

Links

• XRift Documentation
• XRift CLI (GitHub)
• React Three Fiber
• Rapier Physics
• Triplex (Visual Editor)

Example Implementations

• GLB model: src/components/Duck/index.tsx
• Skybox: src/components/Skybox/index.tsx
• Animation: src/components/RotatingObject/index.tsx
• Interaction: src/components/InteractableButton/index.tsx
• User tracking: src/components/RemoteUserHUDs/index.tsx
• Teleport: src/components/TeleportPortal/index.tsx
• Main world: src/World.tsx