WebSpatial

https://webspatial.dev/docs/
Admin
WebSpatial is an open-source SDK that enables developers to bring spatial features and build spatial...
Tokens:28,844
Snippets:418
Trust Score:5.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install WebSpatial Builder

Source: https://webspatial.dev/docs/introduction/getting-started

Install the development dependency for packaging websites as native apps on platforms without built-in runtime support.

```bash
npm install -D @webspatial/builder
```

```bash
pnpm add -D @webspatial/builder
```

```bash
yarn add --dev @webspatial/builder
```

--------------------------------

### Using resizability with initScene

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/resizability

Example of applying resizability constraints when initializing a new scene.

```APIDOC
## initScene

### Example
```javascript
import { initScene } from "@webspatial/react-sdk";

initScene("newSceneName", defaultConfig => {
  return {
    ...defaultConfig,
    type: "volume",
    resizability: {
      minWidth: 100,
      minHeight: "100px",
      maxWidth: 200,
      maxHeight: 200,
    },
  };
});
```
```

--------------------------------

### Install visionOS platform support

Source: https://webspatial.dev/docs/introduction/getting-started

Install the platform-specific runtime package required for visionOS native app bundles.

```bash
npm install -D @webspatial/platform-visionos
```

```bash
pnpm add -D @webspatial/platform-visionos
```

```bash
yarn add --dev @webspatial/platform-visionos
```

--------------------------------

### Install WebSpatial SDK dependencies

Source: https://webspatial.dev/docs/introduction/getting-started

Install the React and Core SDK packages required to enable WebSpatial API functionality.

```bash
npm install @webspatial/react-sdk @webspatial/core-sdk
```

```bash
pnpm add @webspatial/react-sdk @webspatial/core-sdk
```

```bash
yarn add @webspatial/react-sdk @webspatial/core-sdk
```

--------------------------------

### Start the local development server

Source: https://webspatial.dev/docs/introduction/getting-started

Run the Vite development server to obtain a local URL for previewing WebSpatial effects.

```bash
vite dev  
# result:  
# -> Local: http://localhost:5173/  
```

--------------------------------

### Web App Manifest configuration

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/worldScaling

How to set the world_scaling property in the Web App Manifest for the start scene.

```APIDOC
## Web App Manifest Configuration

### Description
Configures the world_scaling property for the start scene within the Web App Manifest. Note that camelCase keys are converted to snake_case.

### Example
```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "type": "volume",
    "world_scaling": "dynamic"
  }
}
```
```

--------------------------------

### Configure xr_main_scene in manifest

Source: https://webspatial.dev/docs/api/react-sdk/manifest-options/main-scene

An example of how to include the xr_main_scene property within a Web App Manifest file.

```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "type": "volume",
    "default_size": {
      "width": 100,
      "height": 100,
      "depth": "1m"
    },
    "resizability": {
      "min_width": 50,
      "max_width": 500,
      "min_height": 50,
      "max_height": 500
    },
    "world_scaling": "dynamic",
    "world_alignment": "gravityAligned",
    "baseplate_visibility": "hidden"
  }
}
```

--------------------------------

### Implementing a Reality Container

Source: https://webspatial.dev/docs/api/react-sdk/react-components/Reality

Example of a Reality component configured with a World container, a material, and a 3D box entity.

```jsx
<Reality style={{ width: "500px", height: "500px", "--xr-depth": 100 }}>  
  <Material type="unlit" id="red" color="#ff0000" />  
  <ModelAsset id="teapot" src="https://example.com/model.usdz" />  
  <World>  
    <Box materials={["red"]} width={0.2} height={0.2} depth={0.2} />  
  </World>  
</Reality>
```

--------------------------------

### Value Grammar for --xr-back

Source: https://webspatial.dev/docs/api/react-sdk/css-api/back

Examples of valid pixel values and numeric precision for the --xr-back property.

```css
--xr-back: 20px;  
--xr-back: 20;  
```

```css
--xr-back: 1px;  
--xr-back: 0.5px;  
```

--------------------------------

### Using resizability in Web App Manifest

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/resizability

Example of applying resizability constraints via the Web App Manifest using snake_case keys.

```APIDOC
## Web App Manifest

### Example
```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "resizability": {
      "min_width": 100,
      "min_height": "100px",
      "max_width": 200,
      "max_height": 200
    }
  }
}
```
```

--------------------------------

### DOM API Usage

Source: https://webspatial.dev/docs/api/react-sdk/css-api/back

Example of reading and writing the --xr-back property directly via the DOM element style.

```APIDOC
## DOM API

### Description
Directly manipulate the --xr-back property or read the current offset using the element's style object.

### Examples
```javascript
// Setting the value
ref.current.style["--xr-back"] = animatedOffsetZ;

