Communitygithub.com

Aperçu UI

Dans un projet de jeu, créez un aperçu HTML ajustable d'un élément HUD, menu, invite, transition ou effet d'écran avant de l'implémenter dans le moteur, puis transformez les valeurs ajustées en spécification de construction.

Qu'est-ce que Aperçu UI ?

Ce skill permet aux développeurs de jeux de concevoir, prototyper et ajuster visuellement des éléments d'interface utilisateur (HUD, menus, invites, transitions, effets d'écran) directement en HTML, avant de les coder dans le moteur (Godot, Unity ou Unreal). Il génère un aperçu interactif superposé à une capture d'écran réelle du jeu, avec un panneau de réglage (curseurs, couleurs, variantes, états). Les valeurs ajustées sont sauvegardées localement sous forme de fichier `values.json`, qui sert de spécification unique. Le skill fournit également une feuille de révision de tous les états, et des scripts pour appliquer les valeurs approuvées dans Godot, Unity ou Unreal. Il est utilisé lorsqu'un membre de l'équipe demande de concevoir, maquetter, restyler ou peaufiner l'apparence ou le mouvement d'un élément UI, même pour un changement mineur.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thomas-ratz/game-ui-proof/tree/HEAD/skills/ui-preview

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait Aperçu UI ?

Rien qui change l'apparence de l'UI du jeu n'est construit tant que la personne n'a pas ajusté un aperçu HTML de celui-ci et appuyé sur Enregistrer. Le values.json sauvegardé est la spécification : chaque nombre qu'il contient devient une propriété exposée dans l'éditeur ou une entrée de thème, jamais un nombre magique dans le code. Un changement que personne ne peut voir n'a pas besoin d'aperçu.

Ordre de travail : quoi prévisualiser → une capture d'écran de cet endroit → la page d'aperçu → la feuille de révision → ils ajustent et appuient sur Enregistrer → construire à partir de values.json → feuille de comparaison construction/aperçu.

