diff --git a/docs/MasterMath/BlockifyVR.md b/docs/MasterMath/BlockifyVR.md new file mode 100644 index 0000000000..f5a41f756a --- /dev/null +++ b/docs/MasterMath/BlockifyVR.md @@ -0,0 +1,191 @@ +# BlockifyVR + +## Table of contents +1. [What This Is](#description) +2. [How It Works](#how-it-works) +3. [The Blocks](#the-blocks) +3.1. [Utilities](#utilities) +3.2. [Transformations](#transformations) +3.3 [Controllers](#controllers) +4. [Transformations and Coordinate Systems](#coord-systems) +5. [Best Practices](#best-practices) +5.1 [Optimization & Performance](#optimization) +5.1 [Designing VR Experiences](#vr-design) +5.2 [Maintaining Cross-Platform Compatibility](#compatibility) +6. [Limitations](#limitations) +7. [Examples](#examples) + +## What This Is +__BlockifyVR__ is a cross-platform virtual reality extension designed to easily integrate into existing 3D projects. It targets modern __6DOF__ virtual reality headsets with two 6DOF controllers. Its purpose is to provide a framework between virtual reality and Scratch for the creation of immersive games, experiences, animations, and more. + +## How It Works +BlockifyVR is a relatively simple extension that provides a layer of interaction between WebXR and Scratch that enables you to create VR experiences with ease. Its heart and foundation relies on [A-frame](https://aframe.io), a JavaScript library built on top of [Three.js](https://threejs.org) designed specifically for VR development on the web. These systems allow you to open your Scratch project into a immersive VR session that enable tracking, controller input, and more VR capabilities to be accessed by your project as input for your experiences. + + + +> [!TIP] +> Reading documentation isn't the best way to learn. For better documentation, see here (external link). You can find interactive tutorials/sample projects there for you to work with. + +## The Blocks +### Utilities + +```scratch +(enter v) VR mode :: #00a616 +``` +This block allows you to enter or exit a VR session. You should use it at the start of a project if a headset is present. + +```scratch + +``` +This block reports whether an VR session is presenting. + +```scratch + +``` +Checks if a VR headset is connected by looking for browser support of immersive-vr or immersive-ar WebXR session. + +```scratch +(stage width :: #00a616) +``` +Reports the width of the Scratch Stage in pixels. + +```scratch +(stage height :: #00a616) +``` +Reports the height of the Scratch Stage in pixels. + +```scratch +(get camera [field of view v] :: #00a616) +``` +Returns either the FOV, near clipping plane, or far clipping plane of the camera. + +### Transformations +```scratch +([x-position v] of [headset v] :: #00a616) +``` +Returns the X, Y, or Z position of the headset, left controller, or right controller. + +```scratch +([x-rotation v] of [headset v] :: #00a616) +``` +Returns the X, Y, or Z rotation of the headset, left controller, or right controller. + +```scratch +(item (1) of [combined v] matrix :: #00a616) +``` +A block that returns various matrix transformations useful for injecting into 3D renderers. It accepts items from 1-16 (4x4 matrix) and can return projection, view, inverse view, and combined (projection multiplied by inverse view) matrices. For more information, see here. + +### Controllers + +Controllers are more complicated because __some buttons are only available on certain platforms__. You can see the mappings in the dropdown below. + +
+ Button Mappings +

Oculus/Meta Touch Controls: Trigger, Grip, Thumbstick, A, B, X, Y, Surface +
HTC Vive: Trigger, Grip, Trackpad, Menu, System +
Windows Motion: Trigger, Grip, Thumbstick, Trackpad, Menu +

+
+
+ +```scratch + +``` +Returns true if the specified left/right controller is connected. On the Oculus/Meta Horizon Browser, an odd system-level quirk causes the controllers to not connect until after pressing the Oculus/Meta button twice to pause and resume the experience. + +```scratch +when [left controller v] [connected v] :: #00a616 hat +``` +An event that executes when the specified controller has connected or disconnected. + +```scratch +when [any v] pressed :: #00a616 hat +``` +An event that executes when the specified button has been pressed. + +```scratch +when [any v] touched :: #00a616 hat +``` +An event that executes when the specified button has been touched. __Only available on Oculus Touch Controllers__. + +```scratch +