251 lines
11 KiB
Markdown
251 lines
11 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`
|
|
|
|
## 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 ||
|
|
| `bootmenu` | `boolean` | true | give user choice [or boot straight into ISO ] |
|
|
| `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())
|
|
```
|
|
|
|
|
|
## [launcher](com/launcher.js)
|
|
|
|
displays app (icons) for enduser to launch
|
|
|
|
```javascript
|
|
<a-scene launcher/>
|
|
```
|
|
|
|
| property | type | example |
|
|
|--------------|--------------------|----------------------------------------------------------------------------------------|
|
|
| `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:
|
|
|
|
```javascript
|
|
AFRAME.registerComponent('foo',{
|
|
events:{
|
|
launcher: function(){ ...launch something... }
|
|
},
|
|
manifest:{ // HTML5 manifesto JSON object
|
|
// https://www.w3.org/TR/appmanifest/
|
|
}
|
|
}
|
|
```
|
|
|
|
2. dynamically in javascript
|
|
|
|
```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](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 |
|
|
|
|
|
|
Restore the pose.
|
|
|
|
|
|
## [require](com/require('').js)
|
|
|
|
automatically requires dependencies or missing components
|
|
|
|
```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.)
|
|
|
|
|
|
## [window](com/window.js)
|
|
|
|
wraps a draggable window around a dom id or [dom](com/dom.js) component.
|
|
|
|
```html
|
|
<a-entity window="dom: #mydiv"/>
|
|
```
|
|
|
|
> depends on [AFRAME.utils.require](com/require.js)
|
|
|
|
| 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` | [] | |
|