From af001f1d97224e373e11c51f136769f4782c049f Mon Sep 17 00:00:00 2001
From: Pihkaal <hello@pihkaal.me>
Date: Thu, 19 Feb 2026 19:30:33 +0100
Subject: [PATCH] feat(2d-nds): help labels

---
 app/components/NDS2D.vue | 165 ++++++++++++++++++++++++++++++++++++++-
 app/utils/input.ts       |  36 +++++++++
 2 files changed, 200 insertions(+), 1 deletion(-)

diff --git a/app/components/NDS2D.vue b/app/components/NDS2D.vue
index 473f963..e9b5a80 100644
--- a/app/components/NDS2D.vue
+++ b/app/components/NDS2D.vue
@@ -1,5 +1,9 @@
 <script setup lang="ts">
+import gsap from "gsap";
+
 const ndsScale = ref(1);
+const showHelp = ref(false);
+const helpTimeline = ref<gsap.core.Timeline | null>(null);
 
 const updateScale = () => {
   const scaleX = (window.innerWidth - 40) / 235;
@@ -7,9 +11,67 @@ const updateScale = () => {
   ndsScale.value = Math.min(scaleX, scaleY);
 };
 
-onMounted(() => {
+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 () => {
   updateScale();
   window.addEventListener("resize", updateScale);
+
+  if (ndsScale.value >= 1) {
+    await animateHelpLabels(true);
+  }
+});
+
+useKeyDown(async ({ key }) => {
+  if (key.toLocaleLowerCase() === "h") {
+    await animateHelpLabels();
+  }
 });
 
 onUnmounted(() => {
@@ -59,8 +121,24 @@ 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 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>
+          <div class="nds2d-hint nds2d-hint-b">{{ mapNDSToKey("B") }}</div>
+          <div class="nds2d-hint nds2d-hint-y">{{ mapNDSToKey("Y") }}</div>
+          <div class="nds2d-hint nds2d-hint-start">
+            {{ mapNDSToKey("START") }}
+          </div>
+          <div class="nds2d-hint nds2d-hint-select">
+            {{ mapNDSToKey("SELECT") }}
+          </div>
+        </div>
       </div>
     </div>
+
+    <button class="nds2d-help-btn" @click="animateHelpLabels()">?</button>
   </div>
 </template>
 
@@ -460,4 +538,89 @@ onUnmounted(() => {
   left: 15px;
   top: 0px;
 }
+
+.nds2d-hints-container {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  z-index: 10;
+}
+
+.nds2d-hint {
+  position: absolute;
+  font-size: 7px;
+  color: #fff;
+  background: rgba(0, 0, 0, 0.7);
+  padding: 1px 3px;
+  border-radius: 2px;
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+.nds2d-hint-dpad {
+  left: 47px;
+  top: 46px;
+  transform: translateX(-50%);
+}
+
+.nds2d-hint-x,
+.nds2d-hint-a,
+.nds2d-hint-b,
+.nds2d-hint-y {
+  width: 15px;
+  text-align: center;
+}
+
+.nds2d-hint-x {
+  right: 38px;
+  top: 32px;
+}
+
+.nds2d-hint-a {
+  right: 15px;
+  top: 56px;
+}
+
+.nds2d-hint-b {
+  right: 38px;
+  top: 79px;
+}
+
+.nds2d-hint-y {
+  right: 62px;
+  top: 56px;
+}
+
+.nds2d-hint-start {
+  left: 330px;
+  bottom: 53px;
+  transform: translateX(-100%);
+}
+
+.nds2d-hint-select {
+  left: 330px;
+  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/utils/input.ts b/app/utils/input.ts
index 65e96bd..31b8cee 100644
--- a/app/utils/input.ts
+++ b/app/utils/input.ts
@@ -15,6 +15,42 @@ export const mapCodeToNDS = (code: string): string | null => {
   return CODE_TO_NDS_BUTTON[code] ?? null;
 };
 
+const NDS_BUTTON_TO_CODE = Object.fromEntries(
+  Object.entries(CODE_TO_NDS_BUTTON).map(([code, nds]) => [nds, code]),
+);
+
+const LAYOUT_OVERRIDES: Record<string, Record<string, string>> = {
+  // AZERTY: fr
+  fr: { KeyQ: "A", KeyA: "Q", KeyW: "Z", KeyZ: "W", KeyM: ",", Semicolon: "M" },
+  // QWERTZ: de, cs, hu, sk, sl, hr, bs, sr, pl
+  de: { KeyY: "Z", KeyZ: "Y" },
+  cs: { KeyY: "Z", KeyZ: "Y" },
+  hu: { KeyY: "Z", KeyZ: "Y" },
+  sk: { KeyY: "Z", KeyZ: "Y" },
+  sl: { KeyY: "Z", KeyZ: "Y" },
+  hr: { KeyY: "Z", KeyZ: "Y" },
+  bs: { KeyY: "Z", KeyZ: "Y" },
+  sr: { KeyY: "Z", KeyZ: "Y" },
+  pl: { KeyY: "Z", KeyZ: "Y" },
+};
+
+const getLayoutOverrides = (): Record<string, string> => {
+  if (!import.meta.client) return {};
+  const lang = navigator.language.split("-")[0]!;
+  return LAYOUT_OVERRIDES[lang] ?? {};
+};
+
+export const mapNDSToKey = (nds: string): string => {
+  const code = NDS_BUTTON_TO_CODE[nds];
+  if (!code) return nds;
+
+  const overrides = getLayoutOverrides();
+  if (overrides[code]) return overrides[code];
+
+  if (code.startsWith("Key")) return code.slice(3);
+  return code;
+};
+
 export const useMouseUp = (callback: () => void) => {
   onMounted(() => {
     document.addEventListener("mouseup", callback);