🎯 Usage Guide

Basic Setup

<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=""):

   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:

   graph LR
   A[Current Group] -->|click spot| B[New Group]
   B -->|spotgroup| C[Next Scene]

Full Implementation Steps

1. Install the package:

npm install aframe-hotspots

2. Add required assets:

<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:

<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:

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

Custom Labels:

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:

  document.getElementById("spots").emit("reloadspots", {
    newspots: "new-group-id",
    currspots: "current-group-id",
  });

  📬 Connect with Me

• 🌐 Portfolio
• 🔗 LinkedIn