name	world-space-annotations
description	Use when building Ankhora's in-MR annotation panels — a world-space text/label placed in real space (bound to a spatial anchor), readable and pokeable by the learner. Triggers: annotation, label, text panel, world-space canvas, callout, note in space, TextMeshPro in VR, poke panel, info bubble, step instruction panel.

World-space annotations

An annotation is Ankhora's atomic teaching unit: a short piece of text/marker placed in the real room (via a spatial anchor) that the learner reads and can interact with. This skill is the recipe for one; it sits on top of spatial-anchors, new-xr-interaction, and the xr-ui-design design language.

Anatomy of an annotation

A world-space Canvas (not screen-space) holding TextMeshPro text (TMP is sharp at distance; default UI text is not). Size it for arm's-reach-to-2 m legibility — see xr-ui-design.
Anchored in space: parent the annotation under an OVRSpatialAnchor (see spatial-anchors) so it stays on the real object as the learner moves. Store its annotationId + anchorId in the record/replay data (record-replay-contract).
Interaction (optional): make it pokeable with meta_add_canvas_interaction_poke (near, in-reach) or ray for far panels — go through Meta's Interaction SDK, never custom raycasts (Horizon Store requirement; see horizon-store-compliance).

Behaviour choices (decide per annotation)

World-locked vs billboard: instructions tied to a physical spot stay world-locked; a floating hint may billboard to face the learner. Default to world-locked for "this part here".
Legibility against passthrough: the real room is the background — use a solid/contrasting panel backing and emissive text so it reads over a bright kitchen/workshop (see urp-shadergraph).
Reveal timing: annotations appear/disappear as timeline events during replay (AnnotationShown / AnnotationHidden in the contract), not all at once.

Workflow over MCP

Build the canvas + TMP via Unity_ManageGameObject / Unity_ManageAsset; add poke interaction via meta_add_canvas_interaction_poke (call meta_get_config_information first).
Keep annotation data (id, text, anchor binding, show/hide times) in the contract DTO; the MonoBehaviour just renders it.

Verify

Unity_SceneView_Capture2DScene: panel is legible, correctly placed, faces sanely.
On device/simulator: poke works, text stays anchored as you move, readable over passthrough.
Unity_ReadConsole: clean.

Out of scope

Rich media annotations (video/3D widgets), authoring UI for end-users, localisation — V2. MVP = one short text annotation, anchored, optionally pokeable.

World-space annotations

Anatomy of an annotation

A world-space Canvas (not screen-space) holding TextMeshPro text (TMP is sharp at distance; default UI text is not). Size it for arm's-reach-to-2 m legibility — see xr-ui-design.

Anchored in space: parent the annotation under an OVRSpatialAnchor (see spatial-anchors) so it stays on the real object as the learner moves. Store its annotationId + anchorId in the record/replay data (record-replay-contract).

Interaction (optional): make it pokeable with meta_add_canvas_interaction_poke (near, in-reach) or ray for far panels — go through Meta's Interaction SDK, never custom raycasts (Horizon Store requirement; see horizon-store-compliance).

Behaviour choices (decide per annotation)

World-locked vs billboard: instructions tied to a physical spot stay world-locked; a floating hint may billboard to face the learner. Default to world-locked for "this part here".

Legibility against passthrough: the real room is the background — use a solid/contrasting panel backing and emissive text so it reads over a bright kitchen/workshop (see urp-shadergraph).

Reveal timing: annotations appear/disappear as timeline events during replay (AnnotationShown / AnnotationHidden in the contract), not all at once.

Workflow over MCP

Build the canvas + TMP via Unity_ManageGameObject / Unity_ManageAsset; add poke interaction via meta_add_canvas_interaction_poke (call meta_get_config_information first).

Keep annotation data (id, text, anchor binding, show/hide times) in the contract DTO; the MonoBehaviour just renders it.

Verify

Unity_SceneView_Capture2DScene: panel is legible, correctly placed, faces sanely.

On device/simulator: poke works, text stays anchored as you move, readable over passthrough.

Unity_ReadConsole: clean.

Out of scope

Rich media annotations (video/3D widgets), authoring UI for end-users, localisation — V2. MVP = one short text annotation, anchored, optionally pokeable.

world-space-annotations