Block tip hint bar

blocks/control.js

@@ -441,6 +441,7 @@ export function defineControlBlocks() {
       this.setPreviousStatement(true);
       this.setNextStatement(true);
       this.setInputsInline(true);
+      this.setTooltip(getTooltip('if_clause'));
 
       this._stashedCondState = null;
 

index.html

@@ -627,6 +627,16 @@ <h1 class="sr-only">FlockXR</h1>
                         >Inspector</a
                       >
                     </li>
+                    <li role="none">
+                      <a
+                        href="#"
+                        id="block-hints-menu-item"
+                        data-i18n="hide_block_hints"
+                        role="menuitem"
+                        tabindex="-1"
+                        >Hide block hints</a
+                      >
+                    </li>
                   </ul>
                 </li>
                 <!-- About menu item -->
@@ -1268,6 +1278,9 @@ <h2 id="modal-title" data-i18n="about_heading">About Flock XR</h2>
               Drag and drop code blocks to create your program. Use arrow keys and Enter to navigate
               and interact with blocks.
             </div>
+            <div id="blockHint" class="block-hint" hidden>
+              <p id="blockHintText" class="block-hint__text" role="status"></p>
+            </div>
             <div id="blocklyZoomControls" role="toolbar" aria-label="Workspace controls">
               <button
                 class="bigbutton"

locale/de.js

@@ -1050,6 +1050,9 @@ export default {
   project_save_ui: 'Speichern',
   tools_submenu_ui: 'Werkzeuge',
   inspector_tool_ui: 'Inspektor',
+  show_block_hints_ui: 'Blockhinweise anzeigen',
+  hide_block_hints_ui: 'Blockhinweise ausblenden',
+  block_hints_menu_location_ui: 'Klicken Sie auf Menü > Werkzeuge',
   language_submenu_ui: 'Sprache',
   about_submenu_ui: 'Über',
   hub_submenu_ui: 'Hub',

locale/en.js

@@ -482,6 +482,8 @@ export default {
   export_mesh_tooltip: 'Export an object as STL, OBJ, or GLB.\nKeyword: export',
 
   // Tooltip translations - Control blocks
+  if_clause_tooltip:
+    'Run the attached blocks if the condition is true. Switch the dropdown to "else if" or "else", and connect another if block below to build if / else if / else chains.',
   wait_tooltip: 'Wait for a specified time in milliseconds.\nKeyword: milli',
   wait_seconds_tooltip: 'Wait for a specified time in seconds.\nKeyword: wait',
   wait_until_tooltip: 'Wait until the condition is true.\nKeyword:until',
@@ -501,7 +503,7 @@ export default {
 
   // Tooltip translations - Events blocks
   start_tooltip:
-    'Run the blocks inside whenthe project starts. You can have multiple start blocks. \nKeyword: start',
+    'Run the blocks inside when the project starts. You can have multiple start blocks. \nKeyword: start',
   forever_tooltip:
     'Run the blocks inside every frame or when the previous iteration finishes. \nKeyword: forever',
   when_clicked_tooltip: 'Run the blocks inside when the object trigger occurs.\nKeyword: click',
@@ -545,9 +547,9 @@ export default {
     'Add a physics shape to the object. Options are object or capsule.\nKeyword:physics',
   apply_force_tooltip: 'Apply a force to an object in XYZ directions.\nKeyword: force',
   jump_tooltip:
-    'Make a character jump to a height (in blocks). Keeps your current running speed, so you leap forwards with momentum like in platform games. Needs physics.\nKeyword: jump hop leap',
+    'Make a character jump to a height (in blocks). Keeps your current running speed. Needs physics.\nKeyword: jump hop leap',
   set_speed_tooltip:
-    'Keep an object moving at a set speed in a direction. It moves just like a player does with "move" — riding up slopes, stepping over small ledges and stopping at walls, staying upright — but relative to the object or the world instead of the camera. It holds that speed until you change it. Pick a direction relative to the object (forward, sideways, up) or a world axis (x, y, z); use "look at" to aim, then drive forward. Choose "all" and 0 to stop.\nKeyword: speed',
+    'Keep an object moving at a steady speed, like "move" but continuous — handles slopes and collisions, relative to the object or world. Choose a direction (forward, sideways, up) or a world axis (x, y, z); use "all" and 0 to stop.\nKeyword: speed',
   set_bounciness_tooltip:
     'Set how bouncy an object is. 0 means no bounce, 1 means very bouncy. The object needs physics first.\nKeyword: bouncy restitution',
   show_physics_tooltip:
@@ -657,8 +659,7 @@ export default {
     'Resize an object to the given x, y, and z and controls the origin of scaling. \nKeyword: scale',
   resize_tooltip:
     'Resize an object to the given x, y, and z and controls the origin of scaling.\nKeyword: resize',
-  rotate_model_xyz_tooltip:
-    'Rotate the object by the given x, y, z values.\nKeyword: rotate\nKeyword: rotateby',
+  rotate_model_xyz_tooltip: 'Rotate the object by the given x, y, z values.\nKeyword: rotateby',
   rotate_to_tooltip: 'Rotate the object to point towards the  coordinates.\nKeyword: rotateto',
   look_at_tooltip:
     'Rotate the first object towards the position of the second object.\nKeyword: look',
@@ -1106,6 +1107,9 @@ export default {
   project_save_ui: 'Save',
   tools_submenu_ui: 'Tools',
   inspector_tool_ui: 'Inspector',
+  show_block_hints_ui: 'Show block hints',
+  hide_block_hints_ui: 'Hide block hints',
+  block_hints_menu_location_ui: 'Click Menu > Tools',
   language_submenu_ui: 'Language',
   about_submenu_ui: 'About',
   hub_submenu_ui: 'Hub',

locale/es.js

@@ -480,6 +480,8 @@ export default {
   export_mesh_tooltip: 'Exporta un objeto en STL, OBJ o GLB.\nPalabra clave: exporta', // human
 
   // Tooltip translations - Control blocks
+  if_clause_tooltip:
+    'Ejecuta los bloques conectados si la condición es verdadera. Cambia el menú desplegable a "sino si" o "sino", y conecta otro bloque si debajo para crear cadenas de si / sino si / sino.', // ai
   wait_tooltip: 'Espera un tiempo especificado en milisegundos.\nPalabra clave: mili', // human
   wait_seconds_tooltip: 'Espera un tiempo especificado en segundos.\nPalabra clave: espera', // human
   wait_until_tooltip: 'Espera hasta que la condición sea verdadera.\nPalabra clave: hasta', // human
@@ -546,7 +548,7 @@ export default {
     'Añade una forma física al objeto. Opciones: objeto o cápsula.\nPalabra clave: física', // human
   apply_force_tooltip: 'Aplica una fuerza a un objeto en direcciones XYZ.\nPalabra clave: fuerza', // human
   jump_tooltip:
-    'Hace que un personaje salte a una altura (en bloques). Mantiene tu velocidad de carrera actual, así que saltas hacia adelante con impulso como en los juegos de plataformas. Necesita física.\nPalabra clave: saltar brincar', // ai
+    'Hace que un personaje salte a una altura (en bloques). Mantiene tu velocidad de carrera actual. Necesita física.\nKeyword: saltar brincar', // ai
   show_physics_tooltip:
     'Mostrar u ocultar colisionadores físicos para depuración. Marque para mostrar, desmarque para ocultar.\nPalabra clave: depuración de coliionador de física', // human
 
@@ -659,7 +661,7 @@ export default {
   resize_tooltip:
     'Redimensiona un objeto a los valores x, y, y z y controla el origen del escalado.\nPalabra clave: redimensiona', // human
   rotate_model_xyz_tooltip:
-    'Rota el objeto por los valores x, y, z indicados.\nPalabra clave: rota\nKeyword: rotapor', // human
+    'Rota el objeto por los valores x, y, z indicados.\nPalabra clave: rota\nPalabra clave: rotapor', // human
   rotate_to_tooltip: 'Rota el objeto para q apunte hacia las coordenadas.\nPalabra clave: rotaa', // human
   look_at_tooltip: 'Rota el primer objeto hacia la posición de la segunda.\nPalabra clave: mira', // human
   move_forward_tooltip:
@@ -1097,6 +1099,9 @@ export default {
   project_save_ui: 'Guardar', // human
   tools_submenu_ui: 'Herramientas', // ai
   inspector_tool_ui: 'Inspector', // ai
+  show_block_hints_ui: 'Mostrar sugerencias de bloques',
+  hide_block_hints_ui: 'Ocultar sugerencias de bloques',
+  block_hints_menu_location_ui: 'Haz clic en Menú > Herramientas',
   language_submenu_ui: 'Idioma', // human
   about_submenu_ui: 'Sobre nosotros', // human
   hub_submenu_ui: 'Centro', // human

locale/fr.js

@@ -1040,6 +1040,9 @@ export default {
   project_save_ui: 'Enregistrer',
   tools_submenu_ui: 'Outils',
   inspector_tool_ui: 'Inspecteur',
+  show_block_hints_ui: 'Afficher les astuces des blocs',
+  hide_block_hints_ui: 'Masquer les astuces des blocs',
+  block_hints_menu_location_ui: 'Cliquez sur Menu > Outils',
   language_submenu_ui: 'Langue',
   about_submenu_ui: 'À propos',
   hub_submenu_ui: 'Hub',

locale/it.js

@@ -1048,6 +1048,9 @@ export default {
   project_save_ui: 'Salva',
   tools_submenu_ui: 'Strumenti',
   inspector_tool_ui: 'Ispettore',
+  show_block_hints_ui: 'Mostra suggerimenti dei blocchi',
+  hide_block_hints_ui: 'Nascondi suggerimenti dei blocchi',
+  block_hints_menu_location_ui: 'Fai clic su Menu > Strumenti',
   language_submenu_ui: 'Lingua',
   about_submenu_ui: 'Informazioni',
   hub_submenu_ui: 'Hub',

locale/pl.js

@@ -1038,6 +1038,9 @@ export default {
   project_save_ui: 'Zapisz',
   tools_submenu_ui: 'Narzędzia',
   inspector_tool_ui: 'Inspektor',
+  show_block_hints_ui: 'Pokaż podpowiedzi bloków',
+  hide_block_hints_ui: 'Ukryj podpowiedzi bloków',
+  block_hints_menu_location_ui: 'Kliknij Menu > Narzędzia',
   language_submenu_ui: 'Język',
   about_submenu_ui: 'O programie',
   hub_submenu_ui: 'Hub',

locale/pt.js

@@ -1048,6 +1048,9 @@ export default {
   project_save_ui: 'Guardar',
   tools_submenu_ui: 'Ferramentas',
   inspector_tool_ui: 'Inspetor',
+  show_block_hints_ui: 'Mostrar dicas de blocos',
+  hide_block_hints_ui: 'Ocultar dicas de blocos',
+  block_hints_menu_location_ui: 'Clique em Menu > Ferramentas',
   language_submenu_ui: 'Idioma',
   about_submenu_ui: 'Sobre',
   hub_submenu_ui: 'Hub',

locale/sv.js

@@ -1026,6 +1026,9 @@ export default {
   project_save_ui: 'Spara',
   tools_submenu_ui: 'Verktyg',
   inspector_tool_ui: 'Inspektör',
+  show_block_hints_ui: 'Visa blocktips',
+  hide_block_hints_ui: 'Dölj blocktips',
+  block_hints_menu_location_ui: 'Klicka på Meny > Verktyg',
   language_submenu_ui: 'Språk',
   about_submenu_ui: 'Om',
   hub_submenu_ui: 'Nav',

main/blockhandling.js

@@ -4,6 +4,7 @@ import { translate } from './translation.js';
 import { blockHandlerRegistry, refreshReporterAriaLabels } from '../blocks/blocks.js';
 import { announceToScreenReader } from './input.js';
 import { TOP_BLOCK_TYPES } from '../config.js';
+import { showBlockHint, clearBlockHint } from '../ui/blockHint.js';
 
 function asBlocklyBlock(candidate) {
   if (!candidate || typeof candidate !== 'object') {
@@ -323,6 +324,11 @@ export function initializeBlockHandling() {
     // Track the currently selected block.
     if (event.type === Blockly.Events.SELECTED) {
       window.currentBlock = event.newElementId ? workspace.getBlockById(event.newElementId) : null;
+      if (window.currentBlock) {
+        showBlockHint(Blockly.Tooltip.getTooltipOfObject(window.currentBlock));
+      } else {
+        clearBlockHint();
+      }
     }
 
     // Workaround for Blockly not checking for orphans on key

main/loading.js

@@ -1,4 +1,5 @@
 import { translate } from './translation.js';
+import { areBlockHintsEnabled, showBlockHintMessage } from '../ui/blockHint.js';
 
 // Function to hide loading screen
 export function hideLoadingScreen() {
@@ -18,6 +19,12 @@ export function hideLoadingScreen() {
       }, 20);
     }
 
+    const hintsLabelKey = areBlockHintsEnabled() ? 'hide_block_hints_ui' : 'show_block_hints_ui';
+    const hintsLabel = translate(hintsLabelKey);
+    showBlockHintMessage(`ℹ️ ${hintsLabel}: ${translate('block_hints_menu_location_ui')}`, {
+      boldPart: hintsLabel,
+    });
+
     // Then show main content after a brief delay
     setTimeout(() => {
       body.classList.remove('loading');

main/main.js

@@ -47,6 +47,7 @@ import {
 import { ShortcutsPanel } from '../accessibility/keyboardui.js';
 import { KeyboardDispatcher } from './keyboardDispatcher.js';
 import { ContextManager } from './context.js';
+import { areBlockHintsEnabled, setBlockHintsEnabled } from '../ui/blockHint.js';
 
 function isEmbedModeEnabled() {
   const embedParam = new URLSearchParams(window.location.search).get('embed');
@@ -729,6 +730,7 @@ function initializeApp() {
   // Add event listeners for menu buttons and controls
   const runCodeButton = document.getElementById('runCodeButton');
   const inspectorMenuItem = document.getElementById('inspector-menu-item');
+  const blockHintsMenuItem = document.getElementById('block-hints-menu-item');
   const togglePlayButton = document.getElementById('togglePlay');
   const stopCodeButton = document.getElementById('stopCodeButton');
   const fileInput = document.getElementById('fileInput');
@@ -839,6 +841,19 @@ function initializeApp() {
     }
   });
 
+  const updateBlockHintsMenuLabel = () => {
+    if (!blockHintsMenuItem) return;
+    const key = areBlockHintsEnabled() ? 'hide_block_hints' : 'show_block_hints';
+    blockHintsMenuItem.dataset.i18n = key;
+    blockHintsMenuItem.textContent = translate(`${key}_ui`);
+  };
+  updateBlockHintsMenuLabel();
+  blockHintsMenuItem?.addEventListener('click', (event) => {
+    event.preventDefault();
+    setBlockHintsEnabled(!areBlockHintsEnabled());
+    updateBlockHintsMenuLabel();
+  });
+
   if (togglePlayButton) {
     togglePlayButton.addEventListener('click', togglePlayMode);
   }

style.css

@@ -612,6 +612,33 @@ button {
   z-index: 100;
 }
 
+.block-hint {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  width: min(320px, calc(100% - 16px));
+  margin: 0;
+  padding: 6px 12px;
+  font-size: 0.9rem;
+  line-height: 1.3;
+  color: var(--color-text-primary);
+  background-color: var(--color-bg);
+  border: 1px solid var(--color-border);
+  box-shadow: 0px 0px 10px var(--color-shadow);
+  border-radius: 8px;
+  z-index: 90;
+  text-align: left;
+  pointer-events: none;
+}
+
+.block-hint[hidden] {
+  display: none;
+}
+
+.block-hint__text {
+  margin: 0;
+}
+
 #blocklyZoomControls .toolbar-divider,
 #info-panel-tabs .toolbar-divider {
   width: 1px;
@@ -992,7 +1019,7 @@ button {
   }
 
   #babylon-inspector-container,
-  #menuDropdown #tools-menu-item {
+  #menuDropdown #inspector-menu-item {
     display: none !important;
   }