1. Configuration (une fois par projet)

  • Copier assets/kit/ vers docs/mockups/kit/ (un autre dossier fonctionne : passer --mockups aux scripts). Les fichiers spécifiques au moteur peuvent être laissés de côté lorsqu'ils ne sont pas utilisés : godot_theme.js + apply_godot.py (Godot), unity_theme.js + apply_uss.py (Unity), unreal_theme.js + apply_unreal.py (Unreal). Godot : copier aussi assets/godot/project.js dans kit/ et le remplir (polices, glyphes clés) ; les pages Godot le chargent depuis là.
  • project.css est le seul fichier du kit à modifier : les polices du jeu (@font-face) et la palette du panneau, y compris --display. kit.js charge chaque police déclarée avant de dessiner.
  • Garder les aperçus hors de l'import du moteur (Godot : un .gdignore vide dans docs/mockups/) et ajouter docs/mockups/*/values.draft.json et docs/mockups/*/shots/ dans .gitignore.
  • Servir la racine du projet : python docs/mockups/kit/serve.py (stdlib uniquement), puis ouvrir http://127.0.0.1:8765/docs/mockups/<feature>/. Les pages chargent les assets du jeu par chemin relatif et sauvegardent leur réglage sur le disque (§5).
  • Lire les styles propres du projet dans le panneau : Godot GodotTheme (thème .tres), Unity UnityTheme (.uss, ScriptableObject .asset), Unreal UnrealTheme (valeurs par défaut de la classe C++ depuis l'en-tête et Default*.ini, DataTable exportée en JSON/CSV). Voir references/engines.md ; chacun a une page d'exemple fonctionnelle dans assets/<engine>/.

2. Demander, puis obtenir le fond réel

  • Demander quel écran, élément ou effet, et dans quelle situation, sauf si c'est déjà clair.
  • Capturer cet endroit à la taille de la zone d'affichage du jeu (le paramètre de résolution du projet ; aussi le stage du manifeste) avec l'UI cachée, plus une avec l'UI actuelle affichée comme référence de base. Utiliser un petit script exécuté par le moteur (modèle Godot : assets/godot/game_shots.gd ; autres : references/engines.md) et le garder à côté de l'aperçu pour la vérification de construction.
  • Demander une capture d'écran à la personne uniquement lorsque l'endroit ne peut pas être atteint par un script. Pour quelque chose de nouveau sans rien à capturer encore, ou lorsque le moteur ne peut pas être exécuté ici, utiliser un fond uni ou simulé et le mentionner dans la légende de l'état.

3. Écrire la page

Copier assets/template/ (ou assets/<engine>/) vers docs/mockups/<feature>/. Le format de la page, les spécifications du panneau, Kit.spec et les paramètres URL sont dans references/kit.md.

  • manifest.json : titre, stage ([l, h]), states (un par situation que le joueur peut voir : vide, plein, focalisé, désactivé, texte le plus long, milieu d'animation ; chacun avec une légende et shotTime), variants (2 à 4 lorsqu'il y a un vrai choix, chacun avec un nom et une note), recommend (variante et pourquoi, en une ou deux lignes).
  • index.html : Kit.start({ feature, images, groups, variants, draw }). Donner à un groupe de plus d'environ six valeurs des sections pour que le panneau les replie. Chaque groupe est l'endroit où les valeurs vivront dans le moteur (une classe de script, un type de thème, un shader), chaque clé est le nom de propriété que la construction utilisera, dans les unités du moteur. draw(ctx, values, s) doit être une fonction pure de s.t (animer les boucles avec t % length).
  • L'apparence propre du jeu, pas une approximation : ses polices et tailles, couleurs du thème (une nouvelle couleur est une proposition : dire à quelle palette elle se joint), assets réels par chemin relatif, texte et nombres réels, et invites montrant les touches réellement liées.
  • Pixel art : pixels entiers, pas de lissage (le paramètre par défaut du kit).
  • Le mouvement s'exécute à sa durée et son easing réels. Tout ce qui tremble, dérive, clignote ou scintille reçoit des bascules Réduire le mouvement / Réduire le clignotement dans un groupe preview: true, montrant ce que ces réglages transforment.
  • Lors du réglage de quelque chose qui existe, la variante a le redessine exactement comme il est aujourd'hui. Vérifier contre la capture d'écran de référence jusqu'à ce qu'elles correspondent, sinon chaque autre variante est comparée à une référence erronée.
  • Quelque chose que plusieurs aperçus dessinent va dans un fichier partagé dans le kit, pas copié par page.

4. La feuille de révision

  • python docs/mockups/kit/shots.py <feature> (nécessite Chrome, Edge ou Chromium, et Pillow ≥ 10.1) écrit shots/<variant>_<state>.png et assemble sheet.png. Il utilise le values.json sauvegardé pour sa variante (--defaults pour les valeurs par défaut de la page) et se termine avec un code non nul si une page échoue, avec l'erreur dessinée sur cette capture.
  • Regarder la feuille avant de la montrer ; recadrer ce qui est décidé à 2× : texte coupé ou qui se chevauche, mauvaise police, quelque chose en dehors de la scène, une animation figée à un moment ennuyeux (déplacer son shotTime).
  • Envoyer la feuille, l'URL en direct et les décisions à prendre, avec votre recommandation.

5. Lire le réglage

  • Pendant qu'ils ajustent, chaque modification est écrite dans <feature>/values.draft.json. Lire chaque fois qu'ils demandent votre avis ; ne jamais construire à partir de celui-ci.
  • Enregistrer (ou Ctrl/Cmd+S) écrit <feature>/values.json, la spécification approuvée, et la page s'ouvre alors dessus : les lignes différentes sont marquées, ↺ remet une valeur en place, Réinitialiser remet toutes en place. Les valeurs d'aperçu uniquement ne sont jamais marquées ni sauvegardées.
  • Sans serve.py, le réglage ne vit que dans le navigateur : Enregistrer copie le JSON (et le conserve comme valeurs par défaut de ce navigateur), ils le collent dans le chat, et vous le sauvegardez comme values.json.
  • Format : {"feature", "variant", "values": {Groupe: {Clé: valeur}}} ; les groupes d'aperçu uniquement sont laissés de côté.

6. Construire à partir de la spécification

  • Godot : python docs/mockups/kit/apply_godot.py <feature> liste ce que la spécification change dans le thème .tres et dans les valeurs par défaut [Export] / @export du script que chaque groupe nomme, dans les valeurs par défaut uniformes d'un groupe <nom>.gdshader, les clés sans export encore, et les scènes qui remplacent ces propriétés. --write applique.
  • Unity : python docs/mockups/kit/apply_uss.py <feature> fait de même pour les propriétés personnalisées USS (groupes uss:). Les valeurs ScriptableObject sont appliquées à la main.
  • Unreal : python docs/mockups/kit/apply_unreal.py <feature> liste ce que la spécification change dans la classe C++ de chaque groupe : remplacements Config/Default<Config>.ini pour une classe Config (--target header réécrit la valeur par défaut de la déclaration à la place), les clés sans encore UPROPERTY (avec une déclaration à coller), et les valeurs par défaut à définir à la main. --write applique. Les valeurs DataTable sont appliquées en réimportant l'export modifié.
  • Construire ce qui n'existe pas encore : couleurs, polices et panneaux dans le système de thème ou de style du moteur ; tailles, décalages, durées et forces comme propriétés exposées dans l'éditeur regroupées comme le JSON, avec les valeurs approuvées comme valeurs par défaut.
  • Vérifier dans le jeu en cours : capturer chaque état que l'aperçu a et créer <feature>/build_vs_preview.png, capture du jeu à côté de la capture de l'aperçu. Corriger ce qui diffère. Dire ce qui n'a pas été vérifié ; l'anticrénelage du texte du navigateur et du moteur diffère, donc juger la position et la taille, pas les pixels de bord.
  • Une modification ultérieure d'un look approuvé est un nouveau cycle : aperçu, feuille, Enregistrer, construire.

Règles

  • Les aperçus restent dans le dépôt : ils enregistrent pourquoi l'UI a l'aspect qu'elle a. Commiter sheet.png et values.json ; shots/ et les brouillons sont régénérés.
  • Pas de construction avant que values.json n'existe ; ne jamais construire à partir du brouillon.
  • Si le kit manque de quelque chose dont un aperçu a besoin, l'ajouter au kit, pas à une seule page.

Skills associés