CommunityProgramación y desarrollogithub.com

Juegos 3D fotorrealistas desde código

Procedimiento para convertir una escena 3D generada por código en un juego corto y jugable que se perciba como una fotografía. Cubre iluminación, materiales, colisionadores, el bucle de juego y un arnés de verificación ejecutable.

¿Qué es Juegos 3D fotorrealistas desde código?

Esta habilidad proporciona un procedimiento sistemático y agnóstico a herramientas para construir juegos 3D fotorrealistas y jugables íntegramente desde código, dirigido a agentes de IA como Claude Code, Cursor o Codex. Su objetivo es garantizar que el resultado sea un juego completo (con menú, ajustes, persistencia, audio, HUD, objetivos y bucles de victoria/derrota), no solo una demo técnica o una escena estática. El procedimiento se basa en ocho compuertas ejecutables (renderizado, censo, colisiones, luces, playtest, producto, móvil y aspecto visual) que el agente debe verificar secuencialmente, priorizando siempre el producto funcional sobre el acabado visual. Incluye un arnés opcional en Node.js/Python para automatizar las comprobaciones, y está diseñado para que modelos de bajo costo (como DeepSeek V4.1 Flash) puedan producir resultados sólidos siguiendo reglas estrictas: no diseñar arquitectura desde cero, rellenar tablas predefinidas, hacer un solo cambio por ronda y nunca autoevaluarse (la compuerta siempre tiene la razón). La habilidad detalla contratos de página, plantillas JavaScript para la capa de producto y un flujo de trabajo con pasos como redactar un brief de dirección de arte, gestionar la iluminación y los materiales, y realizar pruebas de juego en móvil.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NorwinYu/photoreal-game/tree/HEAD

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Juegos 3D fotorrealistas desde código?

Un procedimiento para convertir una escena 3D generada por código en un juego corto y jugable que se perciba como una fotografía. El objetivo es un juego, no una imagen estática, una demo técnica o un paseo guiado: un jugador con un verbo, un sistema que responde, una forma de ganar y una forma de perder.

Nada de esto asume un género. El sujeto decide el verbo: un patio de contenedores sugiere transportar una carga antes de que termine el turno; un taller sugiere reparar una máquina; una escalera sugiere salir sin ser visto. Los shooters son una instanciación entre muchas, y el mismo procedimiento los produce solo cuando el sujeto lo pide.

El procedimiento es agnóstico a herramientas. Asume un agente que puede editar archivos, ejecutar comandos e inspeccionar imágenes. Nada de lo siguiente depende de un motor, una versión de librería o un producto de proveedor específico.

Origen y relevancia. Esta habilidad existe para responder a una pregunta planteada por Saltline — un shooter de navegador en un solo archivo de 1.423.668 bytes, sin activos externos, creado con Claude Fable 5.2. La parte interesante no fue el tamaño; fue que el modelo escribió el generador. Esta habilidad empaqueta esa disciplina de producción en compuertas ejecutables, de modo que un modelo de bajo costo (como DeepSeek V4.1 Flash) pueda mantenerse en el mismo estándar. El resultado no es el mismo juego; es la misma disciplina — y la evidencia queda registrada en los casos de estudio del repositorio.

El arnés incluido es opcional pero recomendado: hace que las compuertas sean ejecutables en lugar de aspiracionales. Necesita Node.js 22+, Python 3.10+ con Pillow y un binario de Chrome/Chromium (CHROME_PATH si no está en una ubicación estándar). El texto de la habilidad en sí no tiene dependencias.

Cómo ejecutar esto con un modelo de bajo costo