// Reading the value
const currentOffsetZ = ref.current.style["--xr-back"];
```
```

--------------------------------

### Web App Manifest Configuration

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/type

Defining the scene type for the start scene within the Web App Manifest.

```APIDOC
## Web App Manifest Configuration

### Description
Sets the scene type for the start scene via the Web App Manifest file.

### Example
```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "type": "volume"
  }
}
```
```

--------------------------------

### Define the minimum web manifest

Source: https://webspatial.dev/docs/how-to/minimal-pwa

Provide the required fields for a WebSpatial-ready PWA, including app name, start URL, display mode, and icon assets.

```json
{
  "name": "My Awesome App",
  "start_url": "/",
  "display": "minimal-ui",
  "icons": [
    {
      "src": "/pwa-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/pwa-1024x1024.png",
      "sizes": "1024x1024",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}
```

--------------------------------

### JSX API Usage

Source: https://webspatial.dev/docs/api/react-sdk/css-api/back

Example of applying the --xr-back property to an element using JSX inline styles.

```APIDOC
## JSX API

### Description
Apply the --xr-back property to a component's style object to control its Z-axis position.

### Example
```jsx
export default function Demo({ animatedOffsetZ, animatedOffsetX }) {  
  return (  
    <div  
      style={{  
        "--xr-back": animatedOffsetZ,  
        left: animatedOffsetX,  
      }}></div>  
  );  
}
```
```

--------------------------------

### Apply --xr-back in CSS

Source: https://webspatial.dev/docs/api/react-sdk/css-api/back

Examples of applying the --xr-back custom property within CSS rules for various layout contexts.

```css
p {  
  position: absolute;  
  left: 0;  
  right: 0;  
  --xr-back: 20px;  
}  
```

```css
.product-detail-info {  
  border-radius: 50px;  
  padding: 50px;  
  position: fixed;  
  top: 0;  
  right: 0;  
  bottom: 0;  
  --xr-back: 20px;  
  margin: auto;  
  width: 400px;  
}  
```

```css
.link-card {  
  position: relative;  
  --xr-back: 50px;  
}  
```

--------------------------------

### Set baseplate_visibility in Web App Manifest

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/baseplateVisibility

Configures the baseplate visibility for the start scene using snake_case in the Web App Manifest.

```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "type": "volume",
    "baseplate_visibility": "hidden"
  }
}
```

--------------------------------

### Apply --xr-back in React

Source: https://webspatial.dev/docs/api/react-sdk/css-api/back

Example of applying the --xr-back property via the style attribute in a React component.

```jsx
export default function Demo() {  
  return (  
    <div  
      style={{  
        "--xr-back": "50px",  
        left: "0",  
      }}></div>  
  );  
}  
```

--------------------------------

### Set world_scaling in Web App Manifest

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/worldScaling

Configures the start scene's world_scaling property using snake_case in the Web App Manifest.

```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "type": "volume",
    "world_scaling": "dynamic"
  }
}
```

--------------------------------

### Set default_size in Web App Manifest

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/defaultSize

Configures the default_size for the start scene within a Web App Manifest, using snake_case naming conventions.

```json
{
  "name": "example app",  
  "start_url": "/",  
  "xr_main_scene": {  
    "default_size": {  
      "width": 500,  
      "height": "1000px"  
    }  
  }  
}
```

--------------------------------

### Set scene type in Web App Manifest

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/type

Define the scene type for the start scene within the Web App Manifest configuration.

```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "type": "volume"
  }
}
```

--------------------------------

### Set world_alignment in Web App Manifest

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/worldAlignment

Configures the world_alignment property for the start scene using the Web App Manifest, requiring the use of snake_case.

```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "type": "volume",
    "world_alignment": "gravityAligned"
  }
}
```

--------------------------------

### Scaffold a new WebSpatial project

Source: https://webspatial.dev/docs/introduction/getting-started

Use the starter CLI to initialize a new project structure.

```bash
npx @webspatial/starter create my-webspatial-app
```

--------------------------------

### Preview the app in the simulator

Source: https://webspatial.dev/docs/introduction/getting-started

Use the WebSpatial Builder to package and launch the application in a native simulator.

```bash
webspatial-builder run --base="http://localhost:5173/"  
```

--------------------------------

### Run command syntax

Source: https://webspatial.dev/docs/api/builder/run

The basic command structure for previewing a packaged WebSpatial app in a simulator.

```bash
webspatial-builder run \
  [--base=<base url>] \
  [--manifest=<local path>] \
  [--manifest-url=<url>] \
  [--project=<dist>]
```

--------------------------------

### SpatialDragStartEvent Payload

Source: https://webspatial.dev/docs/api/react-sdk/event-api/spatial-drag

Details the data structure provided during the start of a spatial drag event.

