PLAN: Gamificación — Campus Virtual

Versión: 1.4
Plataforma: Moodle 5.1 (Docker + MariaDB 10.11)
Decisión final: Camino A — Solo Moodle nativo + block_xp Community (sin suscripción, sin código)
Fuente: 01-gamificacion-campus-virtual-v2.xlsx

Documento soporte del requerimiento (guía operativa paso a paso, Alcance 1). El estado configurado del sistema se documenta en Gamificación; la correspondencia con los desarrollos, en Alcances y desarrollos.

Extensión del alcance — Sidebar de Gamificación (v2.0, implementado)

El alcance 1 se extendió con una capa de presentación con código (restyle del drawer del curso según diseño Figma: gema de experiencia, colección de logros y CTA de insignias), ya implementada y validada en local sobre el curso piloto 3. Ver la guía de implementación del Sidebar (v2.0).

Además, la lista de insignias de este documento (10 activas de la propuesta v2) fue reemplazada por la spec v3 (requierments/Gamificación - Campus virtual.xlsx): 12 insignias — 4 globales (entran "Coleccionista" y "Perfil") y 8 de curso ("Aliado Inteligente" pasa a curso, diferida). La matriz vigente está en Insignias. Las Gemas ahora se configuran a nivel sitio (defaults de admin, heredados por los cursos) — ver Gemas; el JSON de la Fase 1.3 de este plan quedó obsoleto (los nombres deben indexarse 1-based).

Contexto

El campus tiene instalado el stack: block_xp (Level Up XP v19.0 Community), block_stash y el sistema nativo de badges de Moodle. El requerimiento define dos sistemas: 8 niveles Gema (XP acumulado) y 12 insignias (logros certificados). Los objetos stash existentes (Binoculares, Brújula, Lupa, Mapa) son compatibles y se conservan sin modificar.

Esta v1.4 es la guía operativa paso a paso para implementar la propuesta v2 acordada con el cliente, sin código y sin suscripciones.

Arquitectura

Capa	Plugin	Mecánica
Gemas	`block_xp` Community	XP acumulado → nivel con imagen personalizada
Insignias	Moodle Badges (`mdl_badge_issued`)	Criterio cumplido → OpenBadge certificado
Objetos	`block_stash`	Ítem coleccionable por módulo (sin cambios)

Alcance v2 (10 insignias activas)

#	Insignia	Estado	Tipo	Mecanismo nativo
1	Primer Despegue	Activa (criterio ajustado)	Site badge	Activity completion del curso de bienvenida
2	Racha Conectada	ELIMINADA	—	No implementable sin código
3	Ruta Activada	ELIMINADA	—	No implementable sin código
4	Exploración Digital	Activa (criterio ajustado)	Course badge	Activity completion (1 por módulo)
5	Pionero del Aprendizaje	Activa	Site badge	Completing a set of courses (N=1)
6	Explorador Inicial	Activa	Course badge	Activity completion (cualquier 1)
7	Reto Entregado	Activa	Course badge	Activity completion (tareas/quiz)
8	Avance en Terreno	Activa	Course badge	Activity completion (50% manual)
9	Zona Superada	Activa	Course badge	Activity completion (todas del módulo)
10	Impulso Renovado	Activa (criterio ajustado)	Course badge	Activity completion con grade condition
11	Misión Cumplida	Activa	Course badge	Course completion
12	Aliado Inteligente	Diferida (inactiva)	Site badge	Pendiente del tutor IA

Total: 10 activas · 2 eliminadas · 1 diferida

Sistema de Gemas — 8 Niveles XP

Configuración en block_xp con método flat (umbrales fijos cada 500 XP):

Nivel	Nombre	XP mínimo
1	Gema Alba	0
2	Gema Aqua	500
3	Gema Violeta	1.000
4	Gema Esmeralda	1.500
5	Gema Solar	2.000
6	Gema Coral	2.500
7	Gema Índigo	3.000
8	Gema Prisma	3.500

Entorno de Ejecución (referencia para todos los pasos)