La habilidad está escrita para que un modelo débil pueda ejecutarla: todo juicio importante se delega a una comprobación, y el trabajo del modelo es rellenar tablas y aplicar la corrección mejor clasificada. Siga estas reglas al pie de la letra.

  1. No diseñe arquitectura. Comience desde un esqueleto que ya tenga: el arnés de renderizado, el contrato de la página (__READY, __STATS, __SCENE, __AUDIT, __COLLIDERS, __BOUNDS, __TESTMOVE, __TEST, __PRODUCT), la cadena de postprocesado, un shell de juego terminado (título, ajustes, pausa, guardar, táctil, marcadores HUD) y una tabla de kit vacía. Cópielo, luego rellene las tablas. La arquitectura inventada por ejecución es donde fallan los modelos débiles.
  2. Rellene, no invente. Los productos de trabajo son seis tablas: producto (shell + contenido), dirección de arte, kit (dimensiones + piezas + calcomanías), superficies (albedo/rugosidad/normal), luces (posición + luminaria) y el bucle (verbo/sistema/retroalimentación/fallo/prueba).
  3. Primero el producto, luego el aspecto visual. producto → censo → luces → colisiones → prueba de juego → móvil → aspecto. Un fotograma que es hermoso pero no tiene ajustes, ni un segundo rol de enemigo, ni marcadores de objetivo, ni una ruta táctil, no es una ronda terminada.
  4. Un cambio por ronda, luego ejecutar todas las compuertas. Una ronda solo es válida si ninguna compuerta retrocede. Una ganancia visual que rompe el producto o el bucle se revierte.
  5. Nunca se autoevalúe. Si una compuerta está en desacuerdo con su opinión, la compuerta gana. Si una compuerta es incorrecta, corrija la compuerta con un contraejemplo — nunca la omita.
  6. Deténgase en el presupuesto o en la meseta, lo que ocurra primero, e informe la peor cámara y la lista de compuertas fallidas.

Un modelo que sigue esas seis reglas produce resultados comparables a una fracción del costo; un modelo que se salta la regla 5 produce regresiones que parecen plausibles.

Contrato de entrega

Una ejecución está completa solo cuando estos elementos existen y todas las compuertas están en verde:

ArtefactoComprobación
un HTML autocontenido, sin solicitudes de redcargar con la red desactivada
contrato de página expuesto (__READY, __STATS, __SCENE, __AUDIT, __COLLIDERS, __BOUNDS, __TESTMOVE, __TEST, __GAME, __PRODUCT)el arnés los lee
shell de juego terminadomenú, ajustes, pausa, guardar, táctil, jerarquía HUD, fin/reinicio
amplitud de contenido≥2 roles de enemigo/interactuable, ≥2 herramientas, ≥1 cadena de objetivos, ≥3 tiempos
informe de censocobertura = 100%, cero fallos
auditoría de lucescada luz anclada a una luminaria
informe de colisionescero penetraciones, cero fuera de límites, paridad de colisionadores 100%
prueba de juegobucle completable, ruta de fallo alcanzable, reinicio funciona
informe móvildiseño 390×844, sin desbordamiento horizontal, controles táctiles presentes
informe de caja en 3–6 objetos del sujetocada métrica >= 0.8 de la referencia
puntuación de fotogramainformada, pero nunca utilizada para anular una compuerta

Contrato de producto terminado

Un fotograma jugable no es un juego terminado. Las compuertas del bucle protegen el comportamiento; las compuertas del producto protegen el shell, la amplitud del contenido y la primera impresión. Declare lo siguiente en la página para que harness/product.mjs pueda verificarlo sin leer la mente del modelo.

ArtefactoMínimo
Pantallasmenú, jugando, pausa, ajustes, perdido, ganado
Pantalla de títulovisible al cargar; HUD oculto; título, premisa, inicio, ajustes/controles
Ajustessensibilidad, volumen, FOV, invertir-Y, calidad (o un conjunto equivalente)
Persistenciauna clave sobrevive a la recarga (mejor puntuación/progreso/ajustes)
Entradateclado + ratón + táctil; puntería alternativa cuando falla el bloqueo del puntero
Objetivos≥1 cadena con ≥3 tiempos y marcadores mundiales/brújula
Roles≥2 roles de enemigo/obstáculo/interactuable, no uno recoloreado
Herramientas≥2: un verbo principal y uno secundario (arma/herramienta/habilidad)
HUDobjetivo+progreso, supervivencia, arma/municiones, indicador de contexto, brújula/marcadores, subtítulos
Audiosilencio + ≥6 eventos de cambio de estado
Cámarascámara principal y cámaras fijas de primer plano en __PRODUCT.cameras
Rendimientopresupuestos declarados para llamadas/triángulos/luces, medidos después del inicio
Móvil390×844 sin desbordamiento horizontal; controles táctiles alcanzables

Presupuesto de contenido para una porción vertical

Rellene esto antes de cualquier paso artístico. Una porción vertical es una sesión de 3 a 8 minutos con una cadena de objetivos completa, dos roles, un sistema característico y un shell diseñado. Es más pequeña que un demo reel y más grande que una demo técnica.