```APIDOC
## SpatialDragStartEvent Payload

### Fields
- **offsetX, offsetY, offsetZ** (px) - The coordinates of the activation position in the local coordinate system of the spatialized element.
- **clientX, clientY, clientZ** (px) - The coordinates of the activation position in the global coordinate system of the Spatial Scene container.
```

--------------------------------

### Publish a WebSpatial App

Source: https://webspatial.dev/docs/api/builder/publish

Command syntax for packaging and uploading an app-store build, including required credentials and optional configuration flags.

```bash
webspatial-builder publish \
  --u=<username> \
  --p=<password> \
  --version=<app version> \
  --bundle-id=<id> \
  --teamId=<id> \
  [--export=<local path>] \
  [--base=<base url>] \
  [--manifest=<local path>] \
  [--manifest-url=<url>] \
  [--project=<dist>]
```

--------------------------------

### Coordinate Conversion Usage

Source: https://webspatial.dev/docs/api/react-sdk/js-api/convertCoordinate

Examples of converting coordinates between elements, windows, and entities using the convertCoordinate function.

```typescript
import { convertCoordinate } from "@webspatial/react-sdk";

const e2e = await convertCoordinate(position, {
  from: elementOrEntity,
  to: elementOrEntity,
});
const e2w = await convertCoordinate(position, {
  from: elementOrEntity,
  to: window,
});
const w2e = await convertCoordinate(position, {
  from: window,
  to: elementOrEntity,
});
```

--------------------------------

### webspatial-builder run

Source: https://webspatial.dev/docs/api/builder/run

Preview a Packaged WebSpatial App in a simulator.

```APIDOC
## webspatial-builder run

### Description
Used to preview a Packaged WebSpatial App in a simulator. It automatically packages the app, launches the simulator, pushes the app bundle into the simulator, installs it, and starts it.

### Syntax
`webspatial-builder run [--base=<base url>] [--manifest=<local path>] [--manifest-url=<url>] [--project=<dist>]`

### Options
- **--base** (string) - Optional - Provides or overrides the base URL used to resolve start_url.
- **--manifest** (string) - Optional - Points Builder at a local Web App Manifest file.
- **--manifest-url** (string) - Optional - Fetches the manifest directly from a live site URL.
- **--project** (string) - Optional - Points Builder at a custom website build output directory.
```

--------------------------------

### Add WebSpatial AI resources

Source: https://webspatial.dev/docs/introduction/getting-started

Integrate AI resources into an existing web project using the CLI.

```bash
npx @webspatial/starter ai
```

--------------------------------

### Build an app bundle for a test device

Source: https://webspatial.dev/docs/api/builder/build

Use this command to generate a native app bundle for a test device, specifying the required bundle ID and team ID for visionOS.

```bash
webspatial-builder build \
  --bundle-id=<id> \
  --teamId=<id> \
  [--export=<local path>] \
  [--base=<base url>] \
  [--manifest=<local path>] \
  [--manifest-url=<url>] \
  [--project=<dist>]
```

--------------------------------

### Build and upload an App Store submission

Source: https://webspatial.dev/docs/how-to/app-store-connect

Use this command to build and publish the application to the App Store. Requires valid account credentials and version information.

```bash
webspatial-builder publish \
  --base=$PRODUCT_SERVER \
  --bundle-id=$APPLE_BUNDLE_ID \
  --teamId=$APPLE_TEAM_ID \
  --version=$APP_VERSION \
  --u=$APPLE_DEV_NAME \
  --p=$APPLE_DEV_PASSWORD  
```

--------------------------------

### initScene

Source: https://webspatial.dev/docs/api/react-sdk/js-api

Configures initialization options for a new Spatial Scene before it is opened.

```APIDOC
## initScene

### Description
Configure initialization options for a new Spatial Scene before it opens.
```

--------------------------------

### Build an IPA for a registered test device

Source: https://webspatial.dev/docs/how-to/app-store-connect

Use this command to generate an IPA file for testing on a registered device. Ensure the Team ID and Bundle ID match your Apple developer account settings.

```bash
webspatial-builder build \
  --base=$PREVIEW_SERVER \
  --bundle-id=$APPLE_BUNDLE_ID \
  --teamId=$APPLE_TEAM_ID  
```

--------------------------------

### Configure resizability with initScene

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/resizability

Apply resizability constraints when initializing a new scene using the initScene function.

```javascript
import { initScene } from "@webspatial/react-sdk";

initScene("newSceneName", defaultConfig => {
  return {
    ...defaultConfig,
    type: "volume",
    resizability: {
      minWidth: 100,
      minHeight: "100px",
      maxWidth: 200,
      maxHeight: 200,
    },
  };
});
window.open(newSceneUrl, "newSceneName");
```

--------------------------------

### initScene Configuration

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/type

Configuring the scene type during the initialization phase using the initScene function.

