📃 All-in-one-spec

 9th November 2026 at 11:59am

Download HTML, TXT

stream:    Guerilla Standardisation
area:      Internet
status:    informational
author:    Leon van Kammen
workgroup: Internet Engineering Task Force
value:     XRFRAGMENTS-leonvankammen-00

Abstract

Version: 0.6

An open specification for hyperlinking & deeplinking 3D fileformats. This is a specification for interactive URI-controllable 3D files, to enable spatial webs for local-first XR hypermedia browsers.
XR Fragments allows us to better use implicit metadata inside 3D scene(files), by mapping it to proven technologies like URI Fragments.

Almost every idea in this document is demonstrated at https://xrfragment.org

Introduction

How can we add more control to existing text and 3D scenes, without introducing new dataformats?
Historically, there's many attempts to create the ultimate 3D fileformat.
The lowest common denominator is: designers describing/tagging/naming things using plain text.
XR Fragments exploits the fact that all 3D models & markuplanguages already contain such metadata:

** Deeplinking 3D objects by mapping objectnames to URI fragments**

For a better-readable, better-updated spec see the website https://xrfragment.org

How does it work

XR Fragments utilizes URLs on various levels:

  1. for 3D viewers/browser to manipulate the camera or objects of a 3D scene (via URI fragments)
  2. implicitly: by mapping 3D objectnames (of a 3D scene/file) to URI fragments (3D deeplinking)
  3. explicitly: by scanning href metadata inside 3D scene-files to enable interactions
  4. explicitly: by scanning for XR hints metadata inside 3D scene-files to distinguish contextual rendering (AR vs VR e.g.)
  5. externally: progressively enhance a 3D (file) into an experience via sidecarfiles

Aspect 1 was pioneered and implemented by JanusXR / James Baicoianu via janusweb well before the formal specification was established. As a key architect of these early concepts, James’s work laid the groundwork for the standard we use today. We owe him a great deal of thanks for his early contributions.

Applications can adopt XR Fragments at various levels, depending on application needs. However, Level1 is considered the soul of XR fragments: other levels are optional and not required to consider something 'XR Fragment compatible' (3D objects & camera reference-able via URL).

Spatial Referencing 3D objects

3D files/scenes contain an hierarchy of objects.
XR Fragments assumes the following objectname-to-URI-Fragment mapping, in order to deeplink 3D objects:


  my.io/scene.fbx   (or my.io/scene.html delivering a three.js scene)
	
  +─────────────────────────────+
  │ sky                         │  src: http://my.io/scene.fbx#sky          (includes building,mainobject,floor)
  │ +─────────────────────────+ │ 
  │ │ building                │ │  src: http://my.io/scene.fbx#building     (includes mainobject,floor)
  │ │ +─────────────────────+ │ │
  │ │ │ mainobject          │ │ │  src: http://my.io/scene.fbx#mainobject   (includes floor)
  │ │ │ +─────────────────+ │ │ │
  │ │ │ │ floor           │ │ │ │  src: http://my.io/scene.fbx#floor        (just floor object)
  │ │ │ │                 │ │ │ │
  │ │ │ +─────────────────+ │ │ │
  │ │ +─────────────────────+ │ │
  │ +─────────────────────────+ │
  +─────────────────────────────+

Every 3D fileformat supports named 3D objects, and this name allows URLs (fragments) to reference them (and their children objects).

In case of the href-attribute (see level2: explicit hyperlinks) we use this reference to teleport the player/camera to that location (of the referenced object).

What does it solve

It solves:

  1. addressibility and hypermediatic navigation of 3D scenes/objects: URI Fragments using src/href spatial metadata
  2. unlocking spatial potential of the (originally 2D) hashtag (which jumps to a chapter) for navigating XR documents
  3. refraining from introducing an opiniated scripting-engine for mundane tasks (and preventing its inevitable security-headaches)

XR Fragments views XR experiences through the lens of 3D deeplinked URI's, rather than thru a specific scripting- or game-engine, or protocol-specific browsers (https webbrowser e.g.). To aid adoption, the standard comprises of various (optional) support-levels, which incorporate existing standards like W3C Media Fragments and URI Templates (RFC6570) to promote spatial addressibility, sharing, navigation, filtering and databinding objects for (XR) Browsers.

XR Fragments is in a sense, a heuristical 3D format or meta-format, which leverages heuristic rules derived from any 3D scene or well-established 3D file formats, to extract meaningful features from scene hierarchies.
These heuristics, enable features that are both meaningful and consistent across different scene representations, allowing higher interop between fileformats, 3D editors, viewers and game-engines.

Level0: file

Capable 3D fileformats

glTF, usdz, obj, collada, THREE.json, X3D e.g. are capable of XR Fragments.
The requirements of any 3D file is: a scenegraph with 1 or more named objects.