ElementoPorción verticalJuego pequeño terminado
Objetivos1 cadena, 3 tiempos1–3 cadenas, 5–8 tiempos
Roles de enemigo/interactuable23–5 + un clímax
Armas/herramientas2 (principal + secundaria)3–5
Verbos del jugadormoverse, apuntar, disparar, recargar+ agacharse/saltar/interactuar/habilidad
Mundouna ubicación, 3 capas de profundidad2–3 espacios conectados
Shelltítulo, pausa, ajustes, fin+ guardar, calidad, táctil
Sesión3–8 min10–30 min

El manifiesto es una afirmación; la compuerta verifica el comportamiento del DOM y los recuentos declarados. No declare lo que la página no hace.

window.__PRODUCT = {
  title: { name: 'Título del juego', start: '#start', hud: '#hud', hudHiddenOnTitle: true },
  screens: ['menu', 'playing', 'paused', 'settings', 'lost', 'won'],
  ui: { start: '#start', hud: '#hud', pause: '#pause', settings: '#settings', end: '#end', touch: '#touch' },
  settings: ['sensitivity', 'volume', 'fov', 'invertY', 'quality'],
  persistence: ['game.best'],
  input: { keyboard: true, mouse: true, touch: true },
  content: {
    objectives: [{ id: 'objective-1', title: 'Objetivo', steps: 3 }],
    roles: ['role-a', 'role-b'],
    tools: ['tool-a', 'tool-b'],
    beats: ['intro', 'contact', 'mid', 'climax', 'win'],
  },
  hud: ['objective', 'compass', 'health', 'ammo', 'prompt', 'subtitles'],
  audio: { events: 10, mute: true },
  perf: { maxCalls: 700, maxTris: 400000, maxLights: 14 },
  cameras: [
    { name: 'hero', cam: [0.5, 1.7, 10, -2.6, 1.3, -10] },
    { name: 'close', cam: [-6.4, 1.4, 5.2, -9.9, 1.0, 2.2] },
  ],
  test: { start: 'start', pause: 'pause', resume: 'resume', settings: 'openSettings', save: 'save' },
};

Acciones __TEST estándar (se permiten acciones adicionales): start, pause, resume, openSettings, closeSettings, save, state. Deben funcionar sin bloqueo del puntero y devolver una instantánea compatible con JSON. La pantalla de título debe ocultar el HUD; al iniciar debe mostrarlo; las pantallas de ajustes, pausa y fin deben ser inspeccionables desde el DOM.

Cuándo usar

  • Una escena es geométricamente correcta pero se percibe como plana, plástica o "generada".
  • Un renderizado debe coincidir con una fotografía de referencia, un concepto o una dirección de arte.
  • La iluminación, los materiales o la composición necesitan mejorarse de forma controlada.
  • Una generación larga necesita mantenerse coherente a lo largo de muchas iteraciones.

Cuándo no usar

  • Resultados deliberadamente estilizados (sombreado plano, cel, diagramático, similar a una interfaz de usuario). Esos necesitan una abstracción coherente, no plausibilidad física. El procedimiento se transfiere, pero reemplace el perfil fotorrealista y la compuerta de aspecto visual por uno coherente con el estilo; una escena estilizada medida contra un perfil fotográfico pierde por construcción, no por calidad.
  • Tareas de precisión (CAD, dibujos de ingeniería) donde la legibilidad supera al realismo.
  • Escenas sin cámara: visualización de datos, gráficos de nodos, UI.

Modelo del problema

El realismo percibido proviene de cinco palancas. Aplíquelas en este orden; el retorno del esfuerzo disminuye drásticamente a medida que se baja en la lista.

  1. Luz — una única fuente dominante con una dirección, color y elevación definidos, más un entorno para reflejos y relleno.
  2. Materiales — variación en rugosidad, normal y suciedad, en lugar de solo color.
  3. Composición y densidad — objetos en varias escalas y profundidades, con un punto focal claro e indicaciones de escala legibles.
  4. Formación de la imagen — anti-aliasing, mapeo de tonos, bloom, grano, viñeta.
  5. Detalle geométrico — el último recurso, y solo donde sobrevive a varios píxeles en pantalla.

Dos consecuencias que vale la pena establecer explícitamente:

  • El detalle más pequeño de aproximadamente dos píxeles es eliminado por el anti-aliasing y no contribuye a la imagen. Añadir recuento de polígonos a esa escala es un desperdicio.
  • Una escena puede tener una exposición correcta y aun así verse vacía. El vacío es un problema de densidad, no de gradación.