```APIDOC
## initScene Configuration

### Description
Sets the scene type during the initialization of a new Spatial Scene before opening the window.

### Usage
```javascript
import { initScene } from "@webspatial/react-sdk";

initScene("newSceneName", defaultConfig => {
  return {
    ...defaultConfig,
    type: "volume",
  };
});
window.open(newSceneUrl, "newSceneName");
```

### Parameters
- **type** (string) - Required - The scene type. Accepted values: "window" (default) or "volume".
```

--------------------------------

### Create New Spatial Scenes via JavaScript

Source: https://webspatial.dev/docs/concepts/spatial-scenes

Use the window.open method to programmatically open new spatial scenes.

```javascript
window.open(newSceneUrl);
```

```javascript
window.open(newSceneUrl, "newSceneName");
```

--------------------------------

### initScene configuration

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/worldScaling

How to set the worldScaling property when initializing a new scene using the initScene function.

```APIDOC
## initScene Configuration

### Description
Sets the worldScaling property for a new volume-type Spatial Scene during initialization.

### Usage
```javascript
import { initScene } from "@webspatial/react-sdk";

initScene("newSceneName", defaultConfig => {
  return {
    ...defaultConfig,
    type: "volume",
    worldScaling: "dynamic",
  };
});
```
```

--------------------------------

### Initialize a Spatial Scene with custom configuration

Source: https://webspatial.dev/docs/api/react-sdk/js-api/initScene

Use this function to define custom initialization properties for a scene identified by a specific name. The configuration callback receives the current default settings and returns the modified configuration object.

```javascript
import { initScene } from "@webspatial/react-sdk";  
  
initScene("newSceneName", defaultConfig => {  
  return {  
    ...defaultConfig,  
    type: "volume",  
    defaultSize: {  
      width: "1m",  
      height: "100px",  
      depth: "100px",  
    },  
  };  
});  
window.open(newSceneUrl, "newSceneName");
```

--------------------------------

### Configure resizability in Web App Manifest

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/resizability

Set resizability constraints in the Web App Manifest using snake_case keys.

```json
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "resizability": {
      "min_width": 100,
      "min_height": "100px",
      "max_width": 200,
      "max_height": 200
    }
  }
}
```

--------------------------------

### Initial Value of --xr-back

Source: https://webspatial.dev/docs/api/react-sdk/css-api/back

The default initial value for the --xr-back property.

```css
--xr-back: 0;  
```

--------------------------------

### webspatial-builder publish

Source: https://webspatial.dev/docs/api/builder/publish

Command to package and upload a WebSpatial App to an app store.

```APIDOC
## webspatial-builder publish

### Description
Packages a WebSpatial App and automatically uploads it to an app store. This is primarily used for platforms like visionOS where native app submission is required.

### Syntax
webspatial-builder publish --u=<username> --p=<password> --version=<app version> --bundle-id=<id> --teamId=<id> [--export=<local path>] [--base=<base url>] [--manifest=<local path>] [--manifest-url=<url>] [--project=<dist>]

### Parameters
- **--u** (string) - Required for visionOS - Apple developer account email.
- **--p** (string) - Required for visionOS - App-specific password for the Apple developer account.
- **--version** (string) - Required for visionOS - App version to upload to App Store Connect.
- **--bundle-id** (string) - Required for visionOS - Registered Apple app identifier.
- **--teamId** (string) - Required for visionOS - Apple developer team ID for signing.
- **--export** (string) - Optional - Output path for the generated native app bundle.
- **--base** (string) - Optional - Base URL for resolving start_url.
- **--manifest** (string) - Optional - Path to a local Web App Manifest file.
- **--manifest-url** (string) - Optional - URL to fetch the manifest from.
- **--project** (string) - Optional - Path to a custom website build output directory.
```

--------------------------------

### xr_main_scene Configuration

Source: https://webspatial.dev/docs/api/react-sdk/manifest-options/main-scene

Defines the schema and usage for the xr_main_scene manifest field used to initialize the application's main scene.

```APIDOC
## Web App Manifest: xr_main_scene

### Description
The `xr_main_scene` field (prefixed as `xr_` for standardization) is used in the Web App Manifest to configure the initialization properties of the Start Scene for WebSpatial applications.

### Schema
- **type** (string) - Optional - The type of scene, either "volume" or "window".
- **default_size** (object) - Optional - The initial dimensions of the scene.
  - **width** (number | string) - Optional
  - **height** (number | string) - Optional
  - **depth** (number | string) - Optional
- **resizability** (object) - Optional - Constraints for scene resizing.
  - **min_width** (number | string) - Optional
  - **max_width** (number | string) - Optional
  - **min_height** (number | string) - Optional
  - **max_height** (number | string) - Optional
- **world_scaling** (string) - Optional - Scaling behavior, either "automatic" or "dynamic".
- **world_alignment** (string) - Optional - Alignment behavior, either "automatic" or "gravityAligned".
- **baseplate_visibility** (string) - Optional - Visibility of the baseplate, either "automatic" or "hidden".

### Example
{
  "name": "example app",
  "start_url": "/",
  "xr_main_scene": {
    "type": "volume",
    "default_size": {
      "width": 100,
      "height": 100,
      "depth": "1m"
    },
    "resizability": {
      "min_width": 50,
      "max_width": 500,
      "min_height": 50,
      "max_height": 500
    },
    "world_scaling": "dynamic",
    "world_alignment": "gravityAligned",
    "baseplate_visibility": "hidden"
  }
}
```

