# 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.)