Sidebar de Gamificación — Guía de implementación (v2.0)

Alcance: 1 — Gamificación Estado: Implementado y validado en local y Pruebas (curso piloto 3; config general a nivel sitio en ambos) Diseño: Figma — Gamification Sidebar, node 19829-3930 Motor: block_xp Community v19.0 (build 2025100500) — sin modificar su código

Qué es

Rediseño del drawer derecho de los cursos con 3 tarjetas según Figma:

1. Tu gema de experiencia — block_xp: imagen de la gema, "Nivel N", nombre de la gema, "X XP acumulados", barra de progreso y "N XP para el siguiente nivel".
2. Colección de logros — bloque nuevo block_pccntr8203403_logros: contador "X de Y desbloqueados", grid de insignias ganadas (imagen + nombre) y bloqueadas (círculo con candado), enlace "Ver todos".
3. Ver todas las insignias — footer del mismo bloque: texto motivacional + botón "Explorar insignias".

block_stash ("Objetos recompensas") se mantiene debajo con restyle de chrome (solo SCSS).

Arquitectura implementada

Pieza	Mecanismo	Archivos
Card 1	Overrides de theme sobre block_xp	theme/cdigital/classes/output/block_xp_renderer.php (override de level_name(), solo ruta $force=false), templates/blockxp_levelname.mustache, templates/block_xp/xp-widget.mustache, templates/block_xp/progress-bar.mustache
Cards 2+3	Bloque nuevo	blocks/pccntr8203403_logros/ (block_base + templates/content.mustache, solo lectura sobre badgeslib.php)
Estilos	SCSS del theme	theme/cdigital/scss/gamification.scss, concatenado en theme_cdigital_get_main_scss_content() (lib.php); fuente Lexend auto-hospedada en fonts/Lexend-latin.woff2 (SIL OFL)
Config general	Defaults de admin de block_xp	mdl_config_plugins (blocktitle, blockrankingsnapshot, blockdescription, levelsdata)

Hechos técnicos clave (verificados en branch 501)

• El renderer de block_xp es legacy (class block_xp_renderer extends plugin_renderer_base, blocks/xp/renderer.php:43). Con theme_overridden_renderer_factory activo, la clase autoloaded theme_cdigital\output\block_xp_renderer lo reemplaza sin tocar el plugin.
• level_name() se usa en el widget (classes/output/xp_widget.php:237) y en levels_grid() (página admin de niveles); el override delega en el padre cuando $force=true para no alterar las páginas de administración.
• Herencia de niveles: si mdl_block_xp_config.levelsdata del curso está vacío, block_xp usa los default levels de admin (classes/local/factory/levels_factory.php:94-116). Las 8 Gemas se configuran una sola vez a nivel sitio — no hace falta UPDATE por curso.
• Formato de levelsdata v2: xp es un array plano 0-based, pero los metadatos (name, desc) se indexan por número de nivel (1-based) — ver levels_info_writer::construct_finaldata(). Un name como array plano queda corrido un nivel.
• Para que los bloques aparezcan dentro de actividades: instancia con pagetypepattern='*' y showinsubcontexts=1 (contexto padre = curso).

Configuración aplicada

Nivel sitio (todas las configuraciones generales)

• blocktitle = "Tu gema de experiencia", blockrankingsnapshot = 0, blockdescription = '' (defaults de admin de block_xp).
• Niveles por defecto: 8 Gemas, método flat (0/500/…/3500) con nombres 1-based; imágenes cargadas en Admin → Level Up XP → visuals (subidas vía UI).

Curso 3 (piloto)

• Instancia block_xp: pagetypepattern='*', showinsubcontexts=1, side-pre weight -2. La fila migrada de mdl_block_xp_config pisaba los defaults → se alinearon blocktitle/blockdescription/blockrankingsnapshot de la instancia.
• Bloque "Colección de logros" (id según instalación) en side-pre weight -1; stash weight 0. Se eliminaron posiciones legacy (mdl_block_positions en side-post de un theme anterior) de xp y stash.
• Completion: actividad de bienvenida (cm 44) con completion automática al ver; quiz 93 con gradepass=60 + "requiere calificación aprobatoria"; criterios de course completion = 1 actividad representativa por módulo (cms 52, 62, 76, 83, 93, agregación ALL).

Insignias

La matriz de asignación (12 insignias del xlsx v3: 4 globales + 8 de curso) está en Insignias. Las imágenes viven en requierments/assets/insignias/ (repo) y las gemas en requierments/assets/niveles/.

Validación ejecutada (local)

Recorrido simulado con el estudiante de prueba estudiante.gamificacion (scripts CLI vía docker exec, asserts contra mdl_badge_issued): los 12 criterios otorgan correctamente, incluidos el encadenado (Bienvenida → Primer Despegue), el coleccionista (5 badges → Coleccionista), courseset (Pionero), perfil con campo custom de fecha, y nota aprobatoria (Impulso Renovado); "Aliado Inteligente" permanece inactiva. Render verificado por HTTP como estudiante: Card 1 "Nivel 3 / Gema Violeta" con barra al 48 % para 1.240 XP, Card 2 "8 de 8 desbloqueados" con imágenes, y "0 de 8" + 8 candados para un estudiante nuevo; ambos bloques presentes también dentro de actividades (mod-*).

Operación

La configuración por curso (finalización, insignias, bloques) está documentada para usuarios finales en la guía para gestores de cursos.

• Tras editar mustache/SCSS del theme: bump de theme/cdigital/version.php + php admin/cli/purge_caches.php.
• El bloque de logros se oculta solo a estudiantes cuando el curso no tiene insignias activas (contenido vacío).
• Réplica a otros cursos: añadir los 2 bloques al curso (o vía "Any page matching course"), crear las course badges (duplicar y reapuntar course_modules) y verificar que el curso no personaliza levelsdata (hereda las Gemas).

Riesgos y checklist de upgrade

Los overrides son copias/extensiones que dependen del contrato interno de block_xp (variables de contexto de sus plantillas y firma de level_name). El acoplamiento es blando: el peor caso es volver al aspecto por defecto; los datos de XP no corren riesgo.

#	Riesgo	Mitigación
1	Upgrade block_xp v19 → v20 renombra variables de contexto o la firma de level_name	En cada update: diff de blocks/xp/templates/{xp-widget,progress-bar,level-badge}.mustache y de renderer.php::level_name contra las copias del theme (checklist en ADR-004)
2	block_xp migra a renderer namespaced	La factory dejaría de matchear la clase del theme silenciosamente (vuelve el look default); añadido a la checklist
3	Caché mustache oculta cambios	Purga + bump de versión
4	Corte de badges_get_badges en 50	$perpage = 0 explícito en el bloque

Historia del replanteo (v1.5 → v2.0): el motor no-code del plan operativo se mantiene; esta guía añade la capa de presentación y actualiza la lista de insignias al xlsx v3 (requierments/Gamificación - Campus virtual.xlsx). Decisión de arquitectura: ADR-004.