--------------------------------

### Using useMetrics for Unit Conversion

Source: https://webspatial.dev/docs/api/react-sdk/js-api/useMetrics

Demonstrates how to access conversion functions and apply world scaling compensation options.

```typescript
import { useMetrics } from "@webspatial/react-sdk";  
  
function UnitConvertTest() {  
  const { pointToPhysical, physicalToPoint } = useMetrics();  
  
  return (  
    <>
      <pre>  
        Scaled conversion  
        {"\n"}  
        physicalToPoint(1): {physicalToPoint(1)}  
        {"\n"}  
        pointToPhysical(1): {pointToPhysical(1)}  
      </pre>  
  
      <pre>  
        Unscaled conversion  
        {"\n"}  
        physicalToPoint(1):{" "}  
        {physicalToPoint(1, { worldScalingCompensation: "unscaled" })}  
        {"\n"}  
        pointToPhysical(1):{" "}  
        {pointToPhysical(1, { worldScalingCompensation: "unscaled" })}  
      </pre>  
    </>
  );  
}
```

--------------------------------

### Set baseplateVisibility with initScene

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/baseplateVisibility

Configures the baseplate visibility during the initialization of a new volume scene.

```javascript
import { initScene } from "@webspatial/react-sdk";  
  
initScene("newSceneName", defaultConfig => {  
  return {  
    ...defaultConfig,  
    type: "volume",  
    baseplateVisibility: "hidden",  
  };  
});  
window.open(newSceneUrl, "newSceneName");
```

--------------------------------

### Create New Spatial Scenes via HTML Links

Source: https://webspatial.dev/docs/concepts/spatial-scenes

Use standard anchor tags with target attributes to trigger the creation of new spatial scenes.

```html
<a href={newSceneUrl} target="_blank">
```

```html
<a href={newSceneUrl} target="newSceneName">
```

--------------------------------

### Apply background-material to a webpage window

Source: https://webspatial.dev/docs/api/react-sdk/css-api/background-material

Sets the background of the root html element to be fully transparent.

```css
html {  
  --xr-background-material: transparent;  
}  
```

--------------------------------

### webspatial-builder build

Source: https://webspatial.dev/docs/api/builder/build

Builds an app bundle for a test device using the specified bundle ID and team ID.

```APIDOC
## CLI Command: webspatial-builder build

### Description
Packages a WebSpatial App into a native app bundle for deployment to a test device. This command handles the packaging process but does not install or launch the app on the device.

### Syntax
`webspatial-builder build --bundle-id=<id> --teamId=<id> [--export=<local path>] [--base=<base url>] [--manifest=<local path>] [--manifest-url=<url>] [--project=<dist>]`

### Options
- **--bundle-id** (string) - Required for visionOS - The registered Apple app identifier.
- **--teamId** (string) - Required for visionOS - The Apple developer team ID used to sign the build.
- **--export** (string) - Optional - The output path for the generated native app bundle.
- **--base** (string) - Optional - The base URL used to resolve the start_url.
- **--manifest** (string) - Optional - Path to a local Web App Manifest file.
- **--manifest-url** (string) - Optional - URL to fetch the manifest from a live site.
- **--project** (string) - Optional - Path to a custom website build output directory.
```

--------------------------------

### Initial value of background-material

Source: https://webspatial.dev/docs/api/react-sdk/css-api/background-material

The default state for the background-material property.

```css
--xr-background-material: none;  
```

--------------------------------

### Using AttachmentEntity in a Reality scene

Source: https://webspatial.dev/docs/api/react-sdk/react-components/Reality

Demonstrates how to define an AttachmentAsset and render it using the AttachmentEntity component within a World.

```jsx
<Reality>  
  <AttachmentAsset name="info">  
    <div style={{ width: "100%" }}>  
      <p>Some text</p>  
    </div>  
  </AttachmentAsset>  
  <World>  
    <Box position={{ x: 0.5, y: -0.2, z: 0.3 }} />  
    <Entity position={{ x: -0.5, y: -0.2, z: 0.3 }}>  
      <AttachmentEntity  
        attachment="info"  
        position={{ x: 0, y: 0, z: 0 }}  
        size={{ width: 100, height: 100 }}  
      />  
    </Entity>  
  </World>  
</Reality>
```

