# VARTISTE Toolkit
The VARTISTE toolkit is a collection of components developed while creating
[VARTISTE](https://vartiste.xyz). I've compiled them into a stand-alone module
in the hopes that it might help folks to jump start their own projects.
# Installation / Use
The easiest way to use it is to include the `.js` file from a CDN, such as
unpkg, specifying the version using _@version_:
```html
...
```
Latest Version:
[](https://www.npmjs.com/package/aframe-vartiste-toolkit)
Including the javascript file automatically registers the components and
systems.
**Note:** You can access the most up to date version using _@latest_, but this
is not recommended as it may cause unexpected changes.
## New Project vs. Existing Project
When creating a new project, I recommend pulling the entirety of
aframe-vartiste-toolkit. The toolkit contains a wide variety of features;
some components and systems rely on others for full functionality. Including
the entire toolkit allows components and systems to work together to their
full extent.
If you're bringing aframe-vartiste-toolkit into an existing project, you can
either [bring in specific pieces of the toolkit](#customization), or you can
bring in the whole thing. If possible, I recommend pulling in the whole toolkit,
since components may depend on other components or systems. If there's a concern
for naming or functionality conflicts, most components can also operate on their
own.
# Toolkit Overview
The *aframe-vartiste-toolkit* contains a wide variety of elements. It's built by
exporting every little bit and piece of the [VARTISTE](https://vartiste.xyz) app.
Exploring [VARTISTE](https://vartiste.xyz) and the [VARTISTE source
code](https://gitlab.com/zach-geek/vartiste) is ultimately the best way to
see what's available and how it works. Nonetheless, I've written some
documentation as a best-spare-time-effort. Here are some of the essentials to get
you started.
## Philosophy and Terms
VARTISTE leans pretty heavily into the entity-component-system framework that
a-frame makes available; it consists mostly of components, which use systems when
needed, and can be attached to entities pretty readily. Many components also spawn
their own children entities.
There are a few notable exceptions in the form of utility classes, such as
[`VARTISTE.Util`](#util.js) and [`VARTISTE.Undo`](#undo.js). These utility classes
can be used when creating components or anywhere you'd like in your Javascript code.
They are exposed under the VARTISTE object, which is created as a property in the
global `window`. For instance, to access the
`whenLoaded` method of [`Util`](#util.js), you can call
`VARTISTE.Util.whenLoaded(...)` anywhere in your code.
Most components (but not all) respond correctly to updates via
`setAttribute()`; fewer things respond correctly to `remove()` so if you
run into issues, double check the docs here or the source code.
One extension to the ECS framework in VARTISTE are "component systems", created
via [`VARTISTE.Util.registerComponentSystem`](#util.js). These are basically
components for `a-scene` which get automatically attached (like systems do).
They have the full schema and update abilities of components, with the
auto-attach convenience of systems. These are registered as both systems _and_
components and can be accessed either by the scene `components` object
(e.g., `sceneEl.components["COMPONENT NAME"]`) or the scene `systems` object
(e.g., `sceneEl.systems["COMPONENT NAME"]`) within your code.
## UI Components
VARTISTE has a quick-and-dirty user interface, focused around the
[`icon-button`](#icon-button). These are usually collected into an
[`icon-row`](#icon-row), where they're automatically laid out
horizontally. Most clickable elements have a [`tooltip`](#tooltip),
which are readable by the built-in [text-to-speech](#speech.js)
system.
In addition to [`icon-button`s](#icon-button), there are [`edit-field`s](#edit-field)
for text input and [`lever`s](#lever) for adjusting values.
All of these components are arranged on a [`shelf`](#shelf) which provides a
background and frame. Shelves can also be closed or pinned to a controller for
easy workspace management.
## User Rig
I created VARTISTE's user rig layout based on a laser-pointer type interface.
You can incorporate the entire rig with the [`vartiste-user-root`](#vartiste-user-root)
component. It includes:
- Automatic "Press any key to reset orientation" when entering VR.
- Cool "VR Goggles" that show up in the spectator camera (but not during normal
display)
- Ultra leap hand tracking
- [`hand-action-tooltip`](#hand-action-tooltip) context sensitive button help
tied to the controllers
- WebXR controller-only mode. I.e., you can use you controllers without your
headset, but just displaying on the desktop. Uses the [`xr-controllers`](#xr-controllers.js) system
- Controller motion smoothing by default. Really improves experiences for jumpy controllers (*cough*ReverbG2*cough*)
Note this user rig uses the
[`webxr-motion-controller`](#webxr-motion-controller) and
[`webxr-laser`](#webxr-laser) components rather than the a-frame built-in
`laser-controls`. I found the [webxr-input-profiles
motion-controllers](https://github.com/immersive-web/webxr-input-profiles) to be
more consistent and up-to-date than the built-in a-frame components, so I
built the [`webxr-input-profiles`](#webxr-input-profiles) system to take advantage
of that.
## Interaction Components
User interaction is built around laser-control-type raycasting. Interactive
elements have the `clickable` HTML class set, which makes them visible to the
raycasters. `click` events are emitted when these elements are clicked.
Every `clickable` entity, by default, can also be grabbed and moved. Grabbing
and moving is handled via the [`manipulator`](#manipulator) component, which
is installed on the user motion controllers or mouse controls. More info can
be found in the documentation for [`manipulator`](#manipulator).
There are also a bunch of built-in constraints, which can be set on entities to
restrict how they move when grabbed. For instance
[`manipulator-weight`](#manipulator-weight) makes entities feel "heavy" by
slowing down their movement when grabbed.
## Drawing Components
[VARTISTE](https://vartiste.xyz) is, of course, a drawing and image editing
application. I've brought many drawing components into the toolkit to
allow easily adding drawing to other A-Frame applications.
The easiest way to add drawing to your app is to add the
[`drawable`](#drawable) component to whatever you want to be able to draw on,
and the [`hand-draw-tool`](#hand-draw-tool) component to whichever raycasters
you want to be able to draw. These are already set up if you use the
[`vartiste-user-root`](#vartiste-user-root) component. Additionally, you can
create [`pencil-tool`](#pencil-tool) components to create grabbable pencils that
can be easier to use in VR.
You can create your own brushes with the [`set-brush`](#set-brush) component.
Scene-wide drawing parameters are managed by the
[`paint-system`](#paint-system).
## Other cool stuff
There are lots of other nifty components and systems, for instance
[`canvas-fx`](#canvas-fx), which lets you quickly apply special effects to a
canvas, or [`glb-exporter`](#glb-exporter) which will let you download any
arbitrary entity or `THREE.Object3D` as a glb file in a single function call.
There's even a PhysX-based [physics system](#physics.js)!
Ultimately, the best way to find out everything that's available is to read
through these documents, play around with the examples and VARTISTE itself, and
failing that, to read the source code.
Also, VARTISTE uses a bunch of premade environments. These are packaged separately
in the [aframe-enviropacks](https://www.npmjs.com/package/aframe-enviropacks) package.
## Assets
Assets required for some of the basic component use are automatically included
by the javascript source file.
If you want to include *all* VARTISTE assets in your project, you will need an
`a-asset` with a `vartiste-assets` property, like this:
```html
```
## Customization
You can optionally customize which components and systems are registered by the
aframe-vartiste-toolkit by setting the `VARTISTE_TOOLKIT` variable *before* the
vartiste-toolkit.js file is loaded. `VARTISTE_TOOLKIT` should either be `undefined`
(default) or be an object having any of the following properties:
- `excludeComponents`: Array of strings specifying which components, systems, or
systemComponents specifically to exclude from being registered
- `includeComponents`: Array of strings specifying which components, systems, or
systemComponents to be registered. All other components, systems, and
systemComponents will be excluded.
- `excludeFiles`: Array of strings specifying all aframe-vartiste-toolkit source
code files (from [the component reference](https://vartiste.xyz/docs.html)) to
exclude entirely from registration. All components, systems, and
systemComponents in those files will *not* be registered. Any classes in those
files will not be defined.
- `includeFiles`: Array of strings specifying which aframe-vartiste-toolkit
source code files (from [the component
reference](https://vartiste.xyz/docs.html)) to include in registration. All
components, systems, and systemComponents, and classes in other files will be
excluded.
- `assetUrl`: VARTISTE Toolkit assets will be fetched from
`assetUrl/assets/####.###`. Use this option if you want to use webpack and
have a custom public-facing URL
- `replaceTextWithTroikaText`: If set to `true`, it will completely replace the
built-in AFRAME `text` component with a shim that will convert all `text` to
`troika-text`. The shim will automatically convert all `text` properties to
equivalent `troika-text` properties, and handle updates and removal. No
changes to code using the `text` component should be necessary. If set to
`false` the `text` component will be left at the AFRAME default. If left at
the default value of `'auto'`, the toolkit will try to guess whether you want
the shim or not by looking at the `includeComponents` and `excludeComponents`
values.
## Component Reference
The full API and component reference can be found at
[https://vartiste.xyz/docs.html](https://vartiste.xyz/docs.html). Please note
that it is still under construction. The source code is available as well at
[https://gitlab.com/zach-geek/vartiste](https://gitlab.com/zach-geek/vartiste),
and contributions, both code-wise and documentation-wise are welcome.
# Examples
## Example Scene
```html
VARTISTE Toolkit Demo
```
[View the demo on CodePen](https://codepen.io/zach-capalbo/pen/oNbKagV)
## Physics playground
The [aframe-vartiste-toolkit physics playground](https://glitch.com/edit/#!/fascinated-hip-period?path=index.html%3A1%3A0) is a good example of using the toolkit for projects other than painting or drawing. It's also the best example of the [physics](#physics.js) components so far.
# Source Code
For more information, and to better understand VARTISTE, you can also read through the source code:
[https://gitlab.com/zach-geek/vartiste/-/blob/release/src/vartiste-toolkit.js](https://gitlab.com/zach-geek/vartiste/-/blob/release/src/vartiste-toolkit.js)