huayuehua15-netizen/aaa-game-gdd

Skill de Documentos de Desarrollo de Juegos de Nivel AAA (GDD)

Convención de rutas: Todos los scripts/, references/, assets/ en este archivo son relativos al directorio donde se encuentra este SKILL.md. Antes de ejecutar python scripts/new_gdd.py, localice primero ese directorio (Cursor/Codex lo instala en <proyecto>/skills/game-dev/aaa-game-gdd/ mediante install.ps1). Si no está seguro, busque primero la ruta absoluta de este SKILL.md y luego use la ruta absoluta para llamar al script; escribir la ruta relativa directamente desde la raíz del proyecto provocará un error file-not-found.

Qué hace esta skill

Convierte "tengo una idea de juego" en un conjunto completo de documentos que permite a un equipo desarrollar directamente un juego listo para publicar en Steam y comparable a los AAA. La entrega principal es un conjunto de documentos Markdown en chino, estructurados, cuantificables y verificables (GDD), no un documento de diseño genérico.

Cada documento producido debe cumplir tres reglas de hierro:

1. Desarrollable: Los desarrolladores no necesitan preguntar "¿qué hacer exactamente?, ¿qué tamaño?, ¿cuál es el estándar?". Todo lo cuantificable debe tener valores fijos (número de caras, fotogramas, duración, resolución, frecuencia, latencia, condiciones de activación).
2. Verificable: Cada activo, sistema y escenario tiene una lista de verificación de Definición de Hecho (Definition of Done) que se puede marcar al completar.
3. Consistente: Todos los documentos comparten los mismos pilares de visión, biblia de arte, convenciones de nomenclatura y presupuesto de rendimiento; los documentos se referencian entre sí con números y no se permite la contradicción.

Mapa de documentos (referencias léase bajo demanda)

No lea todos los documentos de referencia de una sola vez. Primero determine qué tipo de documento necesita el usuario según la tabla, y luego lea solo el correspondiente. La estructura de cada referencia es: qué problema resuelve → cuándo escribirla → estructura del capítulo → cómo escribir cada capítulo (con estándares cuantificables) → ejemplos buenos/malos → lista de verificación de definición de hecho.

Documento	Cuándo leer esta referencia	Plantilla correspondiente (assets/templates)
00 Visión general del sistema de documentos	Nuevo proyecto, necesita determinar la lista de documentos y el plan de fases	README.md
01 Visión y Pitch	El proyecto tiene una idea, necesita una página para explicar el juego y presentarlo externamente	01-vision-pitch.md
02 Biblia de arte	Definir el estilo artístico, unificar la estética del equipo, crear requisitos de arte	02-art-bible.md
03 Escenarios y niveles	Escribir descripciones de escenarios, flujo de niveles, trayectorias, encuentros, narrativa ambiental	03-scene-level.md, scene-sheet.md, level-sheet.md
04 Sistemas de juego	Diseñar el ciclo principal, combate, progresión, economía, tablas de valores	04-gameplay-systems.md, system-sheet.md
05 Narrativa y diálogos	Escribir esquema de la historia, capítulos, ramificaciones, guiones de diálogo, doblaje	05-narrative-dialogue.md, dialogue-sheet.md
06 Interacción y UI/UX	Definir controles, matriz de interacción, sensación del juego, HUD, menús, accesibilidad	06-interaction-uiux.md
07 Especificaciones de personajes	Diseño, apariencia, conjunto de acciones, IA, valores de personajes principales/enemigos/NPC	07-character-spec.md, character-sheet.md
08 Especificaciones de modelado de objetos	Modelado, texturizado, LOD, nomenclatura y entrega de objetos/armas/activos ambientales	08-prop-modeling.md, prop-sheet.md
09 Especificaciones de animación	Animación de esqueleto 3D, máquina de estados de animación, cinemáticas, animación de sprites 2D	09-animation-spec.md, animation-sheet.md
10 Diseño de audio	Música, efectos de sonido, doblaje, música dinámica, sonoridad del bus	10-audio-spec.md
11 Tecnología y rendimiento	Selección de motor, pipeline de renderizado, objetivos de fotogramas/memoria/tamaño de paquete, plataformas	11-tech-performance.md
12 Calidad AAA y verificación para Steam	Puertas de fase, plan de QA, tienda Steam y publicación, puntuación comparativa AAA	12-steam-qa-checklist.md