Tres consecuencias más para un juego terminado:

  • Un fotograma es necesario pero no suficiente. La capa del producto — arte clave del título, ajustes, pausa, guardar, táctil, marcadores de objetivo, radio/subtítulos, amplitud de contenido — se juzga antes de que el jugador note la iluminación.
  • Las cinco palancas son independientes del sujeto. Se aplican a un puerto diurno, un interior brillante, un campo nevado o una arena estilizada. Noche/lluvia/niebla son un escenario, no el predeterminado.
  • La puntuación del fotograma es una brújula para un aspecto de referencia. No puede distinguir un juego terminado de una demo hermosa.

Flujo de trabajo

Cada paso tiene una salida. No comience el siguiente paso sin ella.

Paso 1 — Hacer observable el renderizado (recomendado antes de cualquier trabajo de escena)

Produzca una forma repetible de capturar un fotograma e inspeccionarlo.

Salida: un comando que devuelve una imagen y, idealmente, algunos números.

Si su entorno ya tiene una herramienta de captura de pantalla, úsela. Si no, construya la más pequeña que funcione:

  • Lance un navegador sin cabeza contra un servidor estático local.
  • Espere una señal de disponibilidad de la página (consulte el contrato a continuación), luego capture.
  • Opcionalmente, calcule estadísticas de imagen: histograma de exposición, recorte, recuento de colores, densidad de bordes.

Contrato de página que mantiene las capturas deterministas:

window.__READY = true;                      // establecido después de unos pocos fotogramas renderizados
window.__STATS = { calls, triangles };      // contadores de renderizador opcionales
// parámetros de consulta opcionales
// ?shot=1            ocultar UI
// ?cam=x,y,z,tx,ty,tz cámara fija
// ?seed=N            semilla aleatoria fija

Reglas:

  • Cámara fija, semilla fija, viewport fijo para cada comparación.
  • Almacene cada captura bajo un nombre versionado; nunca sobrescriba la anterior.
  • Si no hay métricas disponibles, conserve las imágenes y compárelas lado a lado. La comparación visual es suficiente; las métricas solo hacen que la atribución sea más rápida.

Paso 2 — Escribir un brief de dirección de arte

Salida: una tabla corta. Cada fila debe ser lo suficientemente concreta para implementar.

DecisiónContenido
Sujetode qué trata el fotograma, a qué escala
Hora y climadetermina niebla, fuerza de reflejo, contraste
Luz clavedirección, elevación, temperatura de color, intensidad
Cielo y ambientecolor del relleno de sombra
Familia de materialesqué superficies existen, qué tan rugosas, qué tan mojadas
Punto focalen qué debe posarse el ojo primero
Restriccionesqué no debe aparecer (ej. blanco puro, suelo plano, cielo despejado)

Orientación:

  • Elija una historia de luz dominante. Las fuentes adicionales son relleno, rebote o prácticos, y deben estar subordinadas.
  • Restrinja el sujeto antes de añadir detalle. Las condiciones que reducen la complejidad visible — noche, lluvia, niebla, polvo, contraluz, entornos industriales o interiores — son elecciones legítimas y efectivas, no atajos.
  • Elija una elevación clave deliberadamente. La longitud de la sombra escala como altura / tan(elevación): una clave baja produce sombras largas que pueden poner todo el primer plano en la sombra, lo que se percibe como "sin sombras". Las elevaciones medias (aproximadamente 20–30°) suelen dar tanto forma como un área iluminada para contrastar.
  • Elija el escenario de iluminación antes que el kit. No use por defecto noche, lluvia o interiores industriales porque ocultan detalles faltantes. La noche es una opción; un amanecer con contraluz o un interior brillante es más difícil y a menudo más convincente.
EscenarioClaveRelleno / IBLAireMaterial característico
Noche industrialclave fría media-baja, prácticosentorno de cielo, charcos cálidosexponencial, color de cielosuelo mojado, luminarias emisivas
Luz diurna nubladaclave de cielo amplia, 35–60°IBL fuerteperspectiva aérea finahormigón mate, charcos
Hora dorada / contraluzclave cálida baja detrás del sujetorelleno de cielo fríoniebla larga, bordeasfalto mojado, vidrio, metal
Mediodía despejadoclave alta, sombras durasrelleno de cielo + rebotemínimoarena, piedra, pintura
Interiores con prácticosventana + algunas fuentes cálidasentorno de ventana/cielorayos de luz, polvomadera, tela, metal
Subterráneo / luz artificialprácticos + emisivosambiente bajovolumétricohormigón mojado, señales