XR Fragment Compatible

A 3D scene-file can be considered XR Fragment-compatible when it matches one of these heuristics

  1. implicit: it has at least one sidecar-file
  2. explicit: an object has an href extra.
  3. explicit: it has at least one system folder (one objectname starting with underscore)
  • = last wins in case of non-unique names

Loading a file

  1. application sidecar file
  2. next file (slideshow)
  3. sidecar files
  4. timelines

When an XR player (myplayer.exe e.g.) is launched (without a specific file), it should poll for a default file (myplayer.glb e.g.).

Sidecar files

These are optional auto-loaded files to enable hasslefree publishing of XR Movie applications.
The application should poll for only those 3D file-formats it supports.


Webviewer example

  1. https://my.org/demo.html loads demo.glb
  2. https://my.org/demo.html?file=foo.glb loads foo.glb

Linux/Mac example

$ ls -la
myplayer
myplayer.glb
$ ./myplayer          <-- automatically loads myplayer.glb
$ ./myplayer foo.glb  <-- no sidecar logic

Windows example

> dir
myplayer.exe
myplayer.glb
> myplayer.exe         <-- automatically loads myplayer.glb
> myplayer.exe foo.glb <-- no sidecar logic

NOTE: after loading a file the usual sidecar file-logic applies

Slideshow

when a loaded file ends with a number (foo1.glb) automatically check for the existence of foo2.glb)

This will allow simple 3D slideshows:

foo1.glb
foo2.glb
foo3.glb
foo4.glb

But with [sidecar files](#sidecar files) this also allows for XR movie series:

foo-episode1.glb
foo-episode1.vtt
foo-episode1.ogg

foo-episode2.glb
foo-episode2.vtt
foo-episode2.ogg

and so on

F3D

The opensource F3D 3D viewer supports level0 'next file' by invoking:

$ f3d --animation-autoplay foo-episode*.glb

In a similar spirit of the XR Fragment spec: F3D supports multiple 3D file formats, so the 3D slideshow can exist of different 3D fileformats.

Sidecar files

These are optional auto-loaded files to enable hasslefree XR Movies:


via href metadata

scene.glb   <--- 'href' extra [heuristic] detected inside!
scene.png   <--- then poll preview thumbnail
scene.ogg   <--- then poll soundtrack to plays when global 3D animation starts)
scene.vtt   <--- then poll fallback subtitles for accessibility or screenreaders
scene.json  <--- then poll sidecar JSON-file with explicit metadata
heuristics
  1. if at least one `href` custom property/extra is found in a 3D scene
  2. The viewer should poll for the above mentioned sidecar-file extensions (and present accordingly)

via chained extension

scene.xrf.glb   <--- 'href' extra [heuristic] detected inside!
scene.xrf.png   <--- then poll preview thumbnail
scene.xrf.ogg   <--- then poll soundtrack to plays when global 3D animation starts)
scene.xrf.vtt   <--- then poll fallback subtitles for accessibility or screenreaders
scene.xrf.json  <--- then poll sidecar JSON-file with explicit metadata

A fallback-mechanism to turn 3D files into XR Movies without editing them.

heuristics

the chained-extension heuristic .xrf. should be present in the filename (scene.xrf.glb e.g.)


JSON sidecar-file

NOTE: the following approach is only recommended for archivist/userupload scenarios where the 3D file itself should not be altered.

For developers, a json-sidecar-file can allow for defining explicit XR Fragments metadata (>level1), outside of the 3D file. This can be done via (objectname/metadata) key/value-pairs in a JSON sidecar-file:

{
  "aria-description": "description of scene",
  "button": {
    "href": "#roomB",
    "aria-description": "description of room"
  }
}

This will make object button clickable, and teleport the user to object roomB.

So after loading experience.glb the existence of experience.json is detected, to apply the explicit metadata.
The sidecar will define (or override already existing) extras, which can be handy for multi-user platforms (offer 3D scene customization/personalization to users).

In THREE.js-code this would boil down to:

 scene.userData['aria-description'] = "description of scene"
 scene.getObjectByName("button").userData.href = "#roomB"

now the XR Fragments parser can process the XR Fragments userData 'extras' in the scene

multilanguage example

Applications or webservers can use symbolic links or (webpaths) for language-directories:

scene.glb   
scene.json  
es/scene.glb --> ../scene.glb
es/scene.png
es/scene.ogg
es/scene.vtt
es/scene.json --> ../scene.json

However, embedding the multilanguage postfixes are preferred for portability reasons: see multilangual

via subdocuments/xattr

More secure protocols (Nextgraph e.g.) don't allow for simply polling files. In such case, subdocuments or extended attributes should be polled:

