diorama-pixel

Diorama Pixel: una miniatura en píxel art que se mueve

Estás haciendo un lugar pequeño, un puesto, un embarcadero, un huerto o una entrada, visto desde una cámara isométrica fija y dibujado como píxel art: todo el fotograma se renderiza a 320×240 y se amplía con píxeles vecinos, cada superficie se cuantiza a una rampa corta de colores apagados mediante una matriz Bayer de 8×8, los materiales llevan textura procesal (líneas de tablones, vetas de paja, piedras, hierba punteada, agua manchada), el borde del suelo se disuelve en la página blanca, el sol proyecta sombras suaves, y una o dos personitas hacen una cosa clara en bucle. Las tres escenas en examples/ son el listón, y están en el formato que escribirás.

Este skill es uno de tres. diorama dibuja ilustraciones vectoriales SVG (escenas de interfaz, arte lineal, estados vacíos, temas); diorama-worlds renderiza mundos detallados en Three.js con personajes articulados y cuatro acabados. Usa este cuando la persona quiera píxeles, tramado, un aspecto retro o de 16 bits, o una escena de píxeles que deba ser pequeña y sin dependencias.

Escribes una sola cosa: la escena, un archivo .js. El kernel (kit/pixel.js) y la página (kit/page.html) son fijos. Nunca los edites, nunca pegues una copia modificada, y nunca escribas de nuevo lo que el kernel te da (la cámara, la luz, las sombras, las texturas, el tramado, el suelo, un esqueleto de persona, árboles y arbustos, un reloj que duerme fuera de la pantalla, el puntero).

Cada archivo nombrado a continuación está en la carpeta de este skill. Escribe la escena y la página construida en el directorio de trabajo de la persona, y ejecuta los scripts desde allí usando su ruta en esta carpeta.

1. Concepto

Escribe el concepto en una línea antes de cualquier código:

Nombre. El lugar y lo que hay en él. La única acción que hace una persona, y qué más se mueve. Lo que hace el puntero y un toque.

Elige un lugar con historia y utilidad: un puesto de mercado, un embarcadero, la puerta de una panadería, un huerto, una parada de autobús, un jardín en la azotea. Una acción sostiene la escena (atar un ramo, pescar, regar, amasar), con anticipación y una pausa, y dos o tres bucles silenciosos a su alrededor (tela, agua, hojas, una bandera). Luego escribe la lista de partes en cuatro líneas: suelo (zonas: hierba, adoquines, agua, arena, tierra, un camino), estructura (lo que se alza: un puesto, un cobertizo, una valla), personas (quién, dónde, hacia dónde miran, qué hacen), vida (lo que se mece, flota o brilla). Una escena tiene de 10 a 25 objetos. Si la lista parece escasa, la escena también lo será.

Ofrece dos o tres conceptos cuando haya alguien a quien preguntar, y espera. Si no hay nadie a quien preguntar, toma el que tenga el fotograma fijo más fuerte y di cuál.

2. Construcción

1. Lee references/art-direction.md: paleta, materiales, tramado, el borde del suelo, la escala de las personas, qué hace que un fotograma se lea como una miniatura de píxeles en lugar de un render borroso.
2. Lee references/scene-api.md: cada primitiva, material, ayuda y el contrato de tick. No leas kit/pixel.js por debajo de su comentario de índice.
3. Lee el ejemplo más cercano: examples/flower-stall.js (adoquines y hierba, un toldo a rayas, dos personas, un banderín), examples/pier.js (agua y una orilla, una persona sentada con una caña, un bote, un cobertizo de paja) o examples/allotment.js (tierra, un camino de ladrillos, bancales elevados, un jardinero regando, un espantapájaros).
4. Escribe <nombre>.js: un Pixel.scene({…}) con name, title, means (una frase, como máximo 140 caracteres), hint (qué pasar por encima, qué tocar), duration, still, ground, materials opcional, build(P) que devuelve parts (con parts.hot, cada grupo caliente nombrado) y tick(ctx) que posa todo desde ctx.t / ctx.q.
5. Construye: node <skill>/scripts/build.mjs <nombre>.js escribe pixel-<nombre>.html, una página autónoma sin ninguna solicitud de red.

3. Revisión