Recurso	Valor
Container DB	`colombiaaprende_db` (mariadb:10.11)
Container web	`colombiaaprende_web` (PHP 8.3)
BD	`moodle` (user `moodle`, password en `local/.env`)
Web root	`/Users/imac/Desktop/campusvirtual/local/APP158C/public/`
Moodledata	`/Users/imac/Desktop/campusvirtual/local/moodledata/`
Admin URL	`http://localhost:8080/admin/`
Variables .env	`MYSQL_ROOT_PASSWORD`, `MYSQL_PASSWORD`

Convenciones del documento:

[UI] = paso manual en el navegador (Admin UI)
[SQL] = script SQL contra la base de datos
[Archivos] = manipulación del sistema de archivos
[Código] = ajuste de código fuente / configuración
Checkpoint = punto de verificación

Ruta de Implementación Paso a Paso

FASE 0 — Preparación y Backup

0.1 [SQL] Backup completo de la base de datos (obligatorio antes de cualquier cambio)

docker exec colombiaaprende_db sh -c \
  'exec mariadb-dump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction moodle' \
  > /Users/imac/Desktop/campusvirtual/database_backups/moodle_pre_gamificacion_$(date +%Y%m%d_%H%M%S).sql

0.2 [SQL] Backup focalizado de las tablas que se van a tocar (rollback rápido)

docker exec colombiaaprende_db sh -c \
  'exec mariadb-dump -uroot -p"$MYSQL_ROOT_PASSWORD" moodle \
   mdl_block_xp_config mdl_badge mdl_badge_criteria mdl_badge_criteria_param' \
  > /Users/imac/Desktop/campusvirtual/database_backups/gamificacion_tablas_$(date +%Y%m%d_%H%M%S).sql

Ambos dumps son artefactos de este mismo ambiente (Local): sirven solo de rollback local, nunca para poblar Pruebas, Certificación ni Producción — ver qué NO incluye la entrega.

0.3 [SQL] Verificar estado actual de block_xp

-- Ejecutar: docker exec -it colombiaaprende_db mariadb -uroot -p moodle
SELECT id, courseid, enabled, levels,
       SUBSTRING(levelsdata, 1, 80) AS levelsdata_preview
FROM mdl_block_xp_config;

0.4 [UI] Definir curso piloto

Ir a http://localhost:8080/admin/search.php?query=courses → elegir un curso de prueba
Anotar su courseid (visible en la URL ?id=X)
En este plan se asume courseid = <PILOTO> como placeholder

Checkpoint 0

Backups en database_backups/ y courseid piloto anotado.

FASE 1 — Configurar las 8 Gemas en block_xp

1.1 [UI] Decidir scope del block_xp

Por curso (recomendado): cada curso tiene su propia barra de XP
Global: una sola barra de XP a nivel sitio

URL: http://localhost:8080/admin/settings.php?section=block_xp_default_admin_settings

1.2 [UI] Activar "niveles personalizados con imagen"

Por cada curso piloto:

Ir al curso → Activar edición
En el bloque "Level Up XP" → engranaje → "Configuración"
Pestaña "Niveles" → marcar "Permitir personalizar los niveles"
Cambiar número de niveles a 8
Cambiar método a "Flat" (umbrales fijos, sin curva)

1.3 [SQL] Aplicar JSON de las 8 Gemas vía SQL

Archivo /tmp/gemas_levelsdata.sql:

-- Aplicar configuración de 8 Gemas a TODOS los cursos donde block_xp esté habilitado
UPDATE mdl_block_xp_config
SET    levels      = 8,
       levelsdata  = '{"v":2,"algo":{"method":"flat","base":500,"coef":1.0,"incr":500},"xp":[0,500,1000,1500,2000,2500,3000,3500],"name":["Gema Alba","Gema Aqua","Gema Violeta","Gema Esmeralda","Gema Solar","Gema Coral","Gema Índigo","Gema Prisma"],"desc":["","","","","","","",""]}'
WHERE  enabled = 1;

-- Verificar
SELECT id, courseid, levels, SUBSTRING(levelsdata, 1, 60) AS preview
FROM mdl_block_xp_config WHERE enabled = 1;

Ejecutar:

