NextAgentX/pipeline-produccion-juegos

Pipeline de producción de juegos de extremo a extremo

Lleva una idea hasta un producto compilable + plan de lanzamiento. Cada fase tiene artefactos fijos, rutas fijas y puertas de etapa ejecutables; no se permite saltar fases.

Los siguientes roles son opcionales y solo se utilizan si el entorno actual lo admite y está permitida la delegación; de lo contrario, el asistente actual los completa directamente. El alcance del trabajo se selecciona según la autorización real del usuario y la fase del proyecto. Los scripts de estado solo verifican títulos de documentos y TODOs; no verifican automáticamente recursos, compilaciones reales ni pruebas en dispositivos; estas deben ejecutarse por separado y registrarse los resultados.

Las cinco fases de producción, los hitos G1–G5, los ciclos Sprint y el ajuste del tamaño del equipo se describen en references/production-cycle.md. La siguiente tabla de siete fases corresponde a los subportones de artefactos documentales y no tiene una correspondencia uno a uno con los hitos de producción.

Fases y artefactos

Fase	Resultado	Rol responsable
brief	docs/00-brief.md Ficha de proyecto	Productor (tú mismo)
gdd	docs/01-gdd.md	game-narrative-designer
tech	docs/02-tech.md	cocos-engineer, unity-engineer o godot-engineer
art	docs/03-art.md + docs/art-style-bible.md + Arte definitivo + assets/manifest.json	game-art-director
audio	docs/04-audio.md + Audio definitivo	game-audio-designer
qa	docs/05-qa.md	game-qa-engineer
release	docs/06-release.md	game-release-operator

El esqueleto completo está en templates/docs/ del plugin; se copia a docs/ del proyecto y luego se completa. Si los [TODO] del esqueleto no se completan, la puerta de etapa no se abre.

Herramientas (incluidas en el plugin, se llaman directamente con Python)

Directorio de scripts = raíz del plugin scripts/. Si no estás seguro de la ruta absoluta, primero ejecuta codex plugin list para encontrar la ruta del plugin.

Propósito	Comando
Inicializar estado	python scripts/omni_state.py init --root . --engine godot --platforms web,android
Ver progreso de fases	python scripts/omni_state.py status --root .
Validar una fase	python scripts/omni_state.py check --root . --stage gdd
Avanzar fase (con puerta)	python scripts/omni_state.py advance --root .
Generar arte provisional (solo verificar pipeline)	python scripts/gen_placeholder_art.py --manifest assets/manifest.json --root .
Hoja de ruta de producción	Copiar templates/docs/07-production-roadmap.md a docs/
Planificación y retrospectiva de Sprint	Copiar templates/docs/08-sprint-review.md, registrar versión integrada, pruebas y feedback cada ciclo
Revisión de puertas de etapa	Copiar templates/docs/09-milestones.md, registrar revisiones G1–G5 y post-lanzamiento
Postprocesado de arte	python scripts/process_art.py --in raw/x.png --out assets/art/x.png --size 256x64 --key-color "#FFFFFF" --check-nine --nine-slice 24
División de fotogramas de animación IA	python scripts/split_sprite_sheet.py --input raw/sheet.png --cols 4 --rows 2 --fps 12 --loop --out-dir assets/animation/run --backup-dir doc/temp/run-frames
Imagen / GIF por IA	python scripts/gen_ai_image.py --prompt "single game icon" --format png --out assets/art/icon.png --backup-dir doc/temp --dry-run
Efecto de sonido por IA	python scripts/gen_ai_audio.py sfx --prompt "short sci-fi pickup" --duration 1 --out assets/audio/pickup.mp3
Música por IA	python scripts/gen_ai_audio.py music --prompt "gentle space exploration" --duration 30 --instrumental --out assets/audio/main.mp3
Generar BGM (chiptune)	python scripts/gen_music.py --style upbeat --out assets/audio/bgm_main.wav --tempo 132 --bars 16
Sintetizar efecto de sonido	python scripts/gen_sfx.py --preset hit --out assets/audio/sfx_hit.wav
Cálculo de compresión de audio	python scripts/compress_audio.py --dir assets/audio --check
Empaquetar atlas	python scripts/pack_atlas.py --input assets/art/ui --out-sheet assets/art/ui_atlas.png --out-data assets/art/ui_atlas.json
Validar manifiesto de assets	python scripts/validate_assets.py --manifest assets/manifest.json --root .
Inspección final pre-lanzamiento	python scripts/validate_assets.py --manifest assets/manifest.json --final --strict-license
Comprobar/verificar compilación	python scripts/build_check.py --project . → añadir --run para compilar realmente

