diorama-pixel

Diorama Pixel：動きのあるピクセルアートのミニチュア

固定されたアイソメトリックカメラから見た、小さな場所をひとつ作ります。屋台、桟橋、菜園、出入り口などを、ピクセルアートで描きます。フレーム全体は 320 x 240 でレンダリングし、最近傍法でピクセルを拡大します。すべての表面は、8 x 8 のベイヤーマトリクスを通して、彩度を抑えた短いカラーパレットに量子化します。素材にはプロシージャルテクスチャ（板の線、茅の筋、石、点描の草、まだらな水）を施します。地面の縁は白いページに溶け込み、太陽は柔らかな影を落とします。そして、小さな人がひとりかふたり、ループの中でひとつの動作をはっきりと行います。examples/ にある3つのシーンが基準であり、作成するものも同じ形式です。

このスキルは3つあるうちのひとつです。diorama はベクター SVG のイラスト（UI シーン、線画、空の状態、テーマ）を描画します。diorama-worlds は、関節のある人物と4種類の仕上げを備えた、詳細な Three.js の世界をレンダリングします。ピクセル、ディザリング、レトロまたは16ビットの雰囲気、あるいは小さく依存関係のないピクセルシーンを求めている場合は、このスキルを使います。

作成するのはひとつだけです。シーンを記述した .js ファイルです。カーネル（kit/pixel.js）とページ（kit/page.html）は固定です。編集したり、変更したコピーを貼り付けたりしてはいけません。また、カーネルが用意するもの（カメラ、光、影、テクスチャ、ディザリング、地面、人物のリグ、木や茂み、画面外では停止する時計、ポインター）を再び記述してはいけません。

以下に記載されているファイルはすべて、このスキルのフォルダー内にあります。作業者の作業ディレクトリにシーンとビルド済みページを作成し、このフォルダー内のパスを指定して、そこからスクリプトを実行します。

1. コンセプト

コードを書く前に、コンセプトを1行で記述します。

名前。 場所と、そこにあるもの。人物が行うひとつの動作と、ほかに動くもの。ポインターとタップで起きること。

物語と用途のある場所を選びます。市場の屋台、桟橋、パン屋の出入り口、貸し農園、バス停、屋上庭園などです。ひとつの動作をシーンの軸にします（花束を結ぶ、釣りをする、水やりをする、生地をこねるなど）。動作には予備動作とひと休みを含め、その周囲に、布、水、葉、旗などの穏やかなループを2、3個加えます。次に、4行でパーツの一覧を記述します。地面（ゾーン：草、舗装、水、砂、土、小道）、構造物（立っているもの：屋台、小屋、柵）、人物（誰が、どこにいて、どちらを向き、何をしているか）、動き（揺れる、上下する、きらめくもの）。シーンには10〜25個のオブジェクトを使います。一覧が少ないと、シーンも物足りなくなります。

相談できる相手がいる場合は、コンセプトを2、3案提示して返答を待ちます。相談相手がいない場合は、静止画として最も魅力的な案を選び、どれを選んだか伝えます。

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文字以内の1文）、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、静止画、ループの4つの瞬間、ホバー、押下、モバイル表示を書き出し、塗りつぶし、動き、ループの継ぎ目、ピッキング、ホバー、押下、動きの低減、フレームコスト、モバイルでのはみ出しを確認します。フレームコストはシーンのフレーム予算（24 fps で 41.7 ms）を基準に判定されます。--throttle 4 を指定すると、CI ランナーやスマートフォンのように CPU が4倍遅い環境で確認できます。CHROME_PATH でブラウザーを指定できます。指定しない場合は、インストール済みの Chrome または Chromium が使用されます。
3. PNG を開いて確認してください。 チェックに合格しても、絵ができたとは限りません。静止画について、次の点を確認してください。このサイズで動作が伝わるか（手、道具、作業対象）？ 柱や屋根に隠れている人はいないか？ すべての表面に素材感があるか？ 地面はすべての辺でページになじみ、フレームで切れているものはないか？ 太陽の位置と影の位置が合っているか？ そのうえでカーネルではなくシーンを修正し、もう一度確認してください。

バリデーターで拒否されるページを渡さないでください。画像を開いていない場合は、見た目の確認が完了したと主張しないでください。ブラウザーがない場合は、そのことを明確に伝え、見た目が未確認であることを添えて渡してください。

4. 引き渡し

依頼された方法で pixel-<name>.html を渡してください（ファイル、または公開できる場合はアーティファクト）。続けて、それぞれ1行で、コンセプト、静止画の秒数とその理由、サイズ（約 50 KB、依存関係なし）、埋め込み方法（references/scene-api.md の「Embedding」：<canvas>、カーネル、シーンを2つの <script> タグに入れて Pixel.mount を使う方法、またはそこに記載された React コンポーネント）、確認できなかった項目を伝えてください。

5. 調整

変更を依頼されたら、<name>.js だけを編集し、ビルド、検証、再確認を行ってください。

うまくいかない場合

こうしそうになったら	代わりにこうする
three.js、WebGL、画像ファイルを使おうとする	それらはありません。カーネルは2Dキャンバス上で立体をラスタライズします。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：パレットとランプ、マテリアルとテクスチャ、ディザリング、地面の端、光と影、ピクセルスケールでの人物、構図。