docker exec -i colombiaaprende_db sh -c \
  'exec mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" moodle' < /tmp/gemas_levelsdata.sql

Alternativa solo curso piloto (recomendado primero):

UPDATE mdl_block_xp_config
SET    levels = 8, levelsdata = '<JSON ARRIBA>'
WHERE  courseid = <PILOTO>;

1.4 [Archivos] Subir las 8 imágenes PNG de las Gemas

Generar las imágenes con los prompts del Excel v2 (sheet GEMAS). Tamaño: 256×256 px, fondo transparente, PNG.

Vía Admin UI:

Curso piloto → bloque XP → Configuración → Niveles
Para cada nivel (1 a 8) → "Imagen" → cargar el PNG correspondiente
Guardar

Identificar contextid del bloque (si se requiere automatización masiva):

SELECT bi.id AS blockinstanceid, ctx.id AS contextid, ctx.path, bi.parentcontextid
FROM mdl_block_instances bi
JOIN mdl_context ctx ON ctx.contextlevel = 80 AND ctx.instanceid = bi.id
WHERE bi.blockname = 'xp';

1.5 [CLI] Purgar cachés

docker exec colombiaaprende_web php /var/www/html/admin/cli/purge_caches.php

Checkpoint 1

Login como usuario de prueba en el curso piloto
Bloque XP debe mostrar "Gema Alba" como nivel 1, próximo nivel en 500 XP
SQL: SELECT courseid, levels FROM mdl_block_xp_config WHERE enabled=1 debe mostrar levels=8

FASE 2 — Preparar Imágenes de las Insignias

2.1 [Archivos] Generar las 10 imágenes PNG de insignias

Usar los prompts del Excel v2 (sheet INSIGNIAS, columna "Prompt de diseño 3D"). Convención de nombres:

01_primer_despegue.png
04_exploracion_digital.png
05_pionero_aprendizaje.png
06_explorador_inicial.png
07_reto_entregado.png
08_avance_en_terreno.png
09_zona_superada.png
10_impulso_renovado.png
11_mision_cumplida.png
12_aliado_inteligente.png   (para badge inactiva)

Tamaño: 256×256 px PNG, fondo transparente.
Guardar en /Users/imac/Desktop/campusvirtual/assets/badges/.

FASE 3 — Crear Insignias GLOBALES (site badges)

3.1 [UI] Insignia #1 "Primer Despegue"

Pre-requisito: curso de bienvenida con 1 actividad de bienvenida marcada con activity completion.

Pasos:

Ir a http://localhost:8080/badges/index.php?type=1 (Site badges)
"Agregar una nueva insignia"
Detalles:
- Nombre: Primer Despegue
- Descripción: Iniciaste tu recorrido en Campus Virtual
- Emisor: nombre del campus
- Imagen: 01_primer_despegue.png
Guardar → pestaña "Criterios"
Dropdown "Agregar criterio" → "Insignias otorgadas"

Atención: Las site badges nativas no soportan "Activity completion" directamente. Workaround: crear primero un course badge "Bienvenida" en el curso introductorio con criterio activity completion, y luego site badge "Primer Despegue" con criterio "Awarded badges = Bienvenida".

Crear primero la badge intermedia "Bienvenida" en el curso de bienvenida (patrón Fase 4), luego volver y seleccionarla como criterio
Pestaña "Resumen" → "Habilitar acceso"

3.2 [UI] Insignia #5 "Pionero del Aprendizaje"

Site badges → "Agregar una nueva insignia"
Detalles:
- Nombre: Pionero del Aprendizaje
- Descripción: Completaste tu primer curso en Campus Virtual
- Imagen: 05_pionero_aprendizaje.png
Criterios → "Completing a set of courses"
Seleccionar lista de cursos → "Cualquiera de los cursos seleccionados" → mínimo 1
"Habilitar acceso"

3.3 [UI] Insignia #12 "Aliado Inteligente" (DIFERIDA, crear inactiva)

Site badges → "Agregar una nueva insignia"
Nombre: Aliado Inteligente, descripción: Usaste la tutora virtual para resolver una duda, imagen: 12_aliado_inteligente.png
NO habilitar acceso — dejar en estado inactiva

