CONVENCIONES.md (3337B)
1 # Convenciones de los minijuegos (`mini/`) 2 3 Referencia: `buscaminas/app.c`. Cada juego es una carpeta `mini/<juego>/` con 4 `app.c` (y otros `.c` si hace falta, p. ej. datos generados) + `app_config.h`. 5 6 ## Plataforma 7 - Corre en la PicoCalc (RP2040 133 MHz, sin FPU, pila de pocos KB) y en el 8 simulador SDL (`make sim-<juego>`), con el MISMO código. 9 - Solo se usa `mini.h` (que trae `hal.h`, `gfx.h`, `form.h`, `rng.h`, `str.h`) y 10 `<string.h>`. Nada de malloc, stdio, float (enteros / punto fijo), ni SDK de la Pico. 11 - Arreglos grandes: `static`/globales, nunca locales grandes. Nada de recursión profunda. 12 - Pantalla 320x320. `hal_draw(paint, ctx)` llama a `paint` una vez por franja: 13 `paint` dibuja TODO a partir del estado y no modifica nada. 14 - En el aparato repintar la pantalla entera tarda ~100 ms; `hal_draw` solo manda 15 las franjas de 32 filas que cambiaron. Llamar a `hal_draw` solo si algo cambió 16 (`dirty`). En tiempo real, que lo que se mueve toque pocas franjas; nada de 17 animar la pantalla entera. Los tiempos del juego se miden con `hal_ms()`, nunca 18 por cuadros (el simulador es instantáneo, el aparato no). 19 - `hal_key()`: -1 nada, 0 = "redibujá" (no es tecla), `K_UP/K_DOWN/K_LEFT/K_RIGHT/ 20 K_OK (Enter)/K_BACK (Esc)/K_TAB/K_BKSP` o el carácter. **Solo eventos de tecla 21 apretada** (no hay sostenida ni soltar), como mucho uno cada 15 ms. 22 - Fuentes: `font_small` 5x7, `font_normal` 6x12, `font_bold` 6x13 (Latin-1: á é í 23 ó ú ñ ¡ ¿ andan; strings en UTF-8). `mini_big_text` escala. 24 25 ## Estructura y estilo 26 - `app_main`: `mini_start("Título", color_de_acento)`, `mini_art = ...` (adorno 27 debajo del título del menú, entre y≈56 y `mini_menu_top`=84), bucle: menú 28 principal (Form: "Jugar", opciones con `form_choice`, labels con récords) → 29 partida → fin → menú. 30 - En partida: barra de arriba 0..24 en `C_PANEL` (datos: puntos, tiempo, nivel), 31 fondo `RGB(16, 20, 30)`, ayuda de teclas en `font_small` centrada en y=311 en `C_DIM`. 32 - Esc en partida → menú "Pausa" (Seguir / Empezar de nuevo / Menú principal); la 33 pausa no cuenta para los relojes. 34 - Fin de partida: cartel centrado con doble borde (ver buscaminas), "Enter otra Esc menú". 35 - Récords/estadísticas con `mini_get/mini_set` y `mini_save()` (al terminar una 36 partida o al cambiar opciones; los de turnos pueden guardar la partida en curso 37 después de cada jugada con `mini_set_str`, así sobrevive a apagar el aparato). 38 El .SAV entero tiene 2 KB de texto: claves cortas. 39 - UI en castellano rioplatense. Comentarios en castellano, normales (no didácticos). 40 4 espacios, estilo del buscaminas. 41 42 ## Probar 43 - `make sim-<juego>` (solo el tuyo: otros juegos pueden estar a medio escribir). 44 Sin warnings con `-Wall -Wextra -Wshadow`. 45 - Capturas sin ventana: `tools/shot.sh <juego> "TECLAS" salida.png`; TECLAS es 46 `APP_KEYS`: `~` Enter, `<` Esc, `>` Tab, `^ v { }` flechas, `.` pausa 300 ms, 47 `!` salir; el resto, caracteres tal cual. Mirar las capturas. 48 - Chequeo para ARM (la Pico): 49 `arm-none-eabi-gcc -mcpu=cortex-m0plus -mthumb -std=gnu11 -O2 -Wall -Wextra -Wshadow -Wno-unused-parameter -c -I<juego> -I. -I../comun/base -I../comun/gfx -I../comun/pico <juego>/*.c -o /dev/null` 50 (compilar de a un .c si hay varios) y revisar con `arm-none-eabi-size` que la RAM estática sea razonable (< 100 KB).