aframe-hotspots/README.md

A-Frame component for interactive VR hotspots with audio and scene transitions

## 🎯 Usage Guide

### Basic Setup

```html
<a-entity id="spots" hotspots>
  <!-- Initial visible group -->
  <a-entity id="group-point1" visible="true">
    <a-image
      face-camera
      spot="linkto:#point2; spotgroup:group-point2; label:Conference Room"
      position="-11 0 2"
    >
    </a-image>
  </a-entity>

  <!-- Hidden group (activated later) -->
  <a-entity id="group-point2" visible="false">
    <a-image
      face-camera
      spot="linkto:#point1; spotgroup:group-point1; label:Return"
      position="10 0 -8"
    >
    </a-image>
  </a-entity>
</a-entity>
```

### Key Concepts

1. **Hotspot Groups** (`<a-entity id="group-*"`):

   - Organize hotspots into logical groups (one per scene/location)
   - Only **one group** should have `visible="true"` initially
   - Switch between groups using the `spotgroup` property

2. **Spot Component** (`spot=""`):

   ```html
   spot="linkto:#TARGET_PANO; spotgroup:GROUP_ID; label:YOUR_TEXT;
   audio:#AUDIO_ID; labelBackground:#COLOR; labelPadding:0.2"
   ```

   - `linkto`: Target panorama ID (matches your `<img id>`)
   - `spotgroup`: Next group to show when clicked
   - `label`: Text display under hotspot
   - `audio`: Optional audio element ID
   - `labelBackground`: Label background color
   - `labelPadding`: Text padding around label

3. **Navigation Flow**:
   ```mermaid
   graph LR
   A[Current Group] -->|click spot| B[New Group]
   B -->|spotgroup| C[Next Scene]
   ```

### Full Implementation Steps

1. Install the package:

```bash
npm install aframe-hotspots
```

2. Add required assets:

```html
<a-assets>
  <img id="point1" src="scene1.jpg" />
  <img id="point2" src="scene2.jpg" />
  <img id="hotspot" src="arrow.png" />
  <audio id="ambient" src="sound.mp3"></audio>
</a-assets>
```

3. Set up your scene structure:

```html
<a-scene>
  <!-- Hotspot system -->
  <a-entity id="spots" hotspots>
    <!-- First visible group -->
    <a-entity id="entrance" visible="true">
      <a-image
        face-camera
        spot="linkto:#main-hall; spotgroup:main-hall; label:Enter Main Hall"
        position="0 1.6 -3"
      >
      </a-image>
    </a-entity>

    <!-- Secondary group -->
    <a-entity id="main-hall" visible="false">
      <a-image
        face-camera
        spot="linkto:#entrance; spotgroup:entrance; label:Exit"
        position="0 1.6 3"
      >
      </a-image>
    </a-entity>
  </a-entity>

  <!-- Panorama viewer -->
  <a-sky id="skybox" src="#entrance-scene"></a-sky>
</a-scene>
```

### Advanced Features

**Audio Hotspots**:

```html
<a-image
  face-camera
  spot="audio:#info-audio; label:Audio Guide"
  position="2 1.5 -4"
>
</a-image>
```

**Custom Labels**:

```html
spot="label:Meeting Room; labelBackground:#FF0000; labelPadding:0.4;
lineHeight:50"
```

### Lifecycle Flow

1. Initial group (`visible="true"`) shows hotspots
2. Clicking a spot:
   - Changes panorama via `linkto`
   - Hides current group
   - Shows new `spotgroup`
   - Plays/pauses audio if configured

### Best Practices

- Keep group IDs descriptive (`lobby`, `gallery-1`, etc)
- Position hotspots using camera coordinates (X,Y,Z)
- Test group visibility transitions using:
  ```js
  document.getElementById("spots").emit("reloadspots", {
    newspots: "new-group-id",
    currspots: "current-group-id",
  });
  ```
  ## 📬 Connect with Me
- 🌐 [Portfolio](https://sagargada73.github.io/)
- 🔗 [LinkedIn](https://www.linkedin.com/in/sagar-gada/)