Flujo de trabajo

Flujo A: Nuevo proyecto (de la idea al sistema documental completo)

1. Aclarar la información mínima necesaria (hacer preguntas al usuario de una sola vez, máximo 4): tipo de juego y mecánica principal en una frase, motor (Unity/Unreal/Godot/indefinido), plataforma y fotogramas objetivo (PC 60fps? Steam Deck?), tendencia de estilo artístico. Después de preguntar, se puede comenzar a trabajar; no preguntar repetidamente para obtener toda la información; los elementos desconocidos se marcan explícitamente con 【Pendiente de confirmar】 en el documento.
2. Ejecutar el andamio: python scripts/new_gdd.py init --name "Nombre del juego" --out <directorio de salida> --engine <motor confirmado en el paso 1>, genera un árbol completo de documentos GDD. --engine debe usar la respuesta del paso 1, no rellenar siempre "unity" — esto determinará realmente los ejes, nombres de colisiones, navegación y métricas de activos de datos en los documentos.
3. Escribir documentos en orden de fases (ver "Puertas de fase" más abajo): primero leer la referencia correspondiente, luego completar la plantilla. Orden: 01 Visión → 02 Biblia de arte + 11 Presupuesto técnico → 04 Sistema de juego principal → 07/08/09/06 Especificaciones → 03/05 Contenido → 12 Verificación.
4. Para cada escenario/personaje/objeto/animación/diálogo/sistema usar scripts/new_gdd.py sheet para generar una página individual, colocarla en el subdirectorio correspondiente del GDD; en el documento principal solo se pone una tabla de índice, no se apilan cientos de activos en un solo archivo.
5. Pasar los controles de calidad: al final de cada fase, usar la tabla de puertas de 12-steam-qa-checklist.md para revisar cada elemento; no pasar a la siguiente fase si no se cumple.

Flujo B: Documento único (el usuario solo necesita un tipo de documento)

Confirmar el objeto y propósito → Leer la referencia correspondiente → Copiar la plantilla correspondiente y rellenarla → Usar la "Definición de hecho" al final de la referencia para autoevaluación → Entregar. Cuando el usuario solo dice "escríbeme una escena", preguntar primero el nombre de la escena/su posición en el flujo/evento central (todo de una vez), y luego producir directamente una scene-sheet completa, no solo una plantilla vacía.

Escenario vs. Nivel: por defecto, solo se produce lo que el usuario pide. La referencia references/03 dice "el escenario es espacio, el nivel es tiempo, escríbanse por separado", refiriéndose a la división del trabajo cuando se necesitan ambos, no a que cada vez que se escribe una escena se deba adjuntar una página de nivel.

La división es estricta:

• Página de escenario (SC_) = qué ofrece este espacio: terreno, líneas de visión, cobertura, diferencias de altura, puntos de escape, lugares para esconderse, restricciones espaciales para los enemigos (§7) y zonas de activación TZ_ (§4).
• Página de nivel (LV_) = en qué orden experimenta el jugador qué: tabla de beats (con número de evento EV_), ritmo, consecuencias del encuentro, puntos de control.

Por lo tanto:

• El usuario solo quiere escenario → escribir solo scene-sheet.md, no escribir el orden; si realmente no se produce la página de nivel, añadir una línea en el §7 "Orden de experiencia (resumido)".
• Si el usuario quiere flujo de nivel, o el escenario tiene múltiples fases de ritmo → entonces producir level-sheet.md, ambas referenciándose mutuamente con TZ_ ↔ EV_.
• No producir por iniciativa propia dos documentos solo porque la referencia 03 dice "escríbanse por separado", eso inflaría una solicitud simple 2-3 veces.

