Communitygithub.com

ui-preview

En un proyecto de juego, crea una vista previa HTML ajustable de un elemento de HUD, menú, mensaje, transición o efecto de pantalla antes de implementarlo en el motor, y convierte los valores ajustados en la especificación de construcción.

¿Qué es ui-preview?

Esta habilidad está diseñada para equipos de desarrollo de videojuegos que necesitan diseñar, prototipar y refinar elementos de interfaz de usuario (UI) y efectos visuales antes de codificarlos en el motor del juego (Godot, Unity o Unreal). El proceso garantiza que ningún cambio visual se implemente hasta que el diseñador o desarrollador haya ajustado una vista previa HTML interactiva y haya presionado 'Guardar'. La vista previa se renderiza en la resolución real del juego sobre una captura de pantalla auténtica, e incluye un panel de ajuste con controles deslizantes, selectores de color, variantes y estados. El valor guardado (`values.json`) se convierte en la especificación vinculante: cada número se asigna a una propiedad expuesta en el editor o a una entrada de tema, eliminando los 'números mágicos' en el código. La habilidad también genera una hoja de revisión con todas las variantes y estados, y proporciona scripts para aplicar los valores aprobados directamente en Godot, Unity o Unreal. Su utilidad principal es agilizar la iteración de diseño de UI, permitiendo que los cambios sean evaluados visualmente y ajustados con precisión antes de tocar el motor del juego.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Vista previa de UI

Nada que cambie el aspecto de la UI del juego se construye hasta que la persona haya ajustado una vista previa HTML y haya presionado Guardar. El values.json guardado es la especificación: cada número en él se convierte en una propiedad expuesta en el editor o una entrada de tema, nunca un número mágico en el código. Un cambio que nadie puede ver no necesita vista previa.

Orden de trabajo: qué previsualizar → una captura de pantalla de ese lugar → la página de vista previa → la hoja de revisión → ellos ajustan y presionan Guardar → construir desde values.json → hoja de construcción vs. vista previa.

1. Configuración (una vez por proyecto)

  • Copia assets/kit/ a docs/mockups/kit/ (otra carpeta funciona: pasa --mockups a los scripts). Los archivos específicos del motor se pueden omitir cuando no se usen: godot_theme.js + apply_godot.py (Godot), unity_theme.js + apply_uss.py (Unity), unreal_theme.js + apply_unreal.py (Unreal). Godot: también copia assets/godot/project.js en kit/ y complétalo (fuentes, glifos clave); las páginas de Godot lo cargan desde allí.
  • project.css es el único archivo del kit que se edita: las fuentes del juego (@font-face) y la paleta del panel, incluyendo --display. kit.js carga cada fuente declarada antes de dibujar.
  • Mantén las vistas previas fuera de la importación del motor (Godot: un .gdignore vacío en docs/mockups/) y añade docs/mockups/*/values.draft.json y docs/mockups/*/shots/ a .gitignore.
  • Sirve la raíz del proyecto: python docs/mockups/kit/serve.py (solo stdlib), luego abre http://127.0.0.1:8765/docs/mockups/<feature>/. Las páginas cargan el arte del juego por ruta relativa y guardan su ajuste en disco (§5).
  • Leer los estilos propios del proyecto en el panel: Godot GodotTheme (tema .tres), Unity UnityTheme (.uss, ScriptableObject .asset), Unreal UnrealTheme (valores predeterminados de clase C++ desde el encabezado y Default*.ini, DataTable exportado a JSON/CSV). Consulta references/engines.md; cada uno tiene una página de ejemplo funcional en assets/<engine>/.

2. Pregunta, luego obtén el fondo real

  • Pregunta qué pantalla, elemento o efecto, y en qué situación, a menos que ya esté claro.
  • Captura de pantalla de ese lugar en el tamaño de la ventana gráfica del juego (la configuración de resolución del proyecto; también el stage del manifiesto) con la UI oculta, más una con la UI actual mostrada como línea base. Usa un pequeño script que ejecute el motor (plantilla Godot: assets/godot/game_shots.gd; otros: references/engines.md) y mantenlo junto a la vista previa para la verificación de construcción.
  • Pídele a la persona una captura de pantalla solo cuando no se pueda llegar a ese lugar con un script. Para algo nuevo sin nada que capturar aún, o cuando el motor no se pueda ejecutar aquí, usa un fondo simple o simulado y dilo en el título del estado.

3. Escribe la página