NOTE: in the examples below we use the href-heuristic, but also the .xrf. chained-extension applies here.

myspreadsheet.ods
└── explainer.glb      <--- 'href' extra [heuristic] detected inside!
    ├── explainer.ogg  (soundtrack to play when global 3D animation starts)
    ├── explainer.png  (preview thumnbnail)
    ├── explainer.json (sidecar JSON-file with explicit metadata)
    └── explainer.vtt  (subtitles for accessibility or screenreaders)

If only extended attributes (xattr) are available, the respective referenced file can be embedded:

$ setfattr -n explainer.ogg -v "soundtrack.ogg" explainer.glb
$ setfattr -n explainer.png -v "thumbnail.png" explainer.glb
$ setfattr -n explainer.vtt -v "subtitles.vtt" explainer.glb

NOTE: Linux's setfattr/getfattr is xattr on mac, and Set-Content/Get-content on Windows. See pxattr for lowlevel access.

when a loaded file contains a timeline (animations/subtitles e.g.), then:

All timelines must play (looped) by default (to enable XR Movies)

Unless an object has multiple animations (actions e.g.), then just play the first or with name default.

protocol:// my.org/world.glb #room2

URLs are the heart of XR Fragment-based 3D Hypermedia:

  • it allows navigating the XR browser to a (different) 3D scene (world.glb e.g.)
  • it allows teleporting the user to a different location (room2 e.g.)
  • it allows back/forward navigation
  • it allows addressibility (for 3d objects inside a file)

Examples:

https://linux.world/#roomF&t=1,100
linuxapp://conference/nixworkshop?newuser#roomC&t=2,200
androidapp://page1?tutorial#roomB&t=1,100

Implicit and Explicit adressibility is the core of the XR Fragments spec, as well as user teleportation:

  1. implicit deeplinks
  2. portal rendering
  3. teleport camera spawnpoint
  4. XRF microformat

Software uses level1 for deeplinking objects, or to teleport the user: here's pseudocode for a level1 XR Fragments browser in THREE.js:

// by default the (VR) user gets position at 0,0,0 at the loaded scene (+VR userheight)

url   = 'world.glb#roomB&car'
file  = url.split("#")[0] 
xrf   = new URLSearchParams( url.split("#")[1] )
refs  = ([...xrf.keys()]).filter( (k) => !k.match(/(t)/) ) // skip mediafrags

// set last (nonoperator) objectname as camera-location
for( i in refs ){
  scene.setActiveCameraByName(refs[i]) // teleport
  obj = extractObject(scene,refs[i])   // or purely deeplink
}

for robust parsing of XR Fragments use a http query-language parser, or the polyglot parser



Below is the related section of the spec (full spec here: HTML, TXT)



For more info see How it works