--------------------------------

### Scene Configuration Options

Source: https://webspatial.dev/docs/api/react-sdk/scene-options

The following properties are available to configure the behavior and physical properties of a Spatial Scene.

```APIDOC
## Scene Configuration Properties

### type
- **Description**: Choose whether a new Spatial Scene behaves like a window or a volume.

### defaultSize
- **Description**: Set the initial width, height, and depth a Spatial Scene requests when it is created.

### resizability
- **Description**: Limit how far users can resize a Spatial Scene after it opens.

### worldScaling
- **Description**: Control whether a Spatial Scene keeps a constant apparent size or scales with distance.

### worldAlignment
- **Description**: Control whether a Spatial Scene stays upright, faces the user, or behaves more like a real object.

### baseplateVisibility
- **Description**: Show or hide the baseplate under a volume Spatial Scene.
```

--------------------------------

### Link the web manifest in HTML

Source: https://webspatial.dev/docs/how-to/minimal-pwa

Include this link tag in the head of every HTML document to associate the web manifest with the application.

```html
<link rel="manifest" href="/app.webmanifest" />
```

--------------------------------

### Temporary manifest structure

Source: https://webspatial.dev/docs/api/builder/run

The default manifest configuration used by the builder when no project manifest is detected.

```json
{
  name: "WebSpatialTest",
  display: "minimal-ui",
  start_url: "/",
  scope: "/",
}
```

--------------------------------

### Importing Reality and 3D Engine Components

Source: https://webspatial.dev/docs/api/react-sdk/react-components/Reality

Required imports from the @webspatial/react-sdk package to utilize Reality and its associated 3D engine components.

```javascript
import {  
  Reality,  
  Material,  
  ModelAsset,  
  AttachmentAsset,  
  World,  
  Entity,  
  Box,  
  Sphere,  
  Plane,  
  Cone,  
  Cylinder,  
  ModelEntity,  
  AttachmentEntity,  
} from "@webspatial/react-sdk";
```

--------------------------------

### Monitor spatialized elements with enable-xr-monitor

Source: https://webspatial.dev/docs/api/react-sdk/react-components/jsx-marker

Apply enable-xr-monitor to a parent container to synchronize layout updates for spatialized children.

```jsx
function CardList() {  
  const [showFirstCard, setShowFirstCard] = useState(true);  
  
  const onClick = () => {  
    setShowFirstCard(prevState => !prevState);  
  };  
  
  return (  
    <div enable-xr-monitor>  
      {showFirstCard && <div>first card</div>}  
      <div enable-xr>second card</div>  
      <button onClick={onClick}>toggle</button>  
    </div>  
  );  
}  
```

--------------------------------

### navigator.userAgent

Source: https://webspatial.dev/docs/api/react-sdk/dom-api/userAgent

Access the user agent string to detect the current runtime environment and device capabilities.

```APIDOC
## navigator.userAgent

### Description
Obtains information about the current device, operating system, and runtime environment. This property is read-only and available on the `navigator` object.

### Usage
```javascript
const ua = navigator.userAgent.toString();
```

### Detection Logic
- **WebSpatial Runtime**: Matches `/WebSpatial\/(\S+)/`.
- **WebXR Support**: Matches `/\sVR\s/`.
- **WebView**: Matches `/\swv\)/`.
- **Packaged WebSpatial App**: Matches `/WSAppShell\/(\S+)/` (includes visionOS if also matching "Macintosh").
- **PICO OS 6 Web App Runtime**: Matches `/PicoWebApp\/(\S+)/`.
```

--------------------------------

### userAgent

Source: https://webspatial.dev/docs/api/react-sdk/dom-api

Inspects the current device, operating system, and whether the application is running in WebSpatial mode.

```APIDOC
## userAgent

### Description
Inspect the current device, operating system, and whether the app is running in WebSpatial mode.
```

--------------------------------

### Set worldScaling via initScene

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/worldScaling

Configures worldScaling during the initialization of a new volume-type scene.

```javascript
import { initScene } from "@webspatial/react-sdk";  
  
initScene("newSceneName", defaultConfig => {  
  return {  
    ...defaultConfig,  
    type: "volume",  
    worldScaling: "dynamic",  
  };  
});  
window.open(newSceneUrl, "newSceneName");
```

--------------------------------

### Set defaultSize via initScene

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/defaultSize

Configures the defaultSize for a new scene during the initialization process using the initScene function.

