XRshell apps & components

This is a library of useful AFRAME components used in XRSH [or in any AFRAME app].
Characteristics:

• selfcontained
• auto-loading of dependencies (via AFRAME.utils.require() see this example)

Usage

<script src="https://codeberg.org/xrsh/xrsh-com/com/require.js"/>
<script src="https://codeberg.org/xrsh/xrsh-com/com/example/helloworld.js"/>

<a-entity helloworld="foo:1" class="cubes" name="box">  

See component list below

this README.md is generated by running echo "$(./README.awk com/*.js)" > README.md

Credits

This project is partially funded through NGI0 Entrust, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

Component List

data_events

allows components to react to data changes

 <script>
   AFRAME.registerComponent('mycom',{
     init: function(){ this.data.foo = 1 }, 
     event: {
       foo:   (e) => alert("I was updated!")
     }
   })
 </script>

 <a-entity mycom data_events/>

html-as-texture-in-xr

shows domid only in immersive mode (wrapper around aframe-htmlmesh

It also sets class 'XR' to the (HTML) body-element in immersive mode. This allows CSS (in dom component) to visually update accordingly.

depends on AFRAME.utils.require

 <style type="text/css">
   .XR #foo { color:red; }
 </style>

 <a-entity html-as-texture-in-xr="domid: #foo">
   <b id="foo">hello</b>
 </a-entitiy>

property	type
domid	string

event	target	info
3D	a-scene	fired when going into immersive mode
2D	a-scene	fired when leaving immersive mode

isoterminal

Renders a windowed terminal in both (non)immersive mode. It displays an interactive javascript console or boots into a Linux ISO image (via WASM).

  <a-entity isoterminal="iso: xrsh.iso" position="0 1.6 -0.3"></a-entity>

depends on AFRAME.utils.require

property	type	default	info
iso	string	https`//forgejo.isvery.ninja/assets/xrsh-buildroot/main/xrsh.iso"
overlayfs	string	''	zip URL/file to autoextract on top of filesystem
width	number	800
height	number	600
depth	number	0.03
lineHeight	number	18
bootMenu	string	""	character to auto-enter in bootMenu
bootMenuURL	string	""	character to auto-enter in bootMenu when URL has fragment (#foo.zip e.g.)
padding	number	18
maximized	boolean	false
minimized	boolean	false
muteUntilPrompt	boolean	true	mute stdout until a prompt is detected in ISO
HUD	boolean	false	link to camera movement
transparent	boolean	false	heavy, needs good gpu
memory	number	60	VM memory (in MB) [NOTE` quest or smartphone webworker might crash > 40mb ]
bufferLatency	number	1	in ms` bufferlatency from webworker to term (batch-update every char to texture)
debug	boolean	false
emulator	string	fbterm	terminal emulator

for more info see xrsh.isvery.ninja

Component design:

                  css/html template                                                                                
                                                                                                                    
                    ┌─────────┐   ┌────────────┐                  exit-AR                                
           ┌───────►│ com/dom ┼──►│ com/window ├───────────────── exit-VR  ◄─┐                           
           │        └─────────┘   └───────────┬┘                             │                           
           │                                  │                              │                           
┌──────────┴────────┐                         │   ┌───────────┐    ┌─────────────────────────────┐
│  com/isoterminal  ├────────────────────────────►│com/term.js│    │com/html-as-texture-in-XR.js │
└────────┬─┬────────┘                         │   └──┬─────┬▲─┘    └─────────────────────────────┘
         │ │        ┌────────┐             ┌──▼──────▼──────┐                     ││        │                       
         │ └───────►│ plane  ├─────►text───┼►div#isoterminal│◄────────────────── enter-VR   │                       
         │          └────────┘             └────────────────┘                    enter-AR ◄─┘                       
         │                                   │                                                     
         │                                   │                                                                   
         │                             ISOTerminal.js                                                                   
         │                ┌───────────────────────────┐           
         │                │ com/isoterminal/worker.js ├            
         │                └──────────────┌────────────┤            
         │                     │         │ v86.js     │            
         │                     │         │ feat/*.js  │            
         │                     │         │ libv86.js  │            
         │                     │         └────────────┘            
         │                     │         
         └─────────────────────┘    
                                                                                                                    
NOTE: For convenience reasons, events are forwarded between com/isoterminal.js, worker.js and ISOTerminal
      Instead of a melting pot of different functionnames, events are flowing through everything (ISOTerminal.emit())

launcher

displays app (icons) in 2D and 3D handmenu (enduser can launch desktop-like 'apps')

<a-entity launcher>
  <a-entity launch="component: helloworld; foo: bar"><a-entity>
</a-entity>
 

property	type	example
attach	selector	hand or object to attach menu to
registries	array of strings	<a-entity launcher="registers: https://foo.com/index.json, ./index.json"/>

| event | target | info | |--------------|-------------------------------------------------------------------------------------------------------------| | launcher | an app | when pressing an app icon, launcher event will be send to the respective app |

There a multiple ways of letting the launcher know that an app can be launched:

1. any AFRAME component with an launcher-event + manifest is automatically added:

AFRAME.registerComponent('foo',{
  events:{
    launcher: function(){ ...launch something... }
  },
  manifest:{ // HTML5 manifesto JSON object
    // https://www.w3.org/TR/appmanifest/ 
  }
}

2. dynamically in javascript

window.launcher.register({
  name:"foo",
  icon: "https://.../optional_icon.png" 
  description: "lorem ipsum",
  cb: () => alert("foo")
})
//window.launcher.unregister('foo')

Restore the pose.

pastedrop

detects user copy/paste and file dragdrop action and clipboard functions

  <a-entity pastedrop/>

event	target	info
pasteFile	self	always translates input to a File object

Restore the pose.

require

automatically requires dependencies or missing components

await AFRAME.utils.require( this.dependencies )               (*) autoload missing components
await AFRAME.utils.require( this.el.getAttributeNames() )     (*) autoload missing components
await AFRAME.utils.require({foo: "https://foo.com/aframe/components/foo.js"},this)
await AFRAME.utils.require(["./app/foo.js","foo.css"],this)

(*) = prefixes baseURL AFRAME.utils.require.baseURL ('./com/' e.g.)

window

wraps a draggable window around a dom id or dom component.

  <a-entity window="dom: #mydiv"/>

depends on AFRAME.utils.require

property	type	default	info
title	string	""
width	string
height	string	260px
uid	string
attach	selector
dom	selector
max	boolean	false
min	boolean	false
x	string	"center"
y	string	"center"
class	array	[]