Skip to main content

xrift.json Configuration

Configure your world settings in xrift.json at the project root.

Configuration Example​

{
"world": {
"distDir": "./dist",
"title": "My World",
"description": "This is a sample world",
"thumbnailPath": "thumbnail.png",
"buildCommand": "npm run build",
"ignore": [
"**/.DS_Store",
"**/Thumbs.db",
"**/*.map"
],
"outputBufferType": "UnsignedByteType",
"permissions": {
"allowedDomains": ["api.example.com"],
"allowedCodeRules": ["no-network-without-permission"]
}
}
}

Configuration Items​

FieldTypeDescription
distDirstringDirectory of build artifacts to upload
titlestringWorld title (if not set, input required at upload)
descriptionstringWorld description (if not set, input required at upload)
thumbnailPathstringPath to thumbnail image (relative to distDir)
buildCommandstringBuild command to execute before upload
ignorestring[]Glob patterns of files to exclude from upload
physicsobjectWorld physics settings
cameraobjectWorld camera clipping settings
outputBufferTypestringWebGLRenderer output buffer type
itemsstring[]IDs of items placed in the world from the start (<Item itemId>)
permissionsobjectPermissions required by the world

Details of Each Item​

distDir​

Specifies the directory to upload.

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

title / description​

Sets the world title and description. These are optional, but if set, they will be used as default values in the prompt when running xrift upload world.

{
"world": {
"title": "My Awesome World",
"description": "An interactive 3D world"
}
}

thumbnailPath​

Specifies the thumbnail image for the world. Specify as a relative path from distDir.

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

In this case, dist/thumbnail.png will be used as the thumbnail.

Recommended Size: 1280x720 pixels

buildCommand​

A command that is automatically executed before uploading when running xrift upload world.

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

Setting this eliminates the need to build manually.

ignore​

Specifies files to exclude from upload using glob patterns.

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

physics​

You can customize the physics behavior of the world.

SettingTypeDefaultDescription
gravitynumber9.81Strength of gravity (Positive value, Earth=9.81, Moon=1.62)
allowInfiniteJumpbooleantrueWhether to allow infinite jumping
allowFlybooleantrueWhether to allow fly mode
respawnThresholdnumber-10Players who fall below this height (Y) are sent back to the spawn point

Basic Settings​

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

Athletic World (No Infinite Jump)​

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

Disable Fly Mode​

Use this for athletic courses, mazes, and other worlds where flying over obstacles would break the experience.

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

Change the Respawn Height​

If your floor sits below -10, or your world has players falling a long way on purpose, lower the respawn height.

{
"world": {
"physics": {
"respawnThreshold": -100
}
}
}
warning

Keep respawnThreshold below your spawn point. If it is higher, players fall below it again as soon as they respawn and get stuck respawning over and over.

Low Gravity World (Moon Gravity)​

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

High Gravity World (Jupiter Gravity)​

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

outputBufferType​

Specifies the output buffer type for WebGLRenderer. This affects the precision of post-processing and HDR rendering.

ValueDescription
UnsignedByteType8-bit integer (default, suitable for standard rendering)
HalfFloatType16-bit float (suitable for HDR and post-processing)
FloatType32-bit float (highest precision, higher GPU cost)
{
"world": {
"outputBufferType": "HalfFloatType"
}
}

items​

Declares the IDs of items placed in the world from the start (<Item itemId>). Only the IDs listed here are loaded in production (the preload on entry and the resolution of bundle URLs for visitors both use this list).

{
"world": {
"items": [
"2a69ded4-d913-4359-8c1f-eac83a982b0c",
"a454d074-7f1c-416a-b181-19a63b79f432"
]
}
}
  • You can only declare items you created or added to your library (acquire them on the marketplace). Declaring anything else fails the upload
  • Up to 50 items
  • When the author publishes a new version, the items placed in the world update automatically
  • xrift upload scans the built bundle for <Item itemId> and compares it with this list; if an ID is missing, the upload stops before anything is sent. Use xrift upload --skip-item-scan only when an ID that is not used by <Item> was picked up by mistake
  • During local development (xriftDev()), undeclared IDs show the same "not declared" placeholder as production. Add the ID and reload the page

See Item in world-components for how to place them.

permissions​

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

SettingTypeDescription
allowedDomainsstring[]List of external domains the world communicates with
allowedCodeRulesstring[]List of code security rules to relax

Basic Settings​

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

allowedDomains​

Specifies external domains that the world's code communicates with. Communication to unauthorized domains is detected and blocked by @xrift/code-security code analysis.

allowedCodeRules​

Declares which rules of the @xrift/code-security code check should be relaxed because the world needs them. Declared rules are shown on the approval screen when entering, and visitors enter after consenting. Only the rules listed under "Relaxable rules" can be relaxed.

Relaxable rules​
RuleWhat it relaxes
no-new-functionDynamic code generation with the Function constructor
no-string-timeoutString arguments to setTimeout / setInterval
no-javascript-blobDynamic script generation with JavaScript Blobs
no-obfuscationObfuscated code patterns
no-network-without-permissionfetch, WebSocket, etc. whose destination cannot be read from the code (requests with a string destination are checked against allowedDomains)
no-rtc-connectionWebRTC (RTCPeerConnection) connections (see below)
no-dangerous-dominnerHTML and script element injection
no-navigator-accessAccess to geolocation, camera, microphone, clipboard, etc.
no-global-overrideOverriding global objects (window, document, etc.)
Rules that cannot be relaxed​

The following rules are not relaxed even if listed in allowedCodeRules. Any violation makes the upload fail.

RuleWhat it forbids
no-evalExecuting strings as code with eval()
no-external-importImporting JavaScript modules from external URLs
no-storage-accessAccess to localStorage / sessionStorage
no-cookie-accessReading and writing cookies
no-indexeddb-accessAccess to IndexedDB
no-storage-eventListening to storage events from other tabs
no-sensitive-api-overrideOverriding security-critical APIs such as fetch
no-prototype-pollutionModifying built-in object prototypes

To persist data, use useWorldStorage.

Requests to destinations not in allowedDomains (no-unauthorized-domain) cannot be allowed by relaxing a rule either. Add the destination to allowedDomains.

Using WebRTC​

Using RTCPeerConnection requires declaring no-rtc-connection. WebRTC reveals your IP address to the peer, so visitors are asked to consent to a "WebRTC connection" on the approval screen when entering.

{
"world": {
"permissions": {
"allowedDomains": ["stun.l.google.com"],
"allowedCodeRules": ["no-rtc-connection"]
}
}
}
  • The hosts of the STUN / TURN servers in iceServers are checked against allowedDomains. The same applies to STUN / TURN servers a library uses by default, so list those hosts too
  • If you pass iceServers from a variable or an API response, the destinations cannot be verified, so you also need to declare no-network-without-permission