```javascript
import { initScene } from "@webspatial/react-sdk";  
  
initScene("newSceneName", defaultConfig => {  
  return {  
    ...defaultConfig,  
    type: "volume",  
    defaultSize: {  
      width: 500,  
      height: "1000px",  
      depth: "1m",  
    },  
  };  
});  
window.open(newSceneUrl, "newSceneName");  
```

--------------------------------

### defaultSize Configuration

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/defaultSize

The defaultSize property allows developers to specify the initial dimensions of a scene. It accepts width, height, and depth as numbers or strings with unit suffixes.

```APIDOC
## defaultSize

### Description
Defines the initial size of a Spatial Scene upon creation. Note that the operating system's spatial computing logic may override these values.

### Type Signature
```typescript
{
  width?: number | string
  height?: number | string
  depth?: number | string
}
```

### Accepted Values
- **width** (number | string) - Scene width. Defaults to px if a number is provided; supports units like 'px' or 'm'.
- **height** (number | string) - Scene height. Defaults to px if a number is provided; supports units like 'px' or 'm'.
- **depth** (number | string) - Scene depth (for volume scenes). Defaults to px if a number is provided; supports units like 'px' or 'm'.
```

--------------------------------

### Set scene type using initScene

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/type

Configure the scene type during the initialization phase before opening the window.

```typescript
import { initScene } from "@webspatial/react-sdk";  
  
initScene("newSceneName", defaultConfig => {  
  return {  
    ...defaultConfig,  
    type: "volume",  
  };  
});  
window.open(newSceneUrl, "newSceneName");
```

--------------------------------

### Define the main_scene schema

Source: https://webspatial.dev/docs/api/react-sdk/manifest-options/main-scene

The schema defines the structure and allowed values for the xr_main_scene configuration object.

```json
{
  type?: "volume" | "window"
  default_size?: {
    width?: number | string
    height?: number | string
    depth?: number | string
  }
  resizability?: {
    min_width?: number | string
    max_width?: number | string
    min_height?: number | string
    max_height?: number | string
  }
  world_scaling?: "automatic" | "dynamic"
  world_alignment?: "automatic" | "gravityAligned"
  baseplate_visibility?: "automatic" | "hidden"
}
```

--------------------------------

### ModelAsset

Source: https://webspatial.dev/docs/api/react-sdk/react-components/Reality

Declares a 3D model asset to be loaded into the scene.

```APIDOC
## <ModelAsset />

### Description
Declares a 3D model file source to be used within the Reality environment.

### Props
- **id** (string) - Required - Unique identifier for the model.
- **src** (string) - Required - URL to the 3D model file (e.g., .usdz).
- **onLoad** (function) - Optional - Callback triggered when the model loads successfully.
- **onError** (function) - Optional - Callback triggered when the model fails to load.
```

--------------------------------

### Apply enable-xr via inline style

Source: https://webspatial.dev/docs/api/react-sdk/react-components/jsx-marker

Include enableXr: true within the element's inline style object.

```jsx
<div className="card" style={{ enableXr: true, marginTop: "10px" }}></div>
```

--------------------------------

### baseplateVisibility Configuration

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/baseplateVisibility

Configuring the baseplateVisibility property for volume scenes using the React SDK or Web App Manifest.

```APIDOC
## baseplateVisibility

### Description
Controls the visibility of the baseplate under a volume-type Spatial Scene. Only applicable to scenes of type `volume`.

### Type Signature
`"automatic" | "hidden"`

### Default Value
`"automatic"`

### Accepted Values
- **"automatic"**: The baseplate is shown when needed.
- **"hidden"**: The baseplate is always hidden.

### Usage Examples

#### Using initScene
```javascript
import { initScene } from "@webspatial/react-sdk";

initScene("newSceneName", defaultConfig => {
  return {
    ...defaultConfig,
    type: "volume",
    baseplateVisibility: "hidden",
  };
});
```

#### Using Web App Manifest
```json
{
  "xr_main_scene": {
    "type": "volume",
    "baseplate_visibility": "hidden"
  }
}
```
```

--------------------------------

### Set worldAlignment using initScene

Source: https://webspatial.dev/docs/api/react-sdk/scene-options/worldAlignment

Configures the worldAlignment property during the initialization of a new volume-type scene.

```javascript
import { initScene } from "@webspatial/react-sdk";  
  
initScene("newSceneName", defaultConfig => {  
  return {  
    ...defaultConfig,  
    type: "volume",  
    worldAlignment: "gravityAligned",  
  };  
});  
window.open(newSceneUrl, "newSceneName");
```

--------------------------------

### Integrate SSRProvider in Hydrogen

Source: https://webspatial.dev/docs/how-to/ssr

Include SSRProvider within the client entry file for Hydrogen applications to support proper hydration.