Leer un ejemplo completo antes de rellenar — cada tipo de página individual tiene un ejemplo completo, lea directamente el correspondiente según el tipo que va a escribir:

Tipo de página	Ejemplo	Qué debe imitarse principalmente
Escenario (lineal/terror)	assets/examples/SC_01_外科楼二层走廊_示例.md	§7 Oferta espacial = ocultación visual y "primero ver, luego contactar"; §10 Centrarse en percepción y ritmo
Escenario (abierto/JEFE)	assets/examples/SC_07_断桥瞭望台_示例.md	§7 Oferta espacial = distancia ajustable / interrupción de línea de visión / riesgo apostable; §10 Centrarse en resolubilidad del combate
Nivel	assets/examples/LV_01_走廊初遇_示例.md	Cómo conciliar la tabla de beats con TZ_; cómo la curva de intensidad y los puntos de enseñanza no necesitan ventanas emergentes
Personaje (enemigo)	assets/examples/EN_01_缝合者_示例.md	§6 Máquina de estados + diferencia de velocidad, por qué escribir "se puede escapar"; §7 Cómo se calcula la duración del combate
Objeto	assets/examples/PR_017_缺轮轮椅_示例.md	§5 Valores de especificaciones técnicas; §7 En DoD, cómo escribir "intencionalmente no hecho"
Animación	assets/examples/AN_EN01_Slash_01_示例.md	§2 Intervalo de fotogramas en tres partes; §3 Puntos de evento (el sonido de aviso es el límite de equidad)
Diálogo/Cinemática	assets/examples/DL_07_护士长录音_示例.md	Cómo definir ID de línea/duración/conformidad de subtítulos/reproducción interrumpida y reanudada
Sistema	assets/examples/SYS_04_抓取挣脱_示例.md	§4 La tabla de parámetros debe incluir "intención de diseño"; §5 No omitir ningún borde

Todos los ejemplos deben alcanzar este nivel de granularidad (cada elemento con números específicos, identificadores, contenido asignable). Nota: las casillas de verificación en los ejemplos son registros de verificación después de la finalización (incluyen número real de caras, fecha de revisión, decisiones de diseño rechazadas), no el formato de relleno antes de comenzar; en la etapa v0.1, dejar los espacios en blanco que correspondan, no inventar números que parezcan "medidos". §10 Riesgos de diseño e hipótesis a verificar es la única sección donde está permitido y debería no tener números.

Flujo C: Revisión de documentos/ideas existentes

Usar la "Tabla de puntuación en 10 dimensiones AAA" de 12-steam-qa-checklist.md para puntuar cada dimensión (1-10, con evidencia), enumerar los defectos graves que bloquean la publicación, la lista de documentos faltantes y sugerencias de modificación ordenadas por gravedad. La puntuación debe citar el texto original del documento o los elementos faltantes; prohibido hacer evaluaciones genéricas.

Puertas de fase (Stage Gates)

Fase	Documentos obligatorios	Puerta (no pasar a la siguiente fase si no se cumple)
Concepto	01 Visión, 04 Esqueleto del sistema de juego principal	La diversión principal tiene verificación en papel/prototipo graybox; los 3 pilares principales aprobados por todos
Rebanada vertical	02, 06, 11 + al menos 1 página de muestra de cada tipo (escenario/personaje/objeto/animación/diálogo)	Flujo de 10-15 minutos alcanza la calidad final esperada; todos los sistemas principales funcionan; se cumple el presupuesto de rendimiento
Producción en masa	Todos los documentos principales + todas las páginas individuales de activos	Cada página de activo se puede asignar directamente; se puede programar productividad e hitos
Alpha	Todo el contenido	Feature Complete: se puede terminar el juego desde el principio, sin sistemas placeholder
Beta	Lo mismo + 12 Tabla de verificación	Content Complete; cero bugs de tipo S/A; completar el juego completo × 3 configuraciones
RC/Publicación	Todos los elementos de la lista de Steam en 12 marcados	Tienda, verificación Deck, localización, clasificación, compatibilidad de guardado todo aprobado

