Sistema de Clasificaciones

Para qué sirve este sistema

La mayoría de las clasificaciones en Unity empiezan como una lista ordenada guardada en PlayerPrefs y se convierten en un lastre en cuanto un diseñador pide «el mejor tiempo de cada jugador» o «un top 100 común a todas las plataformas». El desempate, la política de retención y la interfaz que muestra el ranking suelen improvisarse por separado, y ninguno de los tres sobrevive al día en que hay que sustituir la lista local por una clasificación online.

El sistema de Clasificaciones de Serenity trata el ranking como una responsabilidad de negocio de primer nivel, no como un añadido de interfaz. ILeaderboardService registra las entradas, las ordena con la misma semántica de empates que una consulta SQL RANK() y entrega el resultado a una vista integrada con los temas que cualquier menú puede abrir sin escribir código — y el backend de almacenamiento puede ser un archivo local, una base de datos o un servicio HTTP sin que cambie una sola línea del código del juego.

El problema en Unity

Construir una clasificación «como es debido» suele implicar resolver tres problemas independientes a la vez: cómo se ordenan y deduplican las entradas, dónde viven los datos ya clasificados y cómo la interfaz los muestra y actualiza. Los equipos que improvisan los tres acaban con reglas de ranking incrustadas en el código de interfaz, sin una lógica de desempate compartida y con un formato de guardado que solo funciona con PlayerPrefs.

El resultado aparece tarde: una tabla que resuelve los empates de forma distinta en dos menús, un «top 100» que en silencio se queda en lo que PlayerPrefs es capaz de almacenar, o una interfaz que hay que reconstruir desde cero el día en que el proyecto necesita una clasificación online en lugar de una local.

Cómo lo aborda Serenity

Serenity expone el comportamiento de clasificación a través de ILeaderboardService, con SubmitAsync, GetTopAsync, GetPlayerRankAsync, GetAroundPlayerAsync y ClearAsync. Cada tabla se describe con un LeaderboardDefinition — dirección de ordenación, retención BestPerPlayer o FullHistory y un límite MaxEntries — y el ranking corre a cargo de un LeaderboardRanker determinista con semántica de empates SQL RANK() documentada. Cada envío y cada borrado emiten LeaderboardEntrySubmittedSignal o LeaderboardClearedSignal a través del event dispatcher.

El almacenamiento es intercambiable gracias al contrato genérico de persistencia IStructuredStore, compartido con el resto de datos estructurados de Serenity: PlayerPrefs para tablas locales del dispositivo, archivos JSON legibles, una base de datos SQLite embebida, tu propio servicio HTTP o una conexión directa a Postgres, MySQL o MongoDB. LeaderboardBackendFactory no lanza excepciones jamás: un backend mal configurado registra una advertencia y recurre a PlayerPrefs en lugar de romper el juego.

Cómo encaja en Serenity

El agregado Leaderboard mantiene el ranking independiente del motor en el núcleo de Business — ILeaderboardService, LeaderboardDefinition, LeaderboardRanker y las señales viven al margen de Unity. La capa de Unity añade UnityLeaderboardSettings para configurar las tablas, UnityLeaderboardScoreBridge para conectar el sistema de Puntuación con los envíos usando el device-id o una identidad de jugador personalizada, y LeaderboardBackendFactory para resolver el backend configurado.

Sobre el núcleo se apoya UnityLeaderboardViewDefinition, una vista de primer nivel registrada en el ViewRouter: presentación Top-N o en torno a la posición del jugador, número de entradas configurable y formatos de valor que incluyen los tiempos M:SS y H:MM:SS, accesible desde cualquier opción de menú o mediante ShowLeaderboardSignal sin escribir código. El slot de tema LeaderboardTemplate viene incluido en los 8 temas de serie, de modo que la tabla se renderiza con el lenguaje visual del tema activo sin prefabs a medida.

Flujo de trabajo práctico

1. Define una tabla con LeaderboardDefinition — dirección de ordenación, retención BestPerPlayer o FullHistory y un límite MaxEntries.
2. Envía puntuaciones con ILeaderboardService.SubmitAsync, o conecta UnityLeaderboardScoreBridge para enviarlas automáticamente cada vez que el sistema de Puntuación registre un nuevo valor.
3. Consulta los resultados con GetTopAsync, GetPlayerRankAsync o GetAroundPlayerAsync para construir tu propia interfaz, o deja que UnityLeaderboardViewDefinition los muestre por ti.
4. Registra la vista en el ViewRouter y ábrela desde cualquier opción de menú o emitiendo ShowLeaderboardSignal — sin cablear nada en la escena.
5. O sáltate los pasos manuales y ejecuta Create Leaderboard: elige un preset, elige la puntuación que quieres seguir, elige dónde vivirán los datos y, si quieres, obtén una pantalla de clasificación lista para navegar.

Qué incluye

• Servicio de clasificación ILeaderboardService con SubmitAsync, GetTopAsync, GetPlayerRankAsync, GetAroundPlayerAsync y ClearAsync
• LeaderboardRanker determinista con semántica de empates SQL RANK() documentada
• LeaderboardDefinition por tabla con retención BestPerPlayer o FullHistory y límite MaxEntries
• Señales LeaderboardEntrySubmittedSignal y LeaderboardClearedSignal emitidas a través del event dispatcher
• Almacenamiento intercambiable mediante IStructuredStore — PlayerPrefs, JSON con LocalFile, SQLite embebido, HTTP o conexión directa a Postgres/MySQL/MongoDB
• UnityLeaderboardViewDefinition integrada con los temas, con presentación Top-N o en torno al jugador y formatos de tiempo M:SS/H:MM:SS
• UnityLeaderboardScoreBridge, que conecta el sistema de Puntuación con los envíos usando device-id o una identidad de jugador personalizada
• Asistente Create Leaderboard de cinco pasos con reversión completa si algo falla

Cuándo usarlo

• Juegos que necesitan una tabla de récords o de mejores tiempos sin escribir a mano el ranking, el almacenamiento y la interfaz por triplicado.
• Proyectos que quieren empezar con una clasificación local y pasar a una online más adelante sin reescribir el código del juego.
• Equipos que quieren una pantalla de clasificación conectada a un menú existente sin que un programador toque la escena.
• Bases de código que ya usan el sistema de Puntuación y quieren que los envíos sean automáticos, en coordinación con Persistencia y los Temas de Interfaz.

Sistemas relacionados

• Sistema de Puntuación Multi-Métrica Un modelo de puntuación dinámico que rastrea cualquier número de métricas nombradas a través de un único servicio, devolviendo instantáneas inmutables que las reglas de juego nunca necesitan poseer.
• Capa de Persistencia de Datos Una jerarquía de puertos que desacopla los contratos de guardado de los backends de Unity para que el almacenamiento en ficheros, PlayerPrefs y el cifrado puedan cambiar sin tocar el código del juego.
• Temas de UI Temas de UI basados en ScriptableObject que comparten visuales y feedback sonoro entre menús, modales y pantallas.
• Sistema de menús Menús declarativos, temas de UI compartidos y navegación predecible, configurados como assets en vez de cableados a mano sobre GameObjects.