```javascript
import { HydratedRouter } from "react-router/dom";  
import { startTransition, StrictMode } from "react";  
import { hydrateRoot } from "react-dom/client";  
import { NonceProvider } from "@shopify/hydrogen";  
import { SSRProvider } from "@webspatial/react-sdk";  
  
if (!window.location.origin.includes("webcache.googleusercontent.com")) {  
  startTransition(() => {  
    const existingNonce = document.querySelector("script[nonce]")?.nonce;  
  
    hydrateRoot(  
      document,  
      <StrictMode>  
        <NonceProvider value={existingNonce}>  
          <SSRProvider>  
            <HydratedRouter />  
          </SSRProvider>  
        </NonceProvider>  
      </StrictMode>,  
    );  
  });  
}
```

--------------------------------

### Configure JSX Runtime in Rsbuild

Source: https://webspatial.dev/docs/how-to/rspack

Use the pluginReact configuration within rsbuild.config.ts to set the importSource for the WebSpatial SDK.

```typescript
import { defineConfig } from "@rsbuild/core";  
import { pluginReact } from "@rsbuild/plugin-react";  
  
export default defineConfig({  
  plugins: [  
    pluginReact({  
      swcReactOptions: {  
        runtime: "automatic",  
        importSource: "@webspatial/react-sdk",  
      },  
    }),  
  ],  
});
```

--------------------------------

### Initial Transform Values

Source: https://webspatial.dev/docs/api/react-sdk/css-api/transform

The default state for the transform property.

```css
transform: none;  
```

```css
transform: translate3d(0, 0, 0) rotate(0deg) scale(1);  
```

--------------------------------

### useMetrics

Source: https://webspatial.dev/docs/api/react-sdk/js-api

Converts between 2D pixel units and real-world meter units within WebSpatial layouts.

```APIDOC
## useMetrics

### Description
Convert between 2D pixel units and real-world meter units inside WebSpatial layouts.
```

--------------------------------

### Render a spatialized 3D model with Model component

Source: https://webspatial.dev/docs/api/react-sdk/react-components/Model

Use the enable-xr attribute to enable volumetric 3D rendering in the space in front of the 2D plane.

```javascript
import { Model } from "@webspatial/react-sdk";  
  
function Example() {  
  return (  
    <Model  
      enable-xr  
      src="/modelasset/vehicle.usdz"  
      style={{ height: "200px", "--xr-depth": "100px" }}  
    />  
  );  
}  
```

--------------------------------

### Initial value of depth

Source: https://webspatial.dev/docs/api/react-sdk/css-api/depth

The default value for the --xr-depth property.

```css
--xr-depth: 0;  
```

--------------------------------

### Configure JSX Runtime in tsconfig.json

Source: https://webspatial.dev/docs/introduction/getting-started

Set the jsxImportSource to the WebSpatial React SDK to enable the required JSX runtime.

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@webspatial/react-sdk",
// ...
```

--------------------------------

### Render Models with ModelEntity

Source: https://webspatial.dev/docs/api/react-sdk/react-components/Reality

Load a 3D model once using ModelAsset and reference it multiple times with ModelEntity to optimize performance.

```jsx
import { Reality, World, ModelAsset, ModelEntity } from "@webspatial/react-sdk";  
  
function SpaceshipFleet() {  
  return (  
    <Reality style={{ width: "100%", height: "500px" }}>  
      {/* --- 1. THE RESOURCE --- */}  
      {/* This downloads the file once. It is INVISIBLE right now. */}  
      <ModelAsset  
        id="ship-blueprint"  
        src="https://example.com/fighter-jet.usdz"  
      />  
  
      {/* --- 2. THE SCENE --- */}  
      <World>  
        {/* Leader Ship: Center, Normal Size */}  
        <ModelEntity  
          model="ship-blueprint" // Points to the ID above  
          position={{ x: 0, y: 0, z: 0 }}  
          scale={{ x: 1, y: 1, z: 1 }}  
        />  
  
        {/* Left Wingman: Moved left, slightly smaller */}  
        <ModelEntity  
          model="ship-blueprint" // Reuses the same loaded file!  
          position={{ x: -0.5, y: -0.2, z: 0.3 }}  
          scale={{ x: 0.8, y: 0.8, z: 0.8 }}  
        />  
  
        {/* Right Wingman: Moved right, slightly smaller */}  
        <ModelEntity  
          model="ship-blueprint" // Reuses the same loaded file  
          position={{ x: 0.5, y: -0.2, z: 0.3 }}  
          scale={{ x: 0.8, y: 0.8, z: 0.8 }}  
        />  
      </World>  
    </Reality>  
  );  
}  
```

--------------------------------

### Apply enable-xr via className

Source: https://webspatial.dev/docs/api/react-sdk/react-components/jsx-marker

Add the __enableXr__ class to an element's className to enable spatialization.

```jsx
<div className="card __enableXr__"></div>
```
Tokens:
Raw