Orden de ejecución

0. Establecer el esqueleto del proyecto

cp -r <plugin>/templates/godot4/* .        # o unity / cocos3
mkdir -p docs assets/art assets/audio doc/temp
cp <plugin>/templates/docs/*.md docs/
cp <plugin>/templates/assets-manifest.json assets/manifest.json
python scripts/omni_state.py init --root . --engine godot --platforms web,android
python scripts/omni_state.py checkpoint --root . --task "Inicio de proyecto" --next "Escribir brief"

Antes de empezar, lee .omni/active.md (si existe): contiene la tarea actual y los bloqueos de la sesión anterior; es más fiable que el chat al comprimir o cambiar de sesión.

Las tres plantillas tienen diferentes niveles de madurez. Debes informar al usuario con sinceridad:

Plantilla	Estado	Pasos manuales necesarios
godot4	Ejecutable directamente (importación probada + escena principal funciona)	Ninguno
unity	Abrible, la escena debe generarse	Menú Tools ▸ Omni ▸ Create Main Scene
cocos3	Código y configuración listos	Crear escena → asignar GameRoot al Canvas → establecer escena inicial

1. Inicio y concepto (G1)

Preguntar cinco cosas: experiencia central, prioridades de plataforma, alcance MVP, monetización y cumplimiento, assets existentes y motor. Rellenar docs/00-brief.md y docs/01-gdd.md, registrar hipótesis por verificar y decisión Go / No-Go. Estimar presupuesto e hitos según el tamaño del equipo y marcar incertidumbres.

2. gdd

Asignar a game-narrative-designer. Requisitos: valores numéricos concretos, cada uno verificable, lista separada de "requisitos para el motor". Al completar, ejecutar advance.

3. Preproducción y vertical slice (G2)

Según el motor, asignar a cocos-engineer, unity-engineer o godot-engineer. Requisitos: primero datos de perfilado, luego optimización; la configuración de compilación por plataforma debe ser específica hasta el formato de textura y la estrategia de empaquetado. Implementar un prototipo jugable temprano para validar el bucle central.

4. art (Assets definitivos)

Asignar a game-art-director para generar docs/03-art.md y assets/manifest.json, y ejecutar según la skill game-art-production:

1. Primero, la biblia de estilo docs/art-style-bible.md: un texto de anclaje de estilo fijo + paleta de colores + elementos prohibidos
2. Generar assets uno por uno: usar la herramienta de imágenes de la sesión actual o la API de IA de imágenes configurada, generar variantes según sea necesario; solicitar salida con fondo transparente cuando se necesite, cumpliendo las reglas de copia de seguridad de imágenes del proyecto. Las animaciones se generan según la skill game-animation-production como GIF o sprite sheet y se verifica el corte de fotogramas.
3. Postprocesar a especificaciones:

python scripts/process_art.py --in raw/btn_raw.png --out assets/art/ui/ui_btn_primary.png \
  --size 256x64 --mode fit --key-color "#FFFFFF" --key-tolerance 14 \
  --nine-slice 24 --check-nine

4. Registrar en el manifiesto: tier: "final" + source + license + commercial_ok + ai_generated
5. Inspección final: validate_assets.py --final --strict-license

Antes de G2, crear una vertical slice completa pero de alcance reducido, integrando programación, diseño, arte y audio en el motor objetivo; probar la calidad visual, el pipeline de assets, la compilación y el rendimiento. No planificar la producción en masa basada en un demo hasta que el slice demuestre que el enfoque es repetible y el costo aceptable. Los scripts de estado del plugin solo verifican documentos, no validan esta puerta.

5. Producción de audio

Asignar a game-audio-designer para generar docs/04-audio.md, y según la skill game-audio-production elegir una ruta:

• Ruta A (Generación por IA): priorizar el uso de herramientas de generación de audio disponibles actualmente; o usar gen_ai_audio.py con la API de ElevenLabs, consultar game-audio-production. Las claves del servicio, permisos, costos y licencias deben aclararse de antemano.
• Ruta B (8-bit, offline sin costo):

python scripts/gen_music.py --style upbeat --out assets/audio/bgm_main.wav --tempo 132 --bars 16
python scripts/gen_sfx.py --list
python scripts/gen_sfx.py --preset hit --out assets/audio/sfx_hit.wav

• Obligatorio comprimir: python scripts/compress_audio.py --dir assets/audio --bitrate 96k; si no hay ffmpeg, seguir las instrucciones del script para usar compresión en tiempo de importación del motor (Godot QOA / Unity Vorbis / Cocos mp3-ogg)
• Obligatorio documentar diferencias de plataforma: minijuegos requieren reproducción tras interacción, modo silencio de iOS, políticas de reproducción automática en Web

Producción en masa (G3) y ciclo Sprint

Solo después de G2, planificar la producción en masa según la capacidad real del vertical slice. Rellenar docs/07-production-roadmap.md; cada ciclo, seleccionar un objetivo verificable del backlog de diseño, programación, arte o audio, y usar docs/08-sprint-review.md para registrar el alcance, responsable, compilación integrada, pruebas, feedback y retrospectiva. La duración del ciclo se determina según la capacidad del equipo, normalmente 2–4 semanas, los equipos pequeños pueden ser más cortos. Cada ciclo se revisa con una versión jugable real; el trabajo fallido o no integrado se marca claramente.

6. Pruebas y pulido (G4 / G5)

Asignar a game-qa-engineer para el plan de pruebas. Después de Alpha, entrar en Beta con contenido bloqueado; por defecto, no se añaden nuevas funciones. Si es necesario añadir una función, registrar el impacto en el cronograma, el alcance de las pruebas y las puertas de etapa, y volver a evaluar. Antes de preparar Gold, es obligatorio ejecutar realmente una compilación y echar un vistazo a la pantalla:

python scripts/build_check.py --project .                            # Primero ver el comando
python scripts/build_check.py --project . --run --capture g4-beta     # Compilar + iniciar + capturar pantalla
python scripts/omni_state.py check --root . --stage qa --evidence     # Validar documentos + evidencias juntos
python scripts/omni_state.py advance --root . --to release            # Sin evidencias, se bloquea

Las capturas de pantalla se guardan en docs/qa/evidence/<nombre>/, y receipt.json registra el sha256 de los archivos cubiertos. Cualquier cambio posterior hará que esta evidencia muestre que está caducada; las capturas caducadas no cuentan como evidencia; hay que volver a capturar.

Que la compilación pase no significa que funcione, y que funcione no significa que se vea bien: texto comprimido fuera de los bloques de color, paneles desbordados, elementos que no aparecen; solo se detectan al mirar la imagen. Unity y Cocos no tienen capacidad integrada de captura desatendida; el script devolverá honestamente NOT ASSESSED; en ese caso, usa --capture-cmd para dar un comando, o indica claramente "no se ha visto la pantalla". No se debe dar por aprobado. Si realmente es necesario avanzar, se puede usar --no-evidence, pero al entregar se debe indicar que no se ha visto.

Si la compilación falla, entrega el registro tal cual al ingeniero del motor correspondiente, no adivines. Registrar las pruebas reales, la compatibilidad de plataforma y las evidencias del paquete candidato; invitar al responsable a revisar antes de confirmar Gold / Release. El advance de documentos no pasa automáticamente Alpha, Beta, Gold ni firma de lanzamiento.

Usar docs/09-milestones.md para registrar responsables, rutas de evidencia y decisiones de G1–G5. Alpha = funcionalidad completa, Beta = contenido bloqueado, Gold = candidato de lanzamiento para la plataforma objetivo aprobado tras revisión; estos estados requieren confirmación manual basada en evidencias reales, no pueden inferirse de las fases documentales.

7. Lanzamiento y operación

Asignar a game-release-operator para generar docs/06-release.md. Todos los números de plataforma deben incluir "consulte la versión oficial más reciente" y un enlace de verificación.

Después del lanzamiento, registrar problemas en producción, métricas de fallos/negocio, feedback de jugadores y estado de hotfixes; retroalimentar al backlog y la hoja de ruta de la siguiente versión. Iniciar el siguiente ciclo Sprint según sea necesario; done solo indica que los artefactos de este ciclo están completos, no que se detenga la operación.

Al entregar al usuario

## Fase actual
Fase en state.json + estado de puerta de etapa

## Artefactos producidos
Listado de docs/ y assets/, indicando cuántos siguen siendo provisionales

## Compilación y evidencias
Resultado de build_check: éxito / fallo / no ejecutado; si hay capturas, qué archivos cubren, si están caducadas

## Brechas reales pendientes
Indicar claramente qué necesita trabajo humano

Reglas de hierro

1. No saltar fases: advance lo bloqueará; no lo evites; evitarlo significa entregar algo no fiable
2. Los documentos no son el final: después de la fase tech deben generarse realmente archivos de código y recursos; solo entregar documentos no cuenta como completado
3. La compilación debe ejecutarse realmente: en la fase qa, sin resultado de compilación no se pasa a release; el script de estado no lo bloquea automáticamente, requiere verificación manual
4. Draft no cuenta como completado: los recursos con tier: "draft" no pueden incluirse en el lanzamiento; la inspección final --final los bloqueará. Al entregar, se debe indicar cuántos draft quedan
5. Cifras con origen: los límites de tamaño de paquete y las capacidades del motor deben incluir versión y método de verificación
6. Cada ciclo Sprint entrega una compilación jugable: el número de tareas completadas no puede sustituir a la compilación, las pruebas y la revisión
7. Las puertas de etapa se basan en evidencias de revisión: omni_state.py solo verifica títulos de documentos y TODOs; no puede validar automáticamente la jugabilidad, la compilación, los dispositivos ni las aprobaciones de lanzamiento
8. Los artefactos tienen prioridad sobre la narrativa: si un rol asignado afirma haber escrito un archivo, se verifica que esa ruta exista. Si no existe, es PHASE FAILED — no se avanza, no se resume como completado. Un párrafo fluido de "voy a..." no es evidencia; los archivos en el disco lo son
9. Después de qa debe haber capturas de pantalla: sin capturas válidas en docs/qa/evidence/, no se pasa a release; advance lo bloqueará. NOT ASSESSED no es aprobado

Lo que este pipeline NO puede hacer

• Modelos 3D y animación esquelética: este pipeline se centra en 2D; los fotogramas generados por IA deben revisarse y posiblemente retocarse.
• Música y efectos de sonido por IA: requiere herramientas de generación disponibles actualmente o servicios externos con permisos; la síntesis procedural no equivale a generación por IA.
• Fuentes comerciales: solo se pueden usar fuentes de código abierto OFL; las fuentes comerciales requieren que el usuario adquiera la licencia.
• Firmar, publicar o aprobar en tu nombre: solo se puede proporcionar listas y cronogramas, no realizar acciones en los paneles de administración.
• Verificación de compatibilidad en dispositivos reales: requiere dispositivos reales.
• Garantizar que el código no tenga bugs: compilar con éxito no significa funcionalidad correcta, y funcionalidad correcta no significa que sea divertido.