Checkpoint 3

-- Verificar las 3 site badges
SELECT id, name, type, status FROM mdl_badge WHERE type = 1;
-- type=1: site badge, status=1 active, status=0 inactive

Esperado: 3 filas — Primer Despegue (status 1), Pionero del Aprendizaje (status 1), Aliado Inteligente (status 0).

FASE 4 — Crear Insignias POR CURSO (course badges)

Patrón a repetir en cada curso. Documentar la primera vuelta en el curso piloto; luego replicar via UI (Course badges → ⋮ → Duplicate).

URL de course badges: http://localhost:8080/badges/index.php?type=2&id=<PILOTO>

4.1 [UI] Insignia #6 "Explorador Inicial"

Course badges → "Agregar una nueva insignia"
Nombre: Explorador Inicial, descripción: Completaste tu primera actividad del curso, imagen: 06_explorador_inicial.png
Criterios → "Activity completion"
Marcar cualquier 1 actividad → "Cualquiera de los seleccionados"
"Habilitar acceso"

4.2 [UI] Insignia #7 "Reto Entregado"

Course badges → "Agregar una nueva insignia"
Nombre: Reto Entregado, imagen 07_reto_entregado.png
Criterios → "Activity completion"
Marcar TODAS las tareas (assign) y cuestionarios (quiz) → "Cualquiera de los seleccionados"
Habilitar acceso

4.3 [UI] Insignia #8 "Avance en Terreno" (50%)

Pre-requisito: el docente lista manualmente el 50% de actividades del curso.

Course badges → "Agregar una nueva insignia"
Nombre: Avance en Terreno, imagen 08_avance_en_terreno.png
Criterios → "Activity completion"
Marcar el 50% → "Todas las seleccionadas" (AND)
Habilitar acceso

4.4 [UI] Insignia #9 "Zona Superada"

Pre-requisito: identificar las CMs que componen un módulo/sección.

Course badges → "Agregar una nueva insignia"
Nombre: Zona Superada, imagen 09_zona_superada.png
Criterios → "Activity completion"
Marcar TODAS las CMs del módulo → "Todas las seleccionadas"
Habilitar acceso

Si hay N módulos, crear N copias ("Zona Superada — Módulo 1", "Módulo 2", …) cada una con las CMs de su módulo.

4.5 [UI] Insignia #10 "Impulso Renovado"

Pre-requisito: la actividad evaluable debe tener configurado Activity completion con "Requiere calificación de aprobación" (Settings de la actividad → "Conclusión de la actividad" → "Requiere calificación" + "Requiere calificación de aprobación").

Course badges → "Agregar una nueva insignia"
Nombre: Impulso Renovado, imagen 10_impulso_renovado.png
Criterios → "Activity completion"
Marcar las evaluaciones con requisito de nota → "Cualquiera de los seleccionados"
Habilitar acceso

4.6 [UI] Insignia #11 "Misión Cumplida"

Pre-requisito: el curso debe tener Course completion habilitado.

Course badges → "Agregar una nueva insignia"
Nombre: Misión Cumplida, imagen 11_mision_cumplida.png
Criterios → "Course completion"
Habilitar acceso

4.7 [UI] Insignia #4 "Exploración Digital" (1 por módulo)

Pre-requisito: identificar 1 actividad representativa por módulo.

Course badges → "Agregar una nueva insignia"
Nombre: Exploración Digital, imagen 04_exploracion_digital.png
Criterios → "Activity completion"
Marcar 1 actividad por módulo → "Todas las seleccionadas" (AND)
Habilitar acceso

4.8 [SQL] Verificación de course badges del piloto

SELECT b.id, b.name, b.status, COUNT(bc.id) AS num_criteria
FROM mdl_badge b
LEFT JOIN mdl_badge_criteria bc ON bc.badgeid = b.id
WHERE b.type = 2 AND b.courseid = <PILOTO>
GROUP BY b.id;

Esperado: 7 badges, todas con status 1.

4.9 [Código] (Opcional) Replicar al resto de cursos

