From 48688544f15e9a9ac37d4aa9a58ed21118b10102 Mon Sep 17 00:00:00 2001
From: Pihkaal <pihkaal@proton.me>
Date: Sun, 22 Feb 2026 21:16:13 +0100
Subject: [PATCH] feat(nds): add help button with hints for all physical
 buttons

---
 app/components/NDS2D.vue | 116 ++++++-------------
 app/components/NDS3D.vue | 234 +++++++++++++++++++++++++++++----------
 app/pages/index.vue      | 160 ++++++++++++++++++++++----
 app/stores/app.ts        |  20 ++++
 app/stores/gallery.ts    |   2 +
 app/stores/intro.ts      |   6 +-
 6 files changed, 377 insertions(+), 161 deletions(-)

diff --git a/app/components/NDS2D.vue b/app/components/NDS2D.vue
index e9b5a80..f0a43e8 100644
--- a/app/components/NDS2D.vue
+++ b/app/components/NDS2D.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import gsap from "gsap";
 
+const app = useAppStore();
 const ndsScale = ref(1);
-const showHelp = ref(false);
-const helpTimeline = ref<gsap.core.Timeline | null>(null);
+const hintsContainer = useTemplateRef<HTMLElement>("hintsContainer");
 
 const updateScale = () => {
   const scaleX = (window.innerWidth - 40) / 235;
@@ -11,72 +11,37 @@ const updateScale = () => {
   ndsScale.value = Math.min(scaleX, scaleY);
 };
 
-const animateHelpLabels = async (yoyo = false) => {
-  if (showHelp.value) return;
-  showHelp.value = true;
-
-  helpTimeline.value?.kill();
-
-  await nextTick();
-  const timeline = gsap
-    .timeline()
-    .fromTo(
-      ".nds2d-hints-container",
-      { opacity: 0 },
-      { opacity: 1, duration: 0.2, ease: "power1.out" },
-    )
-    .to(
-      ".nds2d-help-btn",
-      { color: "#ffffff", opacity: 1, duration: 0.2, ease: "power1.out" },
-      "<",
-    )
-    .to(".nds2d-hints-container", {
-      opacity: 0,
-      duration: 0.2,
-      ease: "power1.in",
-      delay: 3,
-    })
-    .to(
-      ".nds2d-help-btn",
-      { color: "#666666", opacity: 0.5, duration: 0.2, ease: "power1.in" },
-      "<",
-    )
-    .call(() => {
-      showHelp.value = false;
-    });
-
-  if (yoyo) {
-    timeline.to(".nds2d-help-btn", {
-      color: "#ffffff",
-      opacity: 1,
-      duration: 0.3,
-      repeat: 5,
-      yoyo: true,
-      delay: 0.3,
-    });
-  }
-
-  helpTimeline.value = timeline;
-};
-
-onMounted(async () => {
+onMounted(() => {
   updateScale();
   window.addEventListener("resize", updateScale);
-
-  if (ndsScale.value >= 1) {
-    await animateHelpLabels(true);
-  }
-});
-
-useKeyDown(async ({ key }) => {
-  if (key.toLocaleLowerCase() === "h") {
-    await animateHelpLabels();
-  }
 });
 
 onUnmounted(() => {
   window.removeEventListener("resize", updateScale);
 });
+
+watch(
+  () => app.hintsVisible,
+  async (show) => {
+    await nextTick();
+    if (!hintsContainer.value) return;
+    if (show) {
+      gsap.fromTo(
+        hintsContainer.value,
+        { opacity: 0 },
+        { opacity: 1, duration: 0.2, ease: "power1.out" },
+      );
+    } else {
+      gsap.to(hintsContainer.value, {
+        opacity: 0,
+        duration: 0.2,
+        ease: "power1.in",
+      });
+    }
+  },
+);
+
+defineExpose({ ndsScale });
 </script>
 
 <template>
@@ -122,7 +87,11 @@ onUnmounted(() => {
         <div class="nds2d-small-button nds2d-start"></div>
         <div class="nds2d-small-button nds2d-select"></div>
 
-        <div v-if="showHelp" class="nds2d-hints-container">
+        <div
+          ref="hintsContainer"
+          class="nds2d-hints-container"
+          style="opacity: 0"
+        >
           <div class="nds2d-hint nds2d-hint-dpad">Arrows</div>
           <div class="nds2d-hint nds2d-hint-x">{{ mapNDSToKey("X") }}</div>
           <div class="nds2d-hint nds2d-hint-a">{{ mapNDSToKey("A") }}</div>
@@ -137,8 +106,6 @@ onUnmounted(() => {
         </div>
       </div>
     </div>
-
-    <button class="nds2d-help-btn" @click="animateHelpLabels()">?</button>
   </div>
 </template>
 
@@ -602,25 +569,4 @@ onUnmounted(() => {
   bottom: 28px;
   transform: translateX(-100%);
 }
-
-.nds2d-help-btn {
-  position: fixed;
-  bottom: 16px;
-  left: 16px;
-  width: 30px;
-  height: 30px;
-  border: none;
-  border-radius: 50%;
-  background: rgba(255, 255, 255, 0.1);
-  color: #666;
-  font-size: 18px;
-  cursor: pointer;
-  opacity: 0.5;
-  transition: opacity 0.2s;
-  user-select: none;
-}
-
-.nds2d-help-btn:hover {
-  opacity: 1;
-}
 </style>
diff --git a/app/components/NDS3D.vue b/app/components/NDS3D.vue
index 38e8e22..7173368 100644
--- a/app/components/NDS3D.vue
+++ b/app/components/NDS3D.vue
@@ -2,6 +2,7 @@
 import { useLoop, useTresContext } from "@tresjs/core";
 import * as THREE from "three";
 import gsap from "gsap";
+import { mapNDSToKey } from "~/utils/input";
 
 const INTRO_ANIMATION = {
   MODEL_SPIN_DURATION: 3,
@@ -55,7 +56,7 @@ const requireMesh = (key: string): THREE.Mesh => {
   return mesh;
 };
 
-const { camera, renderer } = useTresContext();
+const { camera, renderer, scene } = useTresContext();
 
 model.scale.set(100, 100, 100);
 
@@ -101,61 +102,57 @@ const animateIntro = () => {
   if (hasAnimated.value) return;
   hasAnimated.value = true;
 
-  const introTimeline = gsap.timeline();
-
-  introTimeline.to(
-    camera.activeCamera.value.position,
-    {
-      x: INTRO_ANIMATION.CAMERA_END_POSITION.x,
-      y: INTRO_ANIMATION.CAMERA_END_POSITION.y,
-      z: INTRO_ANIMATION.CAMERA_END_POSITION.z,
-      duration: INTRO_ANIMATION.CAMERA_DURATION,
-      ease: "power2.inOut",
-    },
-    0,
-  );
-
-  introTimeline.to(
-    camera.activeCamera.value.rotation,
-    {
-      x: INTRO_ANIMATION.CAMERA_END_ROTATION.x,
-      y: INTRO_ANIMATION.CAMERA_END_ROTATION.y,
-      z: INTRO_ANIMATION.CAMERA_END_ROTATION.z,
-      duration: INTRO_ANIMATION.CAMERA_DURATION,
-      ease: "power2.inOut",
-    },
-    0,
-  );
-
-  introTimeline.to(
-    model.rotation,
-    {
-      y: Math.PI * 2,
-      duration: INTRO_ANIMATION.MODEL_SPIN_DURATION,
-      ease: "power2.inOut",
-    },
-    0,
-  );
-
-  introTimeline.to(
-    lidMesh.rotation,
-    {
-      x: INTRO_ANIMATION.LID_OPENED_ROTATION,
-      duration: INTRO_ANIMATION.LID_OPEN_DURATION,
-      ease: "power2.out",
-    },
-    INTRO_ANIMATION.MODEL_SPIN_DURATION - INTRO_ANIMATION.LID_OPEN_OVERLAP,
-  );
-
-  introTimeline.to(
-    topScreenMesh.rotation,
-    {
-      x: INTRO_ANIMATION.LID_OPENED_ROTATION,
-      duration: INTRO_ANIMATION.LID_OPEN_DURATION,
-      ease: "power2.out",
-    },
-    "<",
-  );
+  gsap
+    .timeline()
+    .to(
+      camera.activeCamera.value.position,
+      {
+        x: INTRO_ANIMATION.CAMERA_END_POSITION.x,
+        y: INTRO_ANIMATION.CAMERA_END_POSITION.y,
+        z: INTRO_ANIMATION.CAMERA_END_POSITION.z,
+        duration: INTRO_ANIMATION.CAMERA_DURATION,
+        ease: "power2.inOut",
+      },
+      0,
+    )
+    .to(
+      camera.activeCamera.value.rotation,
+      {
+        x: INTRO_ANIMATION.CAMERA_END_ROTATION.x,
+        y: INTRO_ANIMATION.CAMERA_END_ROTATION.y,
+        z: INTRO_ANIMATION.CAMERA_END_ROTATION.z,
+        duration: INTRO_ANIMATION.CAMERA_DURATION,
+        ease: "power2.inOut",
+      },
+      0,
+    )
+    .to(
+      model.rotation,
+      {
+        y: Math.PI * 2,
+        duration: INTRO_ANIMATION.MODEL_SPIN_DURATION,
+        ease: "power2.inOut",
+      },
+      0,
+    )
+    .to(
+      lidMesh.rotation,
+      {
+        x: INTRO_ANIMATION.LID_OPENED_ROTATION,
+        duration: INTRO_ANIMATION.LID_OPEN_DURATION,
+        ease: "power2.out",
+      },
+      INTRO_ANIMATION.MODEL_SPIN_DURATION - INTRO_ANIMATION.LID_OPEN_OVERLAP,
+    )
+    .to(
+      topScreenMesh.rotation,
+      {
+        x: INTRO_ANIMATION.LID_OPENED_ROTATION,
+        duration: INTRO_ANIMATION.LID_OPEN_DURATION,
+        ease: "power2.out",
+      },
+      "<",
+    );
 };
 
 watch(
@@ -200,6 +197,131 @@ watch(
 
 const { onRender } = useLoop();
 
+const HINT_SPRITE_SCALE = 2;
+const HINT_SPRITE_DPR = 4;
+
+const makeHintSprite = (text: string): THREE.Sprite => {
+  const canvas = document.createElement("canvas");
+  canvas.width = 256 * HINT_SPRITE_DPR;
+  canvas.height = 64 * HINT_SPRITE_DPR;
+
+  const ctx = canvas.getContext("2d")!;
+
+  ctx.scale(HINT_SPRITE_DPR, HINT_SPRITE_DPR);
+  ctx.font = "32px monospace";
+  ctx.fillStyle = "#666666";
+
+  const padding = 12;
+  const textWidth = ctx.measureText(text).width + padding * 2;
+  ctx.roundRect((256 - textWidth) / 2, 12, textWidth, 40, 6);
+  ctx.fill();
+  ctx.fillStyle = "#000000";
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+  ctx.fillText(text, 128, 32);
+
+  const texture = new THREE.CanvasTexture(canvas);
+  const material = new THREE.SpriteMaterial({
+    map: texture,
+    transparent: true,
+    depthTest: false,
+  });
+  const sprite = new THREE.Sprite(material);
+  sprite.scale.set(HINT_SPRITE_SCALE, HINT_SPRITE_SCALE * 0.25, 1);
+
+  return sprite;
+};
+
+const HINTS: Record<string, { label: string; offset: THREE.Vector3 }> = {
+  [X_BUTTON]: {
+    label: mapNDSToKey("X"),
+    offset: new THREE.Vector3(-0.3, 1.1, 0.0),
+  },
+  [A_BUTTON]: {
+    label: mapNDSToKey("A"),
+    offset: new THREE.Vector3(-0.4, 1.2, 0.0),
+  },
+  [Y_BUTTON]: {
+    label: mapNDSToKey("Y"),
+    offset: new THREE.Vector3(-0.3, 1.2, 0.0),
+  },
+  [B_BUTTON]: {
+    label: mapNDSToKey("B"),
+    offset: new THREE.Vector3(-0.4, 1.3, 0.0),
+  },
+  [SELECT_BUTTON]: {
+    label: mapNDSToKey("SELECT"),
+    offset: new THREE.Vector3(-0.7, 0.05, 0.0),
+  },
+  [START_BUTTON]: {
+    label: mapNDSToKey("START"),
+    offset: new THREE.Vector3(-0.75, 0.15, 0.0),
+  },
+  [CROSS_BUTTON]: {
+    label: "Arrows",
+    offset: new THREE.Vector3(0.75, 2.3, 0.0),
+  },
+};
+
+const helpSprites = new THREE.Group();
+helpSprites.renderOrder = 999;
+
+const buildHelpSprites = () => {
+  helpSprites.clear();
+  for (const [meshName, { label, offset }] of Object.entries(HINTS)) {
+    const mesh = meshes.get(meshName);
+    if (!mesh) continue;
+
+    const sprite = makeHintSprite(label);
+    const worldPos = new THREE.Vector3();
+    mesh.getWorldPosition(worldPos);
+    sprite.position.copy(worldPos.add(offset));
+
+    helpSprites.add(sprite);
+  }
+};
+
+watch(
+  () => app.hintsVisible,
+  (show) => {
+    if (show) {
+      buildHelpSprites();
+      helpSprites.visible = true;
+      for (const child of helpSprites.children) {
+        const sprite = child as THREE.Sprite;
+        gsap.fromTo(
+          sprite.material,
+          { opacity: 0 },
+          { opacity: 1, duration: 0.2, ease: "power1.out" },
+        );
+      }
+    } else {
+      for (const child of helpSprites.children) {
+        const sprite = child as THREE.Sprite;
+        gsap.to(sprite.material, {
+          opacity: 0,
+          duration: 0.2,
+          ease: "power1.in",
+          onComplete: () => {
+            helpSprites.visible = false;
+          },
+        });
+      }
+    }
+  },
+);
+
+helpSprites.visible = app.hintsVisible;
+watch(
+  scene,
+  (s) => {
+    if (!s) return;
+    s.add(helpSprites);
+    if (app.hintsVisible) buildHelpSprites();
+  },
+  { immediate: true },
+);
+
 const physicalButtonsDown = new Set<string>();
 let mousePressedButton: string | null = null;
 
diff --git a/app/pages/index.vue b/app/pages/index.vue
index b059305..66ff1eb 100644
--- a/app/pages/index.vue
+++ b/app/pages/index.vue
@@ -1,14 +1,12 @@
 <script setup lang="ts">
-import type { Screen as NDSScreen } from "#components";
-
-type ScreenInstance = InstanceType<typeof NDSScreen>;
+import gsap from "gsap";
 
 const { isReady } = useAssets();
 
 const app = useAppStore();
 
-const topScreen = useTemplateRef<ScreenInstance>("topScreen");
-const bottomScreen = useTemplateRef<ScreenInstance>("bottomScreen");
+const topScreen = useTemplateRef("topScreen");
+const bottomScreen = useTemplateRef("bottomScreen");
 
 const topScreenCanvas = computed(() => topScreen.value?.canvas ?? null);
 const bottomScreenCanvas = computed(() => bottomScreen.value?.canvas ?? null);
@@ -27,27 +25,120 @@ const toggleFullscreen = () => {
   }
 };
 
-onMounted(() => {
+const helpButton = useTemplateRef("helpButton");
+let helpAnimation: gsap.core.Timeline | null = null;
+
+const showHelpLabels = async (yoyo = false) => {
+  if (!app.hintsAllowed) return;
+
+  helpAnimation?.kill();
+  app.hintsVisible = true;
+
+  await nextTick();
+
+  helpAnimation = gsap
+    .timeline({
+      onComplete: () => {
+        helpAnimation = null;
+      },
+    })
+    .fromTo(
+      helpButton.value,
+      { color: "#666666", opacity: 0.5 },
+      { color: "#ffffff", opacity: 1, duration: 0.2, ease: "power1.out" },
+    )
+    .to(helpButton.value, {
+      color: "#666666",
+      opacity: 0.5,
+      duration: 0.2,
+      ease: "power1.in",
+      delay: 3,
+    })
+    .call(() => {
+      app.hintsVisible = false;
+    });
+
+  if (yoyo) {
+    helpAnimation.to(helpButton.value, {
+      color: "#ffffff",
+      opacity: 1,
+      duration: 0.3,
+      repeat: 5,
+      yoyo: true,
+      delay: 0.3,
+    });
+  }
+};
+
+const hideHelpLabels = () => {
+  if (!app.hintsVisible) return;
+
+  helpAnimation?.kill();
+  helpAnimation = null;
+
+  app.hintsVisible = false;
+
+  gsap.to(helpButton.value, {
+    color: "#666666",
+    opacity: 0.5,
+    duration: 0.2,
+    ease: "power1.in",
+  });
+};
+
+watch(
+  () => app.hintsAllowed,
+  (allowed) => {
+    if (!allowed) hideHelpLabels();
+  },
+);
+
+onMounted(async () => {
   if (isIOS()) {
     showFullscreenBtn.value = false;
-    return;
   }
 
-  if (!isTouchDevice()) return;
+  if (isTouchDevice()) {
+    const landscape = window.matchMedia("(orientation: landscape)");
 
-  const landscape = window.matchMedia("(orientation: landscape)");
+    const onOrientationChange = (e: MediaQueryListEvent | MediaQueryList) => {
+      if (e.matches && !document.fullscreenElement) {
+        document.documentElement.requestFullscreen().catch(() => {});
+      }
+    };
 
-  const onOrientationChange = (e: MediaQueryListEvent | MediaQueryList) => {
-    if (e.matches && !document.fullscreenElement) {
-      document.documentElement.requestFullscreen().catch(() => {});
+    landscape.addEventListener("change", onOrientationChange);
+
+    onUnmounted(() => {
+      landscape.removeEventListener("change", onOrientationChange);
+    });
+  }
+
+  const scaleX = (window.innerWidth - 40) / 235;
+  const scaleY = (window.innerHeight - 40) / 431;
+  const scale = Math.min(scaleX, scaleY);
+
+  if (app.settings.renderingMode === "2d" && scale < 1) return;
+
+  if (!app.booted) {
+    watch(
+      () => app.hintsAllowed,
+      async (allowed) => {
+        if (allowed) await showHelpLabels(true);
+      },
+      { once: true },
+    );
+  }
+});
+
+useKeyDown(async ({ key, repeated }) => {
+  if (!repeated && key.toLocaleLowerCase() === "h") {
+    if (app.hintsVisible) {
+      hideHelpLabels();
+    } else {
+      await showHelpLabels();
     }
-  };
-
-  landscape.addEventListener("change", onOrientationChange);
-
-  onUnmounted(() => {
-    landscape.removeEventListener("change", onOrientationChange);
-  });
+  }
 });
 </script>
 
@@ -105,6 +196,15 @@ onMounted(() => {
       </template>
     </NDS2D>
 
+    <button
+      v-if="app.hintsAllowed"
+      ref="helpButton"
+      class="help-btn"
+      @click="app.hintsVisible ? hideHelpLabels() : showHelpLabels()"
+    >
+      ?
+    </button>
+
     <button
       v-if="showFullscreenBtn"
       class="fullscreen-btn"
@@ -125,6 +225,28 @@ onMounted(() => {
 </template>
 
 <style scoped>
+.help-btn {
+  position: fixed;
+  bottom: 16px;
+  left: 16px;
+  width: 30px;
+  height: 30px;
+  border: none;
+  border-radius: 50%;
+  background: rgba(255, 255, 255, 0.1);
+  color: #666;
+  font-size: 18px;
+  cursor: pointer;
+  opacity: 0.5;
+  transition: opacity 0.2s;
+  user-select: none;
+  z-index: 100;
+}
+
+.help-btn:hover {
+  opacity: 1;
+}
+
 .fullscreen-btn {
   position: fixed;
   bottom: 16px;
diff --git a/app/stores/app.ts b/app/stores/app.ts
index fe41f5e..72d121a 100644
--- a/app/stores/app.ts
+++ b/app/stores/app.ts
@@ -51,6 +51,8 @@ export const useAppStore = defineStore("app", {
       screen: "home" as AppScreen,
       visitedGallery: false,
       camera: null as THREE.Camera | null,
+      hintsVisible: false,
+      hintsAllowed: false,
     };
   },
 
@@ -86,6 +88,24 @@ export const useAppStore = defineStore("app", {
       }
     },
 
+    allowHints() {
+      this.hintsAllowed = true;
+    },
+
+    disallowHints() {
+      this.hintsAllowed = false;
+      this.hintsVisible = false;
+    },
+
+    showHints() {
+      if (!this.hintsAllowed) return;
+      this.hintsVisible = true;
+    },
+
+    hideHints() {
+      this.hintsVisible = false;
+    },
+
     setCamera(camera: THREE.Camera) {
       this.camera = camera;
     },
diff --git a/app/stores/gallery.ts b/app/stores/gallery.ts
index 7e0ba85..46cc120 100644
--- a/app/stores/gallery.ts
+++ b/app/stores/gallery.ts
@@ -35,6 +35,7 @@ export const useGalleryStore = defineStore("gallery", {
       this.isOutro = false;
 
       const app = useAppStore();
+      app.disallowHints();
 
       // Intro: Fade starts first (at 0), camera starts after with overlap
       const cameraDelay =
@@ -157,6 +158,7 @@ export const useGalleryStore = defineStore("gallery", {
       setTimeout(() => {
         this.isOutro = false;
         app.navigateTo("home");
+        app.allowHints();
       }, ANIMATION.NAVIGATE_DELAY);
     },
   },
diff --git a/app/stores/intro.ts b/app/stores/intro.ts
index 7d2e093..8ead7a1 100644
--- a/app/stores/intro.ts
+++ b/app/stores/intro.ts
@@ -47,7 +47,11 @@ export const useIntroStore = defineStore("intro", {
             ease: "steps(" + (totalFrames - 1) + ")",
           },
           4.1,
-        );
+        )
+        .call(() => {
+          const app = useAppStore();
+          app.allowHints();
+        });
     },
 
     animateOutro() {