Android XR Runtime

This document defines the Android XR / SceneCore implementation and verification of the Elonn Runtime.

Shared Runtime semantics, including Carry, Field, Entry, Dataset interpretation, and Runtime responsibilities, are defined by runtime-authoring-guide.md. This document does not redefine them.

Spatial presentation

Android XR realizes the canonical Carry and Field behaviors using SceneCore entities, coordinate spaces, poses, and lifecycle.

SceneCore mechanisms are implementation details. They do not introduce additional Elonn layers or change Dataset semantics.

Field

Field content is world-fixed in position.

For geographic Field placements:

• bearing follows the true geographic bearing;
• radial distance is Runtime presentation rather than literal geographic distance;
• vertical placement follows the Earth's curvature using the real geographic distance, so sufficiently distant locations fall below the horizon;
• markers continuously face the member.

The result is not a fixed-height ring. Radius may be compressed for useful XR presentation while bearing and curvature preserve the meaningful geometry of the location.

Marker position and marker facing are separate behaviors. A marker remains world-fixed in position while its orientation changes as necessary to face the member.

Carry

Carry is viewer-relative.

Carry remains at its defined offset from the viewer as the member moves and turns. Head rotation therefore rotates Carry with the member rather than exposing Carry as an object fixed in the surrounding world.

The Carry area is intentionally larger than the visible view. Content may occupy portions of Carry outside the member's current field of view and become visible as the member turns their head.

Entry is presented on Carry and is Elonn's main interface.

SceneCore reasoning

Spatial behavior must be understood from the actual SceneCore implementation:

• entity hierarchy;
• parent relationships;
• coordinate spaces;
• poses;
• pose ownership and updates;
• entity and session lifecycle.

For any spatial problem, establish which coordinate space controls the object and what happens to that coordinate space when the member translates or rotates.

Position, orientation, and size are separate properties and should be investigated separately when possible.

When behavior previously worked differently, use git history to identify the relevant implementation and compare it with the current implementation.

Android XR and phone

Android XR and ordinary Android are presentation backends for the same World Dataset.

Android XR uses SceneCore where appropriate. Ordinary Android uses its phone presentation, including its ARCore Field implementation.

Different device capabilities may require different presentation mechanisms without changing canonical Elonn semantics.

Verification

A successful build verifies only that the code builds.

XR behavior is verified by running the Runtime and moving through the environment.

Translation

Use emulator navigation to test translation.

For Field, verify that the member can:

• approach a marker;
• retreat from it;
• move laterally relative to it;
• pass it;
• move around and behind it.

The marker's position must remain fixed in the surrounding world.

For Carry, verify that translation does not leave Carry behind in the surrounding world.

Head rotation

Head rotation requires interactive emulator control; it cannot be established through adb alone.

Test rotation manually in the emulator.

For each rotation test:

1. Establish the initial view.
2. Capture the initial state.
3. Rotate the simulated head without restarting the Runtime or XR session.
4. Capture the resulting state.
5. Compare the before-and-after captures from that same session.

For Field, verify that marker positions remain world-fixed while the markers continuously turn to face the member.

For Carry, verify that Carry turns with the member and maintains its viewer-relative offset.

The Carry area is larger than the visible view, so head rotation should reveal different portions of Carry rather than exposing it as a world-fixed panel.

Translation and head rotation should be tested independently when diagnosing spatial behavior.

Workflow

For each XR behavior:

1. Read runtime-authoring-guide.md and relevant Agents context.
2. Inspect the current implementation.
3. Inspect relevant git history when prior behavior matters.
4. Identify the SceneCore hierarchy, coordinate space, poses, and update behavior involved.
5. Explain the observed behavior.
6. Propose the smallest change.
7. Review the proposal.
8. Implement the agreed change.
9. Build and run it.
10. Verify translation and/or head rotation as appropriate.
11. Record verified work and decisions in Agents.

Work on one spatial behavior at a time.

Implementation reports should distinguish what was observed, what was established from code or documentation, and what remains a hypothesis.