Copia assets/template/ (o assets/<engine>/) a docs/mockups/<feature>/. El formato de página, las especificaciones del panel, Kit.spec y los parámetros de URL están en references/kit.md.

  • manifest.json: título, stage ([ancho, alto]), states (uno por situación que el jugador pueda ver: vacío, lleno, enfocado, deshabilitado, texto más largo, mitad de animación; cada uno con un título y shotTime), variants (2 a 4 cuando hay una elección real, cada uno con un nombre y una nota), recommend (variante y por qué, en una o dos líneas).
  • index.html: Kit.start({ feature, images, groups, variants, draw }). Dale a un grupo de más de aproximadamente seis valores sections para que el panel los pliegue. Cada grupo es el lugar donde vivirán los valores en el motor (una clase de script, un tipo de tema, un shader), cada clave el nombre de propiedad que usará la construcción, en las unidades del motor. draw(ctx, values, s) debe ser una función pura de s.t (animaciones en bucle con t % length).
  • El aspecto propio del juego, no una aproximación: sus fuentes y tamaños, colores del tema (un color nuevo es una propuesta: di a qué paleta se une), arte real por ruta relativa, texto y números reales, y mensajes que muestren las teclas realmente vinculadas.
  • Pixel art: píxeles enteros, sin suavizado (el valor predeterminado del kit).
  • El movimiento se ejecuta con su duración real y su easing. Cualquier cosa que se sacuda, desvíe, parpadee o titile obtiene conmutadores de Reducir Movimiento / Reducir Parpadeo en un grupo preview: true, mostrando en qué se convierten esos ajustes.
  • Al ajustar algo que existe, la variante a lo redibuja exactamente como es hoy. Compáralo con la captura de pantalla de línea base hasta que coincidan, o cada otra variante se compara con una línea base incorrecta.
  • Algo que varias vistas previas dibujan va en un archivo compartido en el kit, no copiado por página.

4. La hoja de revisión

  • python docs/mockups/kit/shots.py <feature> (necesita Chrome, Edge o Chromium, y Pillow ≥ 10.1) escribe shots/<variant>_<state>.png y crea sheet.png. Usa el values.json guardado para su variante (--defaults para los valores predeterminados de la página) y sale con código distinto de cero si una página falla, con el error dibujado en esa captura.
  • Mira la hoja antes de mostrarla; recorta lo que se está decidiendo a 2×: texto recortado o superpuesto, la fuente incorrecta, cualquier cosa fuera del escenario, una animación congelada en un momento aburrido (mueve su shotTime).
  • Envía la hoja, la URL en vivo y las decisiones a tomar, con tu recomendación.

5. Leer el ajuste

  • Mientras ajustan, cada cambio se escribe en <feature>/values.draft.json. Léelo cada vez que pregunten qué piensas; nunca construyas a partir de él.
  • Guardar (o Ctrl/Cmd+S) escribe <feature>/values.json, la especificación aprobada, y la página se abre sobre ella: las filas que difieren se marcan, ↺ devuelve un valor, Restablecer devuelve todos. Los valores solo de vista previa nunca se marcan ni guardan.
  • Sin serve.py el ajuste vive solo en el navegador: Guardar copia el JSON (y lo mantiene como valores predeterminados de ese navegador), ellos lo pegan en el chat, y tú lo guardas como values.json.
  • Formato: {"feature", "variant", "values": {Grupo: {Clave: valor}}}; los grupos solo de vista previa se omiten.

6. Construir desde la especificación

  • Godot: python docs/mockups/kit/apply_godot.py <feature> lista lo que la especificación cambia en el tema .tres y en los valores predeterminados de [Export] / @export del script que nombra cada grupo, en los valores predeterminados uniformes de un grupo <name>.gdshader, claves sin exportación aún, y escenas que anulan esas propiedades. --write aplica.
  • Unity: python docs/mockups/kit/apply_uss.py <feature> hace lo mismo para propiedades personalizadas de USS (grupos uss:). Los valores de ScriptableObject se aplican manualmente.
  • Unreal: python docs/mockups/kit/apply_unreal.py <feature> lista lo que la especificación cambia en la clase C++ de cada grupo: anulaciones de Config/Default<Config>.ini para una clase Config (--target header reescribe el valor predeterminado de la declaración en su lugar), claves sin UPROPERTY aún (con una declaración para pegar), y valores predeterminados para establecer manualmente. --write aplica. Los valores de DataTable se aplican reimportando la exportación editada.
  • Construye lo que aún no existe: colores, fuentes y paneles en el sistema de temas o estilos del motor; tamaños, desplazamientos, duraciones y fortalezas como propiedades expuestas en el editor agrupadas como el JSON, con los valores aprobados como valores predeterminados.
  • Verifica en el juego en ejecución: captura de pantalla de cada estado que tiene la vista previa y crea <feature>/build_vs_preview.png, captura del juego junto a la captura de la vista previa. Corrige lo que difiere. Di lo que no se verificó; el antialiasing de texto del navegador y del motor difiere, así que juzga posición y tamaño, no píxeles de borde.
  • Un cambio posterior a un aspecto aprobado es una nueva ronda: vista previa, hoja, Guardar, construir.

Reglas

  • Las vistas previas permanecen en el repositorio: registran por qué la UI se ve como se ve. Confirma sheet.png y values.json; shots/ y borradores se regeneran.
  • No hay construcción antes de que exista values.json; nunca construyas a partir del borrador.
  • Si al kit le falta algo que una vista previa necesita, agrégalo al kit, no a una página.

Skills relacionados