diorama-pixel

Diorama Pixel：会动的像素艺术微缩场景

你要创作一个小地方——摊位、码头、菜地或门口——用固定的等距视角观察，并以像素艺术绘制：整个画面以 320 x 240 渲染，再用最近邻像素放大；通过 8 x 8 Bayer 矩阵，将每个表面量化为一组短小的柔和色阶；材质带有程序化纹理（木板线条、茅草纹理、石块、点描草地、斑驳水面）；地面的边缘渐隐于白色页面；阳光投下柔和阴影；一两个人物做着一件明确的事，并循环动作。examples/ 中的三个场景是质量基准，文件格式就是你要编写的格式。

这是三个技能之一。diorama 绘制矢量 SVG 插画（UI 场景、线稿、空状态、主题）；diorama-worlds 使用 Three.js 渲染细节丰富的世界，包含有关节的人物和四种表面效果。若用户想要像素画、抖色、复古或 16 位风格，或必须小巧且无依赖的像素场景，就使用这个技能。

你只需编写一项内容：场景，一个 .js 文件。内核（kit/pixel.js）和页面（kit/page.html）是固定的。切勿编辑它们，切勿粘贴修改后的副本，也切勿重新编写内核已提供的内容（摄像机、光照、阴影、纹理、抖色、地面、人物骨架、树木和灌木、在画面外休眠的时钟、指针）。

下文提到的所有文件都位于此技能的文件夹中。在用户的工作目录中编写场景和生成的页面，并通过这些文件在此文件夹中的路径运行脚本。

1. 概念

编写任何代码前，先用一行写下概念：

名称。 场景地点及其中的物品。人物做的一件事，以及其他会动的事物。指针悬停和轻点时会触发什么。

选择一个有故事、有用途的地点：集市摊位、栈桥、面包店门口、社区菜园、公交站、屋顶花园。一件主要动作推动场景（扎花束、钓鱼、浇水、揉面），动作中要有期待和停顿，再围绕它安排两三个安静循环的动效（布料、水、树叶、旗帜）。然后用四行列出组成部分：地面（区域：草地、铺石、水面、沙地、泥土、小径）、结构（立着的物件：摊位、小屋、围栏）、人物（是谁、在哪里、面朝哪里、在做什么）、生机（什么在摇摆、起伏或闪烁）。场景由 10–25 个物件组成。如果清单内容单薄，场景看起来也会单薄。

如果有人可以询问，就提供两三个概念并等待答复。如果没人可问，就选取静帧效果最好的那个，并说明你选了哪一个。

2. 构建

1. 阅读 references/art-direction.md：调色板、材质、抖色、地面边缘、人物的比例，以及怎样让画面看起来像像素微缩场景，而非模糊的渲染图。
2. 阅读 references/scene-api.md：所有图元、材质、辅助函数和 tick 接口约定。不要阅读 kit/pixel.js 中索引注释之后的内容。
3. 阅读最接近的示例：examples/flower-stall.js（铺石路面和草地、条纹遮阳篷、两个人物、一面三角旗）、examples/pier.js（水面和岸边、一位手持钓竿的坐姿人物、一条船、一座茅草小屋）或 examples/allotment.js（泥土、砖砌小径、高架种植床、一位浇水的园丁、一座稻草人）。
4. 编写 <name>.js：使用一个 Pixel.scene({ … })，包含 name、title、means（一句话，最多 140 个字符）、hint（悬停和轻点时触发什么）、duration、still、ground、可选的 materials、返回 parts 的 build(P)（其中包含 parts.hot，每个热区组都要命名），以及根据 ctx.t / ctx.q 为所有元素设置姿态的 tick(ctx)。
5. 构建：node <skill>/scripts/build.mjs <name>.js 会生成 pixel-<name>.html，这是一个完全自包含的页面，不会发起网络请求。

3. 检查

1. node <skill>/scripts/validate.mjs <name>.js pixel-<name>.html：检查声明、时钟、自包含性、无 URL、内核逐字节一致、大小预算和指针。修复所有 FAIL。
2. 先运行一次 npm ci --ignore-scripts --prefix <skill>，然后运行 node <skill>/scripts/look.mjs <name>.js <outdir>。它会在禁用网络的无头 Chromium 中打开页面，并写入 <name>-look.json、静帧、循环中的四个时刻、悬停、按下和移动视图，同时检查填充、运动、循环接缝、拾取、悬停、按下、减少动态效果、帧耗时和移动端溢出。帧耗时根据场景的帧预算评估（24 fps 时为 41.7 ms）；--throttle 4 会在速度慢四倍的 CPU 上检查，模拟 CI 运行器或手机。CHROME_PATH 用于指定浏览器；否则会使用已安装的 Chrome 或 Chromium。
3. **打开 PNG 并检查。**检查通过不代表画面就合格。看看静帧：这个尺寸下能看清动作吗（手、工具、正在处理的东西）？有没有人被柱子或屋顶挡住？每个表面是否都呈现出相应材质？地面是否在各个方向都渐隐至页面中，没有任何部分被画框裁切？地面上的阴影位置是否符合阳光方向？然后修改场景，不要修改内核，再次检查。

不要交付验证器判定不合格的页面。如果没有打开图片，就不要声称检查已完成。没有浏览器时，请明确说明，并在未经检查的情况下交付。

4. 交付

按对方要求提供 pixel-<name>.html（文件，或可发布时提供的制品）。然后每项各用一行说明：概念；静帧的秒数及原因；大小（约 50 KB，无依赖）；嵌入方式（参见 references/scene-api.md 中的 "Embedding"：一个 <canvas>、内核和场景分别放在两个 <script> 标签中并使用 Pixel.mount，或使用其中的 React 组件）；任何无法验证的内容。

5. 调整

对方要求修改时，只编辑 <name>.js，然后构建、验证并再次检查。

常见问题

如果你发现自己在……	应改为……
想用 three.js、WebGL 或图片文件	这些都不存在：内核会在 2D canvas 上栅格化实体；请使用 P.box、P.cyl、P.ball、P.wedge、P.line
编写 requestAnimationFrame、setTimeout 或 Math.random	在 tick 中根据 ctx.t / ctx.q 设置所有姿势；使用 P.hash(i, j) 实现固定不变的多样性
编写 position.x += speed * dt	使用 P.phase(t, period) 来确定位置，这样静帧和循环接缝才能精确
有人被柜台、柱子或屋顶挡住	移动人物、降低柜台、抬高屋顶：相机是固定的，而人物是画面的主角
手臂与身体连成一团	采用前臂伸出的姿势（P.pose(p, 'work' / 'hold')），并让双手拿着有独立颜色的东西
把树画成一个大圆球	使用 P.tree 和 P.bush：由圆润着色的叶簇构成
大面积表面只用一种纯色	使用有纹理的材质：'wood'、'thatch'、'stone'、'paving'、'leaf'、'cloth'，或使用带 tex 的渐变
地面边缘过于生硬	地面使用 ground: { rx, rz, wobble, fade }：它已经会渐隐；不要添加板块或底座
场景比地面还宽	将所有内容保持在 rx 和 rz 范围内；画框会适配地面
内部宽度超过 480 px	采用 320 x 240 的画面规格；更高分辨率看起来像渲染图，而不是像素画
为了让场景正常工作而编辑 kit/pixel.js	问题出在场景；修改场景

参考资料

• references/scene-api.md：声明、P（基本图元、材质、人物、姿势、树木、噪声）、tick 上下文和指针、运行时及嵌入方式。
• references/art-direction.md：调色板和渐变、材质与纹理、抖动、地面边缘、光照与阴影、像素尺寸的人物、构图。