Moodle permite duplicar via UI (Course badges → ⋮ → Duplicate). Tras duplicar hay que volver a apuntar los course_modules del curso destino. Recomendación: para el primer release, duplicar manualmente y validar curso a curso.

Checkpoint 4

Login como estudiante en el curso piloto
Completar 1 actividad → debe otorgarse "Explorador Inicial"
Ver http://localhost:8080/badges/mybadges.php → la badge aparece

FASE 5 — Activity Completion: Habilitación a Nivel Curso

5.1 [UI] Por cada curso del campus

Settings del curso → "Completion tracking" = Yes
Por cada actividad relevante: Settings → "Activity completion" → configurar condiciones (view, grade, submit)

5.2 [SQL] Verificar cursos con completion habilitado

SELECT id, fullname, enablecompletion FROM mdl_course WHERE enablecompletion = 0;

Esperado: ningún resultado (o solo cursos descartados explícitamente).

5.3 [SQL] Habilitar Course Completion para badge #11

UPDATE mdl_course SET enablecompletion = 1 WHERE id IN (<lista_de_courseids>);

Tras esto, definir el criterio en Course → More → Course completion → Edit.

FASE 6 — Insignia Diferida #12 "Aliado Inteligente"

Creada inactiva en 3.3. Cuando exista el tutor IA:

[UI] Site badges → editar "Aliado Inteligente" → Criterios → elegir criterio apropiado (probablemente "Awarded badges" intermedio o "Manual issue by role" como fallback)
Habilitar acceso

FASE 7 — Stash (Objetos): Sin Cambios

block_stash mantiene sus 4 objetos. No tocar. Solo verificar:

SELECT s.id, s.name, s.courseid
FROM mdl_block_stash s
JOIN mdl_block_stash_items i ON i.stashid = s.id;

Resumen de Cambios por Tipo de Acción

Tipo	Cantidad	Detalle
[UI] Manual Admin UI	~15 pasos	Configurar bloque XP, crear 10 badges, habilitar criterios
[SQL] SQL directo	3 scripts	(1) backup, (2) actualizar `levelsdata` Gemas, (3) habilitar `enablecompletion`
[Archivos] Sistema de archivos	8 + 10 PNGs	8 imágenes Gema + 10 imágenes Insignia
[Código] Código fuente	0	No se modifica nada de Moodle ni de block_xp

Verificación End-to-End

#	Prueba	Cómo ejecutar	Resultado esperado
1	Gemas configuradas	SQL: `SELECT levels, JSON_EXTRACT(levelsdata,'$.name') FROM mdl_block_xp_config WHERE enabled=1;`	`levels=8`, lista Gema Alba…Gema Prisma
2	Imagen Gema 1	Login estudiante → bloque XP en curso piloto	Imagen Gema Alba visible
3	XP al ver curso	Visitar curso varias veces	Acumulación XP > 0
4	Subir nivel	Acumular ≥500 XP	Pop-up "Gema Aqua"
5	Badge #6 Explorador Inicial	Completar 1 actividad	Badge en `/badges/mybadges.php`
6	Badge #7 Reto Entregado	Enviar 1 tarea	Badge otorgada
7	Badge #8 Avance en Terreno	Completar 50% actividades	Badge otorgada
8	Badge #9 Zona Superada	Completar todas CMs del módulo	Badge otorgada
9	Badge #10 Impulso Renovado	Aprobar evaluación	Badge otorgada
10	Badge #11 Misión Cumplida	Completar el curso	Badge automática
11	Badge #4 Exploración Digital	Completar 1 actividad por módulo	Badge otorgada
12	Badge #5 Pionero del Aprendizaje	Completar 1 curso	Site badge otorgada
13	Badge #1 Primer Despegue	Completar actividad de bienvenida	Site badge otorgada
14	Badge #12 inactiva	SQL: `SELECT status FROM mdl_badge WHERE name='Aliado Inteligente';`	`status=0`
15	Stash intacto	SQL: 4 ítems en `mdl_block_stash_items`	Sin cambios

Query maestra de auditoría:

SELECT b.name, b.type, COUNT(bi.id) AS otorgadas
FROM mdl_badge b
LEFT JOIN mdl_badge_issued bi ON bi.badgeid = b.id
GROUP BY b.id ORDER BY b.type, b.name;