Script de andamio

# Inicializar el árbol completo de documentos GDD (crea <Nombre del juego>_GDD/ en el directorio de salida)
python scripts/new_gdd.py init --name "Nombre del juego" --out "D:/MyGame" --engine unity
#   --engine: unity | unreal | godot | agnostic (predeterminado)
#             ★ Esto no es decorativo: la elección determinará el formato de intercambio / ejes / nomenclatura de colisiones / navegación / activos de datos / métrica LOD del motor
#   --genre: opcional, descripción del tipo de juego, se escribirá en el documento de visión
#   --dimension: 3d (predeterminado) | 2d (crea subdirectorios sprites/ tilesets/ adicionales)

# Generar página individual para un solo objeto (se coloca automáticamente en el subdirectorio correspondiente)
python scripts/new_gdd.py sheet --type scene --name "Hospital abandonado" --out "D:/MyGame/Nombre_del_juego_GDD"
#   --type: scene | level | character | prop | animation | dialogue | system | sprite | tileset
#   --subtype: para character usar player/enemy/npc (CH/EN/NPC); para prop usar item/weapon (PR/WP)
#   Ejemplo: sheet --type character --subtype enemy --name "Cosificador" → characters/EN_01_Cosificador.md
#   Ejemplo: sheet --type sprite --name "HeroIdle" → sprites/SPR_01_HeroIdle.md

init también admite --dimension 2d: crea subdirectorios adicionales sprites/ y tilesets/ (para proyectos 2D).

El script reemplaza automáticamente los placeholders {{GAME_NAME}}, {{DATE}}, {{ENGINE}}. Si el script no está disponible, copiar manualmente las plantillas de assets/templates/.

Normas generales de escritura

• Encabezado del documento: Cada documento debe comenzar con: número de documento, versión, estado (Borrador/En revisión/Bloqueado), fecha de última actualización, responsable, números de documentos relacionados. Las páginas de activos individuales también deben incluir el nombre del recurso dentro del motor (ej. SM_Prop_HospitalWheelchair_01).
• Priorizar la cuantificación: Prohibido usar descripciones no verificables como "buena sensación", "imágenes hermosas", "enemigo muy fuerte". Escribir "desde que se presiona el ataque hasta que se aplica el daño: 8 frames (0.13s a 60fps)", "HP del enemigo 120, DPS del jugador con mejora máxima 45, duración esperada del combate 35-45s".
• Si no está seguro, márquelo: Los valores desconocidos escriben 【Pendiente de confirmar: motivo/responsable/plazo】, prohibido inventar números y fingir certeza; los valores de experiencia de la industria pueden adoptarse directamente y marcarse en el documento como "Valor predeterminado de la industria, ajustar después de la primera prueba".
• Requisitos de imágenes y texto: Los escenarios, niveles y UI deben incluir un diagrama de diseño (plano ASCII, diagrama de flujo/estado Mermaid, o referencia al número del concepto artístico); las máquinas de estados, árboles de diálogo y flujos de menú deben dibujarse con Mermaid; los parámetros y listas se presentan en tablas.
• Cada documento debe tener DoD: Al final, lista de verificación de definición de hecho (con casillas - [ ]), que es el único criterio para la entrega y verificación.
• Idioma: Texto principal en chino; nombres propios, API del motor, nombres de recursos en inglés; los guiones de diálogo deben tener campos reservados para inglés/otros idiomas.
• Modificar documentos con control de versiones: Después de bloquear un documento, las modificaciones deben registrarse al final en un registro de cambios: versión, fecha, qué se cambió.

Requisitos de entrega

• La entrega son archivos Markdown colocados en el directorio del proyecto del usuario (árbol de directorios del andamio + documentos rellenados), no un resumen en el chat.
• Después de cada entrega, indique al usuario: qué documento escribir a continuación, qué 【Pendiente de confirmar】 necesita que él decida.
• El estándar de calidad del documento es: "un artista/programador externo recién incorporado, leyendo solo la página individual correspondiente, puede producir activos calificados de forma independiente".