176 lines
8.4 KiB
Markdown
176 lines
8.4 KiB
Markdown
# 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`
|
|
|
|
## Funding
|
|
|
|
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.)
|