Una escena con contraluz no es "más fácil": expone reflejos recortados, dominantes de color y siluetas débiles. Corrija la exposición y la caída de los reflejos antes de proceder.

Paso 3 — Construir el kit

Salida: una tabla de dimensiones, piezas, calcomanías, horneado. La guía completa está en rules/kit.md.

Paso 4 — Construir superficies

Salida: tabla de superficies con valores de albedo, rugosidad y normal. La guía completa está en rules/surface.md.

Paso 5 — Construir luces

Salida: tabla de luces con posición, intensidad, temperatura y luminaria. La guía completa está en rules/light.md.

Paso 6 — Construir el bucle

Salida: tabla del bucle con verbo, sistema, retroalimentación, fallo, prueba. La guía completa está en rules/loop.md.

Compuertas (del arnés o de procedimiento)

Cada compuerta se ejecuta en orden y detiene la ronda si falla.

Compuerta de producto

  • La página expone __PRODUCT con los campos requeridos.
  • Cada pantalla declarada existe en el DOM y alterna visibilidad.
  • Los botones de inicio, pausa y reinicio funcionan.
  • El HUD se oculta en el título y se muestra al jugar.
  • La persistencia sobrevive a la recarga.

Compuerta de censo

  • __SCENE devuelve una lista de objetos renderizados con identificador único, tipo (malla/luz/cámara), posición, orientación y estado de visibilidad.
  • La cobertura es la proporción de objetos de escena mencionados en el censo de arte. Debe ser del 100%.

Compuerta de luces

  • Cada luz en __SCENE tiene un padre luminaria declarado en __AUDIT.
  • Las luminarias son objetos renderizados (no luces fantasma).
  • La temperatura de la luz coincide con el brief.

Compuerta de colisiones

  • __COLLIDERS devuelve las cajas delimitadoras de todos los objetos con colisión.
  • __BOUNDS devuelve el volumen de juego.
  • Ejecute __TESTMOVE para mover el jugador a través del espacio; detecte penetraciones y salidas de límites.
  • La paridad de colisionadores = 100% cuando cada malla renderizada tiene una caja de colisión y viceversa.

Compuerta de prueba de juego

  • Ejecute __TEST secuencias: start, pause, resume, settings, save, state.
  • El bucle es completable: el jugador puede alcanzar el estado "ganó" desde el inicio.
  • La ruta de fallo es alcanzable: el jugador puede morir o fallar.
  • El reinicio restaura el estado inicial.

Compuerta móvil

  • Diseño 390×844 sin desbordamiento horizontal.
  • Los controles táctiles están presentes y son funcionales.
  • El tamaño de fuente mínima es 16 px.

Compuerta de aspecto visual

  • Compare la captura actual con la referencia utilizando el perfil fotorrealista y la puntuación de histograma.
  • Cada métrica debe estar dentro del umbral declarado.

Compuerta de informe de caja

  • Para 3 a 6 objetos del sujeto, mida: recuento de triángulos, área de textura, profundidad de sombreado, relación de aspecto.
  • Compare con los mismos objetos en el fotograma de referencia en la misma cámara.
  • Cada métrica debe ser >= 0.8 de la referencia.

Consejos para la ejecución

  • Comience desde el esqueleto. No escriba el motor de renderizado; copie el que ya funciona.
  • Use consultas de parámetros (?shot=1, ?cam=...) para capturas deterministas.
  • Las tablas son su memoria externa. Manténgalas actualizadas.
  • Cuando una compuerta falla, lea el mensaje: dice qué tabla actualizar o qué corrección aplicar.
  • Una ronda es un cambio de archivo, luego ejecutar todas las compuertas. No se salte pasos.
  • Si el modelo se atasca en la estética, recuerde la regla 3: producto primero, luego aspecto visual.

Esta habilidad se deriva del trabajo de producción de Saltline y se empaqueta para que modelos de bajo costo puedan alcanzar la misma disciplina. Consulte rules/ para especificaciones detalladas de compuertas y el directorio harness/ para el arnés de verificación ejecutable.

Skills relacionados