Rollback

# Restaurar tablas tocadas:
docker exec -i colombiaaprende_db sh -c \
  'exec mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" moodle' \
  < /Users/imac/Desktop/campusvirtual/database_backups/gamificacion_tablas_<TIMESTAMP>.sql

# Purgar cachés tras el rollback:
docker exec colombiaaprende_web php /var/www/html/admin/cli/purge_caches.php

Restaurar siempre un dump tomado en este mismo ambiente (Local). Nunca uno traído de Pruebas, Certificación ni Producción.

Notas

Implementación no-code, sin suscripción: solo Moodle nativo + block_xp Community.
2 insignias del Excel original (#2 Racha Conectada, #3 Ruta Activada) eliminadas: requerían código custom.
3 criterios ajustados: #1, #4, #10 (documentado en Gamificación - Campus virtual_v2propuesta.xlsx).
1 insignia diferida: #12 Aliado Inteligente, creada inactiva.
Objetos block_stash no se modifican.
El primer despliegue se ejecuta sobre un curso piloto antes de replicar al resto.
Lo que se replica hacia Pruebas es configuración (defaults de block_xp, criterios e imágenes de insignias), nunca los datos del usuario de prueba usado para validar los checkpoints de este plan — ver qué NO incluye la entrega.

Contexto​

Arquitectura​

Alcance v2 (10 insignias activas)​

Sistema de Gemas — 8 Niveles XP​

Entorno de Ejecución (referencia para todos los pasos)​

Ruta de Implementación Paso a Paso​

FASE 0 — Preparación y Backup​

0.1 [SQL] Backup completo de la base de datos (obligatorio antes de cualquier cambio)​

0.2 [SQL] Backup focalizado de las tablas que se van a tocar (rollback rápido)​

0.3 [SQL] Verificar estado actual de block_xp​

0.4 [UI] Definir curso piloto​

Checkpoint 0​

FASE 1 — Configurar las 8 Gemas en block_xp​

1.1 [UI] Decidir scope del block_xp​

1.2 [UI] Activar "niveles personalizados con imagen"​

1.3 [SQL] Aplicar JSON de las 8 Gemas vía SQL​

1.4 [Archivos] Subir las 8 imágenes PNG de las Gemas​

1.5 [CLI] Purgar cachés​

Checkpoint 1​

FASE 2 — Preparar Imágenes de las Insignias​

2.1 [Archivos] Generar las 10 imágenes PNG de insignias​

FASE 3 — Crear Insignias GLOBALES (site badges)​

3.1 [UI] Insignia #1 "Primer Despegue"​

3.2 [UI] Insignia #5 "Pionero del Aprendizaje"​

3.3 [UI] Insignia #12 "Aliado Inteligente" (DIFERIDA, crear inactiva)​

Checkpoint 3​

FASE 4 — Crear Insignias POR CURSO (course badges)​

4.1 [UI] Insignia #6 "Explorador Inicial"​

4.2 [UI] Insignia #7 "Reto Entregado"​

4.3 [UI] Insignia #8 "Avance en Terreno" (50%)​

4.4 [UI] Insignia #9 "Zona Superada"​

4.5 [UI] Insignia #10 "Impulso Renovado"​

4.6 [UI] Insignia #11 "Misión Cumplida"​

4.7 [UI] Insignia #4 "Exploración Digital" (1 por módulo)​

4.8 [SQL] Verificación de course badges del piloto​

4.9 [Código] (Opcional) Replicar al resto de cursos​

Checkpoint 4​

FASE 5 — Activity Completion: Habilitación a Nivel Curso​

5.1 [UI] Por cada curso del campus​

5.2 [SQL] Verificar cursos con completion habilitado​

5.3 [SQL] Habilitar Course Completion para badge #11​

FASE 6 — Insignia Diferida #12 "Aliado Inteligente"​

FASE 7 — Stash (Objetos): Sin Cambios​

Resumen de Cambios por Tipo de Acción​

Verificación End-to-End​

Rollback​

Notas​