1. node <skill>/scripts/validate.mjs <nombre>.js pixel-<nombre>.html: la declaración, el reloj, la autonomía, sin URLs, el kernel byte a byte, el presupuesto de tamaño y el puntero. Corrige cada FAIL.
2. npm ci --ignore-scripts --prefix <skill> una vez, luego node <skill>/scripts/look.mjs <nombre>.js <dirSalida>. Abre la página en Chromium sin cabeza con la red bloqueada y escribe <nombre>-look.json, el fotograma fijo, cuatro momentos del bucle, el paso por encima, la pulsación y una vista móvil, y comprueba el relleno, el movimiento, la costura del bucle, la selección, el paso por encima, la pulsación, el movimiento reducido, el coste del fotograma y el desbordamiento móvil. El coste del fotograma se juzga con respecto al presupuesto de fotogramas de la escena (41.7 ms a 24 fps); --throttle 4 lo mira en una CPU cuatro veces más lenta, como un ejecutor de CI o un teléfono. CHROME_PATH selecciona un navegador; de lo contrario, usa un Chrome o Chromium instalado.
3. Abre los PNG y mira. Las comprobaciones superadas no hacen una imagen. Pregunta del fotograma fijo: ¿se lee la acción a este tamaño (manos, la herramienta, lo que se está trabajando)? ¿Hay alguien escondido detrás de un poste o un techo? ¿Cada superficie muestra su material? ¿El suelo se desvanece en la página por todos los lados, sin nada cortado por el marco? ¿Están las sombras en el suelo donde dice el sol? Luego arregla la escena, no el kernel, y mira de nuevo.

No entregues una página que el validador rechace. No digas que el aspecto está terminado si no abriste las imágenes. Sin un navegador, dilo claramente y entrega con el aspecto no verificado.

4. Entrega

Entrega pixel-<nombre>.html como la persona pidió (el archivo, o un artefacto si puedes publicar uno). Luego, una línea cada uno: el concepto; el segundo del fotograma fijo y por qué; el tamaño (aproximadamente 50 KB, sin dependencias); cómo incrustarlo (references/scene-api.md, "Incrustación": un <canvas>, el kernel y la escena en dos etiquetas <script> y Pixel.mount, o el componente React que allí se indica); cualquier cosa que no pudieras verificar.

5. Ajustes

Cuando la persona pida un cambio, edita solo <nombre>.js, construye, valida y mira de nuevo.

Lo que sale mal

Si te encuentras	Haz esto en su lugar
buscando three.js, WebGL o un archivo de imagen	no los hay: el kernel rasteriza sólidos en un canvas 2D; usa P.box, P.cyl, P.ball, P.wedge, P.line
escribiendo requestAnimationFrame, setTimeout o Math.random	posa todo desde ctx.t / ctx.q en tick; usa P.hash(i, j) para variedad que se mantenga fija
position.x += speed * dt	una posición desde P.phase(t, period), para que el fotograma fijo y la costura del bucle sean exactos
una persona escondida detrás de un mostrador, un poste o un techo	muévela, baja el mostrador, sube el techo: la cámara es fija y ellos son la historia
brazos que se leen como una masa con el cuerpo	una pose con los antebrazos extendidos (P.pose(p, 'work' / 'hold')), las manos sosteniendo algo con un color propio
un árbol como una bola grande	P.tree y P.bush: racimos de grupos de hojas sombreadas redondeadas
un color plano en una superficie grande	un material texturizado: 'wood', 'thatch', 'stone', 'paving', 'leaf', 'cloth', o una rampa con tex
un borde duro donde termina el suelo	el suelo es ground: { rx, rz, wobble, fade }: ya se disuelve; nunca añadas una losa o un pedestal
una escena más ancha que su suelo	mantén todo dentro de rx y rz; el marco se ajusta al suelo
más de 480 px de ancho interno	320×240 es el aspecto; más píxeles parecen un render, no píxel art
editando kit/pixel.js para que una escena funcione	la escena está mal; cambia la escena

Referencias

• references/scene-api.md: la declaración, P (primitivas, materiales, personas, poses, árboles, ruido), el contexto de tick y el puntero, el runtime y la incrustación.
• references/art-direction.md: paleta y rampas, materiales y texturas, tramado, el borde del suelo, luz y sombra, personas a escala de píxeles, composición.