xrsh-com/README.md

# XRshell apps & components

<img src='https://codeberg.org/xrsh/xrsh/media/branch/main/xrsh.svg' width="25%"/>

This is a library of useful AFRAME components used in [XRSH](https://xrsh.isvery.ninja) [or in any AFRAME app].<br>
Characteristics:

* selfcontained 
* auto-loading of dependencies (via [AFRAME.utils.require()](com/require.js) see this [example](com/example/helloworld.js))

# Usage

```html
<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](https://nlnet.nl/entrust), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/xrsh).

[<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
[<img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI Zero Logo" width="20%" />](https://nlnet.nl/entrust)

# Component List


## [data_events](com/data_events.js)

allows components to react to data changes 

```html 
 <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](com/html-as-texture-in-xr.js)

shows domid **only** in immersive mode 
(wrapper around [aframe-htmlmesh](https://ada.is/aframe-htmlmesh/)

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

> depends on [AFRAME.utils.require](com/require.js)

```html 
 <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](com/isoterminal.js)

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

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

> depends on [AFRAME.utils.require](com/require.js)

| property         | type      | default                | info |
|------------------|-----------|------------------------|------|
| `iso`            | `string`  | https`//forgejo.isvery.ninja/assets/xrsh-buildroot/main/xrsh.iso" | |
| `overlayfs`      | `string`  | *WORK-IN-PROGRESS* | |
| `width`          | `number`  |  800   ||
| `height`         | `number`  |  600   ||
| `depth`          | `number`  |  0.03  ||
| `lineHeight`     | `number`  |  18    ||
| `prompt`         | `boolean` |  true  | boot straight into ISO or give user choice |
| `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](https://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())
```       


## [pastedrop](com/pastedrop.js)

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

```html 
  <a-entity pastedrop/>
```

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


## [require](com/require('').js)

automatically requires dependencies 

```javascript
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.)