Sistema de Classificacions

Per a què serveix aquest sistema

La majoria de les classificacions a Unity comencen com una llista ordenada desada a PlayerPrefs i esdevenen un llast tan bon punt un dissenyador demana «el millor temps de cada jugador» o «un top 100 comú a totes les plataformes». El desempat, la política de retenció i la interfície que mostra el rànquing solen improvisar-se per separat, i cap dels tres no sobreviu al dia en què cal substituir la llista local per una classificació en línia.

El sistema de Classificacions de Serenity tracta el rànquing com una responsabilitat de negoci de primer nivell, no com un afegit d'interfície. ILeaderboardService registra les entrades, les ordena amb la mateixa semàntica d'empats que una consulta SQL RANK() i lliura el resultat a una vista integrada amb els temes que qualsevol menú pot obrir sense escriure codi — i el backend d'emmagatzematge pot ser un fitxer local, una base de dades o un servei HTTP sense que canviï ni una sola línia del codi del joc.

El problema a Unity

Construir una classificació «com cal» sol implicar resoldre tres problemes independents alhora: com s'ordenen i es dedupliquen les entrades, on viuen les dades ja classificades i com la interfície les mostra i les actualitza. Els equips que improvisen els tres acaben amb regles de rànquing incrustades al codi d'interfície, sense una lògica de desempat compartida i amb un format de desament que només funciona amb PlayerPrefs.

El resultat apareix tard: una taula que resol els empats de manera diferent en dos menús, un «top 100» que en silenci es queda en el que PlayerPrefs és capaç d'emmagatzemar, o una interfície que cal reconstruir des de zero el dia que el projecte necessita una classificació en línia en lloc d'una de local.

Com ho aborda Serenity

Serenity exposa el comportament de classificació a través d'ILeaderboardService, amb SubmitAsync, GetTopAsync, GetPlayerRankAsync, GetAroundPlayerAsync i ClearAsync. Cada taula es descriu amb un LeaderboardDefinition — direcció d'ordenació, retenció BestPerPlayer o FullHistory i un límit MaxEntries — i el rànquing va a càrrec d'un LeaderboardRanker determinista amb semàntica d'empats SQL RANK() documentada. Cada tramesa i cada esborrat emeten LeaderboardEntrySubmittedSignal o LeaderboardClearedSignal a través de l'event dispatcher.

L'emmagatzematge és intercanviable gràcies al contracte genèric de persistència IStructuredStore, compartit amb la resta de dades estructurades de Serenity: PlayerPrefs per a taules locals del dispositiu, fitxers JSON llegibles, una base de dades SQLite incrustada, el teu propi servei HTTP o una connexió directa a Postgres, MySQL o MongoDB. LeaderboardBackendFactory no llança mai excepcions: un backend mal configurat registra un avís i recorre a PlayerPrefs en lloc de trencar el joc.

Com encaixa a Serenity

L'agregat Leaderboard manté el rànquing independent del motor al nucli de Business — ILeaderboardService, LeaderboardDefinition, LeaderboardRanker i els senyals viuen al marge d'Unity. La capa d'Unity hi afegeix UnityLeaderboardSettings per configurar les taules, UnityLeaderboardScoreBridge per connectar el sistema de Puntuació amb les trameses fent servir el device-id o una identitat de jugador personalitzada, i LeaderboardBackendFactory per resoldre el backend configurat.

Sobre el nucli s'hi recolza UnityLeaderboardViewDefinition, una vista de primer nivell registrada al ViewRouter: presentació Top-N o al voltant de la posició del jugador, nombre d'entrades configurable i formats de valor que inclouen els temps M:SS i H:MM:SS, accessible des de qualsevol opció de menú o mitjançant ShowLeaderboardSignal sense escriure codi. El slot de tema LeaderboardTemplate ve inclòs als 8 temes de sèrie, de manera que la taula es renderitza amb el llenguatge visual del tema actiu sense prefabs a mida.

Flux de treball pràctic

1. Defineix una taula amb LeaderboardDefinition — direcció d'ordenació, retenció BestPerPlayer o FullHistory i un límit MaxEntries.
2. Envia puntuacions amb ILeaderboardService.SubmitAsync, o connecta UnityLeaderboardScoreBridge perquè les enviï automàticament cada vegada que el sistema de Puntuació registri un valor nou.
3. Consulta els resultats amb GetTopAsync, GetPlayerRankAsync o GetAroundPlayerAsync per construir la teva pròpia interfície, o deixa que UnityLeaderboardViewDefinition els mostri per tu.
4. Registra la vista al ViewRouter i obre-la des de qualsevol opció de menú o emetent ShowLeaderboardSignal — sense cablejar res a l'escena.
5. O salta't els passos manuals i executa Create Leaderboard: tria un preset, tria la puntuació que vols seguir, tria on viuran les dades i, si vols, obtén una pantalla de classificació llesta per navegar.

Què inclou

• Servei de classificació ILeaderboardService amb SubmitAsync, GetTopAsync, GetPlayerRankAsync, GetAroundPlayerAsync i ClearAsync
• LeaderboardRanker determinista amb semàntica d'empats SQL RANK() documentada
• LeaderboardDefinition per taula amb retenció BestPerPlayer o FullHistory i límit MaxEntries
• Senyals LeaderboardEntrySubmittedSignal i LeaderboardClearedSignal emesos a través de l'event dispatcher
• Emmagatzematge intercanviable mitjançant IStructuredStore — PlayerPrefs, JSON amb LocalFile, SQLite incrustat, HTTP o connexió directa a Postgres/MySQL/MongoDB
• UnityLeaderboardViewDefinition integrada amb els temes, amb presentació Top-N o al voltant del jugador i formats de temps M:SS/H:MM:SS
• UnityLeaderboardScoreBridge, que connecta el sistema de Puntuació amb les trameses fent servir device-id o una identitat de jugador personalitzada
• Assistent Create Leaderboard de cinc passos amb reversió completa si alguna cosa falla

Quan fer-lo servir

• Jocs que necessiten una taula de rècords o de millors temps sense escriure a mà el rànquing, l'emmagatzematge i la interfície per triplicat.
• Projectes que volen començar amb una classificació local i passar a una en línia més endavant sense reescriure el codi del joc.
• Equips que volen una pantalla de classificació connectada a un menú existent sense que un programador toqui l'escena.
• Bases de codi que ja fan servir el sistema de Puntuació i volen que les trameses siguin automàtiques, en coordinació amb Persistència i els Temes d'Interfície.

Sistemes relacionats

• Sistema de Puntuació Multi-Mètrica Un model de puntuació dinàmic que rastreja qualsevol nombre de mètriques amb nom a través d'un únic servei, retornant instantànies immutables que les regles de joc no han de posseir mai.
• Capa de Persistència de Dades Una jerarquia de ports que desacobla els contractes de desat dels backends de Unity perquè l'emmagatzematge en fitxers, PlayerPrefs i el xifratge puguin canviar sense tocar el codi del joc.
• Temes d'UI Temes d'UI basats en ScriptableObject que comparteixen visuals i feedback sonor entre menús, modals i pantalles.
• Sistema de menús Menús declaratius, temes d'UI compartits i navegació predictible, configurats com a assets en lloc de cablejats a mà sobre GameObjects.