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/adocs/mockups/kit/(otra carpeta funciona: pasa--mockupsa 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 copiaassets/godot/project.jsenkit/y complétalo (fuentes, glifos clave); las páginas de Godot lo cargan desde allí. project.csses 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
.gdignorevacío endocs/mockups/) y añadedocs/mockups/*/values.draft.jsonydocs/mockups/*/shots/a.gitignore. - Sirve la raíz del proyecto:
python docs/mockups/kit/serve.py(solo stdlib), luego abrehttp://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), UnityUnityTheme(.uss, ScriptableObject.asset), UnrealUnrealTheme(valores predeterminados de clase C++ desde el encabezado yDefault*.ini, DataTable exportado a JSON/CSV). Consultareferences/engines.md; cada uno tiene una página de ejemplo funcional enassets/<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
stagedel 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 yshotTime),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 valoressections 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 des.t(animaciones en bucle cont % 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
alo 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) escribeshots/<variant>_<state>.pngy creasheet.png. Usa elvalues.jsonguardado para su variante (--defaultspara 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.pyel 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 comovalues.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.tresy en los valores predeterminados de[Export]/@exportdel 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.--writeaplica. - Unity:
python docs/mockups/kit/apply_uss.py <feature>hace lo mismo para propiedades personalizadas de USS (gruposuss:). 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 deConfig/Default<Config>.inipara una clase Config (--target headerreescribe 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.--writeaplica. 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.pngyvalues.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.