Every 3D object, material or camera can be adressed by URI fragments (#myobject e.g.) which are derived from the 3D scene objectnames (implicit metadata).
These are inferred at runtime from the 3D scene-nodes (object names, object metadata etc).

Free fragments and features generated for you..How great is that? 🎉


  my.io/scene.usdz                 Embeddable as:
  +─────────────────────────────+
  │ sky                         │  src: http://my.io/scene.udsz#sky          (includes building,mainobject,floor)
  │ +─────────────────────────+ │ 
  │ │ building                │ │  src: http://my.io/scene.udsz#building     (includes mainobject,floor)
  │ │ +─────────────────────+ │ │
  │ │ │ mainobject          │ │ │  src: http://my.io/scene.udsz#mainobject   (includes floor)
  │ │ │ +─────────────────+ │ │ │
  │ │ │ │ floor           │ │ │ │  src: http://my.io/scene.udsz#floor        (just floor object)
  │ │ │ │                 │ │ │ │
  │ │ │ +─────────────────+ │ │ │  href: http://my.io/scene.udsz#-mainobject (hides mainobject when clicked)
  │ │ +─────────────────────+ │ │
  │ +─────────────────────────+ │
  +─────────────────────────────+

Fragments (#building e.g.) allow for very convenient, guess-able filters to reference/show/hide objects within a 3D scene.

For more examples see filters and the reference-menu (by feature)

Below is the related section of the spec (full spec here: HTML, TXT)


default portals

To render a portal, the easiest way is JanusXR-style portals:

clickable planes which teleport the user to a different position or file. This is the whole idea behind href and XRF microformat metadata.

result1.glbresult2.glb

In blender you can create a plane, and attach a href hyperlink to it

non-euclidian portals

NOTE: this **extension** is optional, and can be used in a progressive enchanched way across (non)supporting viewers.

Undefined widget 'videojs'

Portals avoid XR clutter. Rinsema's effect: "To observe much is to absorb little"

A materialless mesh with the following heuristics will render as an immersive portal:

PortaltypeHeuristicsResult
XR lenschild objects in materialless meshobjects are only visible in mesh
XR portalhref valuethe other mesh will be used as camera-point
(location will have 1.6m camera-height added)
NOTE: in 3D engines this is refererred to as rendering to a designated stencil.

You can see this demonstrated in index.glb or the demo-video & viewer below:

NOTE: designers are adviced to always accompany a button to the portal (see video), to keep things backwards compatible with barebones (non-portal-supporting) XRF viewers.

Examples

Example scene hierarchy:



  my.io/scene.usdz
  +─────────────────────────────+
  │ world1                      │  
  │ +─────────────────────────+ │ 
  │ │ myportalmesh------------------+ href: #portalpoint  
  | |                         | |     
  │ +─────────────────────────+ │   myportalmesh renders world2
  │ world2                      │   inside from portalpoint's of view
  │ +─────────────────────────+ │   (if myportalmesh has no material)
  │ │ cube                    │ │  
	| | portalpoint             | |
  │ +─────────────────────────+ │	
  +─────────────────────────────+

Lenses

Will render objects inside of the portal (children) ONLY inside of the portal.

Example scene hierarchy:



  my.io/scene.usdz
  +─────────────────────────────+
  │ world1                      │  
  │ +─────────────────────────+ │ 
  │ │ myportal                | |  myportal renders someinfo inside  
	| | +──────────+            | |  as portal  
  | | | someinfo |            | |  (if myportal has no material)
  | | +──────────+            | |
  │ +─────────────────────────+ │
  +─────────────────────────────+

Demo viewer

Press the 'Teleport down there'-button (in the lens) and witness the portals afterwards yourself:

set the position of the camera.

level1 spawnpoints

protocol :// my.org/world.glb #bar

Spawn user at object (with name) bar after loading (and replacing the current scene with) world.glb

level2 href spawnpoints

objectnameoptionalfunctionality
spawnyesSpecifies default camera-position (if exist). Detected after loading scene (world.glb e.g.), if no URI hashtag is present (world.glb#roomC e.g.)
URI fragmenttypefunctionality
#roomBstringposition camera to position of object with name roomB
#cam2stringposition camera to position of camera with name cam02, and make it active camera [follow animation e.g.]
https://my.org/worldX.glb#roomYstringposition camera to position of object roomC after replacing the current scene with worldX.glb
the usercamera (usually default at 0,0,0 or at objectname spawn) is repositioned to the origin and upvector of the target object, and only in VR/AR its height gets adjusted (~1.6m height is subtracted, to compensate for camera-rig )

To enable VR elevators e.g., make sure:

the camera is attach/parented to that object (so it animates along with the object)

You can add this URI Fragment to the top-level URLbar, or as href value (to trigger via click) in a 3D model Editor (Blender e.g.):

Undefined widget 'videojs'

IMPORTANT: please respect collidable floor / objects. Also notice that #pos=roomB has been deprecated in favor of #roomB to simplify the spec.

Developers only:

» example implementation
» discussion

Spec

Below is the related section of the spec (full spec here: HTML, TXT)

How can applications discover 3D experiences on a network?

Answer: spatial microformats

The XRF microformat is an optional text heuristics which applications can detect across various usecases.

via HTML webpage

If the browser/application requests an webpage (https://nlnet.nl e.g.) it should check for the rel-me microformat :

<link rel="alternate" as="spatial-entrypoint" href="scene.xrf.glb">

This way the application loads https://nlnet.nl/scene.xrf.glb when the user types nlnet.nl into the URLbar.
Optionally, type can be specified for dynamically generated 3D files:

<link rel="alternate" as="spatial-entrypoint" href="https://worlds.org/scene.php#platformB" type="model/gltf+binary" />

The type-attribute is for fallback-purposes.
Viewer-supported 3D file-extensions (.glb e.g.) will ALWAYS take precedence over the (non)presence of the type attribute.
The reason is that platforms (Mastodon 'labels' e.g.) don't allow specifying type-attributes.
Another reason is that XR Fragments is filetype-agnostic, so flexibility is expected on the viewer-side.

NOTE: in case of multiple 3D files mentioned in <link rel="me", only the first (supported 3D filetype) will be chosen.

Collections

Example of a webpage with collection of 3D models (like icosa.gallery):

<link rel='alternate' as='spatial-portal' href="result1.glb"/>
<link rel='alternate' as='spatial-portal' href="result2.glb"/>
<link rel='alternate' as='spatial-portal' href="result3.glb#buildingA"/>
<link rel='alternate' as='spatial-portal' href="result3.glb#buildingB"/>

<!-- optional: pagination hints                -->
<link rel='next' as='spatial-portal' href="..."/>
<link rel='prev' as='spatial-portal' href="..."/>
<link rel="pages" min="1" max="46"   items="8" /> 

3D engines (games/apps) can render these like clickable portals, for example JanusXR-style portals:

result1.glbresult2.glb

NOTE: for more customizability JML <link> will allow for positioning/thumbnailed portals:

<fireboxroom>
  <assets>
    <assetimage src="/img/thumb1.jpg" id="img1"/>
    <assetimage src="/img/thumb2.jpg" id="img2"/>
  </assets>
  <room skybox="true" pos="0 0 0" showavatar="false" use_local_asset="room_plane">
    <link url="/myverse/janusxr_tutorial1/"  thumb_id="img1"  title_col="0.4 0.37 0.4" pos="0 0 0.001" draw_glow="true" scale="3 3 0.1" />
    <link url="/myverse/janusxr_tutorial2/"  thumb_id="img2"  title_col="0.4 0.37 0.4" pos="3 0 0.001" draw_glow="true" scale="3 3 0.1" />
  </room>
</fireboxroom>

Mixing multiple spatial microformats:

<link rel="alternate" as="spatial-entrypoint" href="scene.xrf.glb"/>
<link rel="me" href="myavatar.vrm"/>
<!-- JanusXR JML https://github.com/jbaicoianu/janusweb
<fireboxroom>
  <room>
    <object id="scene.xrf.glb" pos="0 0 0"/>
  </room>
</fireboxroom>
-->

via WebFinger

When John has an account on foo.com, how can other applications request his 3D homepage by simply entering john@foo.com?

Answer: it can be requested at https://foo.com/.well-known/webfinger?resource=acct:john@foo.com, resulting in:

{
  "subject": "acct:john@foo.com",
  "aliases": [
    "https://mastodon.example/social/john",
    "https://john.foo.com",
    "https://3d.john.foo.com/model/scene.glb"
  ],
  "properties": {
    "http://schema.org/name": "John Doe",
    "http://schema.org/description": "Developer, 3D Enthusiast, and Social Explorer"
  },
  "links": [
    {
      "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://mastodon.example/social/john/{uri}"
    },
    {
      "rel": "self",
      "type": "text/html",
      "href": "https://john.foo.com"
    },
    {
      "rel": "me",
      "type": "text/html",
      "href": "https://john.foo.com"
    },
		{
      "rel": "me",
      "type": "model/gltf+binary",
      "href": "https://3d.john.foo.com/model/avatar.vrm"
    },
    {
      "rel": "scene",
      "type": "model/gltf+binary",
      "href": "https://3d.john.foo.com/model/scene.xrf.glb"
    }
  ]
}

This way the application will load https://3d.john.foo.com/model/scene.glb when the user types john@foo.com into the user field.

via Text (URI)

As a fallback, for an application to trigger loading a 3D scene is by detecting URI's of 3D scene-files any text:

  • foo.glb (or any other popular 3D extension)
  • https://foo.com/scene.glb (or any other popular protocol)

This way, the application can highlight the link whenever it detects the URI (in a text-file or text-section of a 3D model)

What if we embed XR Fragment URI's inside a 3D or XML file?

level2 promotes adding clickable hyperlinks, via the href metadata attribute.

<room>
  <object id="plane" js_id="button" href="#building"/>
  <object id="cube"  js_id="building"/>
  <link url="foo.glb#spawn"/>
</room>

Clicking the plane will teleport the user to object building.
Clicking the portal (<link>) will clear the scene, load foo.glb and teleport the user to object spawn.

For more info about JanusXR

cube = scene.getObjectByName("cube")
sphere = scene.getObjectByName("sphere")

// add URI's with XR Fragments 
cube.userData.href   = '#platform2'
sphere.userData.href = "foo.glb#spawn'

// local teleport!
cube.onClick = () => { 
  camera.position.copy( scene.getObjectByName("platform2").position )
}

// remote teleport!
sphere.onClick = await () => { 
  scene.clear()
  await scene.load('foo.glb')
  camera.position.copy( scene.getObjectByName("spawn").position )
}

Clicking the cube will teleport the user to object 'platform2'.
Clicking the sphere will clear the scene, load foo.glb and teleport the user to object spawn.

NOTE: gltf-models fully support href's in this implementation but href in markup is not supported (yet: JanusXR is a safer bet)

<a-scene>
  <a-cube href="#building"/>
  <link href="foo.glb#spawn"/>
</a-scene>

Clicking the cube will teleport the user to object building.
Clicking the portal (<link>) will clear the scene, load foo.glb and teleport the user to object spawn.</div>

NOTE: no implementation (yet)

<m-cube href="#building"></m-cube>
<m-sphere href="foo.glb#spawn"></m-cube>

Clicking the cube will teleport the user to object building.
Clicking the sphere will clear the scene, load foo.glb and teleport the user to object spawn.</div>

All modern 3D editors can attach metadata to objects, and export these as 'extras' with the 3D file.

An Easy nocode way to add metadata is by adding custom properties in blender e.g.. This is demonstrated in the getting started video:

Undefined widget 'videojs'

custom property type functionality
href string (uri or predefined view) href navigation / portals / teleporting to other XR documents

3D documents using href are spec-compliant but similar variants (<Link url="..."> in JanusXR JML e.g) are considered spec-compatible


Object metadata can also be added/exported programmatically, for example in AFRAME/THREE.js can export GLB/USDZ/OBJ/COLLADA-files with them, after setting myobject.userData.href = "#nameofplane" e.g.

Spec

Below is the related section of the spec (full spec here: HTML, TXT)

Adding links to 3D objects

Clicking an 3D object with href-data, will teleport the user to that file and/or object.





<room>
  <object id="plane" js_id="button" href="#building"/>
  <object id="cube"  js_id="building"/>
  <link url="foo.glb#spawn"/>
</room>

Clicking the plane will teleport the user to object building.
Clicking the portal (<link>) will clear the scene, load foo.glb and teleport the user to object spawn.

For more info about JanusXR

cube = scene.getObjectByName("cube")
sphere = scene.getObjectByName("sphere")

// add URI's with XR Fragments 
cube.userData.href   = '#platform2'
sphere.userData.href = "foo.glb#spawn'

// local teleport!
cube.onClick = () => { 
  camera.position.copy( scene.getObjectByName("platform2").position )
}

// remote teleport!
sphere.onClick = await () => { 
  scene.clear()
  await scene.load('foo.glb')
  camera.position.copy( scene.getObjectByName("spawn").position )
}

Clicking the cube will teleport the user to object 'platform2'.
Clicking the sphere will clear the scene, load foo.glb and teleport the user to object spawn.

NOTE: gltf-models fully support href's in this implementation but href in markup is not supported (yet: JanusXR is a safer bet)

<a-scene>
  <a-cube href="#building"/>
  <link href="foo.glb#spawn"/>
</a-scene>

Clicking the cube will teleport the user to object building.
Clicking the portal (<link>) will clear the scene, load foo.glb and teleport the user to object spawn.</div>

NOTE: no implementation (yet)

<m-cube href="#building"></m-cube>
<m-sphere href="foo.glb#spawn"></m-cube>

Clicking the cube will teleport the user to object building.
Clicking the sphere will clear the scene, load foo.glb and teleport the user to object spawn.</div>

All modern 3D editors can attach metadata to objects, and export these as 'extras' with the 3D file.

An Easy nocode way to add metadata is by adding custom properties in blender e.g.. This is demonstrated in the getting started video:

Undefined widget 'videojs'
propertytypeexample value
hrefstring (uri)#bar
#pyramid
xrf://#-someobject
://somefile.gltf#foo

Interaction behaviour

1. when clicking a href-value (#bar e.g.), the user(camera) is teleport to the referenced object.

2. when clicking a remote href-value (https://foo.org/hello.glb#bar e.g.), then that 3D file replaces the current scene (+user(camera) is teleported to any referenced object roomB).

XR Safety Exception: when linking to a 3D file which has zero signs of XR Fragments (see 📜 level0: File), it will be treated as an Object import

Spec

See the full spec here: HTML, TXT

solutions in the spec were abducted from this and this survey result

Demo

Undefined widget 'videojs'

capture of aframe/sandbox

XR Viewer implementation

specactionfeature
level0+1hover 3D file hrefshow the preview PNG thumbnail (if any). See 📜 level0: File)
level0+1launch 3D file hrefreplace the current scene with a new 3D file (href: other.glb e.g.)
level2click internal 3D file href (#roomB e.g.)teleport the camera to the origin of object(name roomB). See teleport camera.
level2click external 3D file href (foo.glb e.g.)replace the current scene with a new 3D file (href: other.glb e.g.)
level2hover external 3D file hrefshow the preview PNG thumbnail (if any sidecar 📜 level0: File)
level2click hrefhashbus: execute without changing the toplevel URL location (href: xrf://#someObjectName e.g.)
level3click hrefset the global 3D animation timeline to its Media Fragment value (#t=2,3 e.g.)
NOTE: hashbus links (xrf://#foo&bar) don't change the toplevel URL, which makes it ideal for interactions (in contrast to typical #roomC navigation, which benefit back/forward browser-buttons), see hashbus for more info.

XRF viewer pseudocode

scene.traverse( (n) => {
  if( n.userData.href ){
    n.addEventListener('click', () => scene.teleport(n.userData.href) )
  }
})

XR Fragment-capable clients offer increased XR Accessibility via aria-description-metadata, and the so-called 2-button navigation:

TAB and ENTER actions allow for cycling/executing objects with href metadata contextually, meaning that only relevant objects are candidates for this (allowing comfortable tab-navigation inside huge worlds with large amounts of buttons). The buttons are remappable, and can also be triggered via speech.

Example of metadata of an accessible button:

  • href: #platformB
  • aria-description: is a space where the history of mankind is explained

Selecting the button will display/read to the user: #platformB is a space where the history mankind is explained.
The spec encourages starting aria-description with a verb (for easy transcripts).

Undefined widget 'videojs'

Here's the relevant part of the spec:

The spec also defines a simple text-input interface which allows navigation via speech or text-input:

set the position of the camera.

level1 spawnpoints

protocol :// my.org/world.glb #bar

Spawn user at object (with name) bar after loading (and replacing the current scene with) world.glb

level2 href spawnpoints

objectnameoptionalfunctionality
spawnyesSpecifies default camera-position (if exist). Detected after loading scene (world.glb e.g.), if no URI hashtag is present (world.glb#roomC e.g.)
URI fragmenttypefunctionality
#roomBstringposition camera to position of object with name roomB
#cam2stringposition camera to position of camera with name cam02, and make it active camera [follow animation e.g.]
https://my.org/worldX.glb#roomYstringposition camera to position of object roomC after replacing the current scene with worldX.glb
the usercamera (usually default at 0,0,0 or at objectname spawn) is repositioned to the origin and upvector of the target object, and only in VR/AR its height gets adjusted (~1.6m height is subtracted, to compensate for camera-rig )

To enable VR elevators e.g., make sure:

the camera is attach/parented to that object (so it animates along with the object)

You can add this URI Fragment to the top-level URLbar, or as href value (to trigger via click) in a 3D model Editor (Blender e.g.):

Undefined widget 'videojs'

IMPORTANT: please respect collidable floor / objects. Also notice that #pos=roomB has been deprecated in favor of #roomB to simplify the spec.

Developers only:

» example implementation
» discussion

Spec

Below is the related section of the spec (full spec here: HTML, TXT)

Guided & interactive XR navigation is possible when using href in WebVTT subtitle-files.

Potential

  • guided XR tours across multiple files/URLs
  • timeline for spawnpoints
  • rich storytelling / e-learning

Example using sidecar files:

myscene.xrf.glb
myscene.xrf.vtt
myscene.xrf.ogg

Since .xrf. (or at least one href) is a heuristic for loading sidecar files, the webvtt subtitles (myscene.xrf.vtt) can be displayed while the experience plays (syncronized with myscene.xrf.ogg):

WEBVTT

00:01.000 --> 00:04.000 href:#spawn
<v narrator voice>welcome to a special experience.
one
two
three

00:06.000 --> 00:12.000 
Let me take you to the divine..

00:13.000 --> 00:14.000 href:#fadeAudioOut&inside
Here we are 

00:14.000 --> 00:19.000
Now lets open a portal 
to a remote location 

00:19.000 --> 00:25.000 href:https://xrfragment.org
That portal will take us 
to https://xrfragment.org
Just click it..

00:25.100 --> 00:30.000 
Welcome to another Janus URL

Here href is used as CUE setting, which the player can act upon.

How to know whether a 3D file is a full scene or just a prop?
When should a 3D file hide its skybox?
How does a file know whether its embedded or not?
How to hide an object in AR-mode only?
How to ''hide'' an object by default, after loading a scene?

Answer: somehow tagging the file, or object with predefined classes ; universal XR keywords.

<!-- xr layers: vr ar portal embed -->
<room>
  <!-- override: dont show in AR by leaving 'ar' out -->
  <object id="room_and_sky" class="vr portal embed">

  <!-- override: only show in AR -->
  <text text="welcome in AR mode" class="ar"/>
</room>

Here the JML browser is instructed to opt out certain elements, depending on the context.

For more info about JanusXR

cube = scene.getObjectByName("cube")
sphere = scene.getObjectByName("sphere")

// you can set the classes manually in case your glTF 
// does not have them (yet)
scene.userData.class  = "vr ar portal embed" // default 
cube.userData.class   = 'ar' // only ar 
sphere.userData.class = "vr portal embed' // hide in ar

const modes = getModes()    // ['ar'] (somehow determine viewing context)

scene.traverse( (obj) => { // trickle down classes to children
  if( obj.userData.class ){
    obj.userData.classes = obj.userData.class.replace(/  /,' ').split(' ')
    modes.map( (mode) => {
      if( ! ~obj.userData.classes.indexOf(mode) ) obj.visible = false 
    })
    obj.traverse( (child) => {
      child.userData.classes = obj.userData.classes )
      child.visible = false
    })
  }
})

The cube will only be visible in AR, while the sphere also in VR, when renderered in a portal, or when embedded in another scene.

NOTE: not implemented yet in this implementation but href in markup is not supported (yet: JanusXR is a safer bet)

<a-scene> <!-- assumed default class="vr ar portal embed" -->
  <a-cube layer="ar"/> <!-- show only in AR -->
  <a-sphere layer="vr portal embed"/>
</a-scene>

The cube will only be visible in AR, while the sphere also in VR, when renderered in a portal, or when embedded in another scene.

NOTE: no implementation (yet)

  <m-cube layer="ar"/> <!-- show only in AR -->
  <m-sphere layer="vr portal embed"/>

The cube will only be visible in AR, while the sphere also in VR, when renderered in a portal, or when embedded in another scene.

All modern 3D editors can attach metadata to objects, and export these as 'extras' with the 3D file.

Similar to href: instead of href, create an extra class-property with a string-value (ar e.g.), to opt out of the default inherited vr ar portal embed-value (from the scene-root, even when its not explicitly defined).

Predefined hints: XR layers

hint/class desktop
mode
VR
mode
AR
mode
usecase
vr show show hide render object+children
ar hide hide show render object+children
embed show show show render object+children when loaded in another scene
portal show show show render object+children inside portal
collection hide hide hide object+children are not part of a scene/experience (think importing into inventory, openbrush brushes e.g.).
hide hide hide hide hide object+children

Any element without any of these class-values is considered visible in all layers. Once class-value(s) are detected it'll work as a layer-mask: class: 'vr ar' will be visible in desktop-,VR- and AR-mode.

NOTE: there's is no CSS: class attributes without CSS means no cascade inheritance; above class-definitions will apply to the element itself (and its children, which can override by defining their own XR layer class-definitions).

Predefined hints: XR object interactions

hint/class spec document default usecase
grabbable v1 unset allow single handtracking-pinch to reposition object, or via buttonhold + controllermove/mousemove
stretchable v1 unset allow both handtracking-pinch to stretch object, or via buttonhold + controllermove/mousemove
collidable v1 unset hints that grabbable and stretchable should halt upon collisions

NOTE: href: #*foo implies that object foo has class: 'grabbable'

Usecases

  • 3D previews: class: 'vr ar' prevents rendering (heavy) items when displayed in a portal (or embedded into another scene).
  • extra info: class: 'portal' displays onboarding texts/info ONLY when rendered in a portal.

Examples

class: 'vr ar portal embed'skysky will not be renderedwhen the user is viewingin AR modedesigner notesdesigner notes will not be renderedin viewer becauseof class overrideclass: 'hide'ARonboardingwill ONLY be shownwhen loaded inAR sessionnot when loaded intoVR, portal or anotherscene.(all objects inherit these default classes)class: 'vr portal embed'class: 'vr ar portal embed'(all objects inherit these default classes)(all objects inherit these default classes)class: 'vr ar portal embed'class: 'ar'

XR Fragments is not a fileformat-specific extension, it's a spec for deeplinking any 3D file.
The level2 metadata (See reference) is easy to embed in any 3D editor (not only blender) than it would be to support new GLTF extensions.
This is not to say extensions are bad (they are superior in certain cases).

Just like URLs allow fileformat-agnostic navigation, 3D asset 'extras' are fileformat-agnostic too, which together allow for XR Fragments.

To deal with extensions/overlapping features see native vs XRF features

How to deal with overlapping functionality?


Well, native (extensions) take precende, otherwise 'fallback' applies.

Examples

Native feature XRF Solution
<Link url="..."> in JanusXR JML href: ... (3Dfile extra)
<Link href="..."/> (JML)
use <Link url="...">, otherwise href="...", otherwise href: ...
OMI_Link gltf extension href: .... use OMI_Link, otherwise href

Common advice is to 'stack' (portal)links to achieve graceful degradation:

  • plane at 0 0 0 has texture explaining link/portal
  • plane at 0 0 0.01 uses href link
  • plane at 0 0 0.02 uses OMI_LINK link

That way there's click 'fallthrough': the user will click whichever the engine supports.


Below is the related section of the spec (full spec here: HTML, TXT)



For more info see How it works

multilangual 3D file

How to enable multilangual 3D experiences?

Answer: by adding extra objectnames/metadata which include a language postfix (ISO 639-1 language 2char-code).

Example object-metadata:

  • aria-description: this is a cube
  • aria-description-nl: dit is een kubus

Example object-name:

Given a scene with objectnames banner and banner-nl

  • href: #+banner

If the language is set to nl and banner-nl exists too, then that will be selected/operated instead.

How to determine the language?

This should be a setting of the browser. For example, to get the language from a webbrowser:

navigator.language.substr(0,2)  // 'en'

NOTE: this is completely optional, and works via progressive enhancement.