m-position-probe

[MarcusLongmuir]

This PR adds a new element, m-position-probe as initially discussed in #29 and tracked in #64.

The presence of an m-position-probe element in a client is a request for the user's client to send their avatar/camera position (experience-dependent) as positionenter, positionmove, and positionleave events to the element.

The range and interval are configurable to allow the m-position-probe element to be tuned to the necessary interest distance and update frequency. The default is 10 (meters) and 1000 (milliseconds) / 1 second.

The events sent by a conforming client include both a elementRelative and documentRelative position and rotation:

e.g.

{
  "type": "positionmove",
  "detail": {
    "elementRelative": {
      "position": { "x": 2, "y": 4, "z": 6 },
      "rotation": { "x": 0, "y": 90, "z": 0 }
    },
    "documentRelative": {
      "position": { "x": 12, "y": 24, "z": 36 },
      "rotation": { "x": 0, "y": 90, "z": 0 }
    }
}

---

What kind of changes does your PR introduce? (check at least one)

• Feature

Does your PR introduce a breaking change? (check one)

• Yes

If yes, please describe its impact and migration path for existing applications:

ScenePosition has been renamed to PositionAndRotation to be more explicit about the contents.
getUserPosition has been renamed to getUserPositionAndRotation to be more explicit about including rotation.

Does your PR fulfill the following requirements?

• All tests are passing
• The title references the corresponding issue # (if relevant)

Resolves #64

[michavie]

For events that are part of the developer API, I think it would make developer lives easier if we strongly typed exposed data of CustomEvents:

Thinking of something like:

type MmlEventPositionEnterDetail = {
  elementRelative: ...
  documentRelative: ...
}

export type MmlEventPositionEnter = CustomEvent<MmlEventPositionEnterDetail>

new CustomEvent<MmlEventPositionEnterDetail>(positionProbeEnterEventName, {
  detail: {
    elementRelative: elementRelativePositionAndRotation,
    documentRelative: documentRelativePositionAndRotation,
  },
}),

So developers have type-safety when listening to events:

positionProbe.addEventListener("positionenter", (event: MmlEventPositionEnter) => {
    const { connectionId, elementRelative, documentRelative } = event.detail;
  });

or designing the event system to use subclasses of CustomEvent

[MarcusLongmuir]

@michavie - That's a good point. I just took a look at doing this quickly, but it seems the types and exports are a non-trivial change to import so I think we do that in a separate change and do it across more than just this element. Can you create an issue with the above please?

And a related query on the last code example - that would require the author's environment to include the type definitions for the m- elements and their associated events so that the listener can be typed. That seems like a separate challenge to just using the schema types in the library implementation.