作ったものを紹介するだけなら、完成画面を一枚見せれば終わります。けれど、同じようなものを作りたい人に役立つ記事にするには、「なぜ始めたか」「どこで迷ったか」「何を分けて実装したか」「どう確認したか」まで残す必要があります。
今回は、個別に散らばっていたWebGL表現を、ブラウザで比べられ、次の作品にも使える小さな実験棚にまとめるまでの作業から、三つを取り上げます。完成品の自慢ではなく、もう一度作るための設計図として書きます。
最初に決めたこと
目的は、個別に散らばるWebGL表現を、ブラウザで比較し、次の作品へ使える小さな実験棚にすることでした。
最初から全部を作るのではなく、利用者が最初に触る入口から始めます。画面、データ、演出、公開作業を同時に変えると、何が良くなり、何が壊れたか分からなくなるからです。そこで、この作業では一つの変更を小さくし、そのたびに実際の操作と数値の両方を確認しました。
また、ローカルで動いた状態と、公開URLで動いた状態は別物として記録します。ファイルが存在する、HTTP 200が返る、画面で最後まで操作できる。この三つは同じ証拠ではありません。
1. サンプルを一つの入口へ集めた
固定したrouteとtemplateから複数の描画資産を読み込み、URLを知らなくても選べる入口にしました。
ここで重視したのは、機能があることではなく、利用者が変化を画面上で確かめられることです。実装では、入力、内部状態、表示、保存や次の行動を分けて考えました。不具合が起きても、「操作が届いていない」「計算が違う」「表示だけ古い」と切り分けやすくなります。
2. 共通接続を追加した
Three UI、描く、書くへ次の行動を渡せるように、registryのflowを設定しました。
共通接続では、どこからどこへ情報を渡すのかを一つずつ確認しました。次の画面へ進めるだけでなく、戻ったときに前の状態が壊れていないかも見ています。
3. 失敗時の境界を意識した
WebGL対応、canvas、親ページ、iframeで起きるエラーを分け、外側の問題を描画本体の失敗と混同しないようにしました。
ブラウザ、canvas、親ページ、iframeのエラーを分けると、問題の場所を絞り込めます。外側の問題を、描画本体の失敗と混同しないことが大切でした。
実際に触ると、どこが面白いのか
このツールの面白さは、説明を読んで理解するだけでなく、自分で触った結果がすぐ画面へ返ってくることです。個別に散らばっていたWebGL表現を、ブラウザで比べ、次の作品に使える小さな実験棚にするという目的が、三つの変更を通して一つの体験になっています。
作り方を読み進める前に、公開中の版を一度触ってみてください。入力する前と結果が出たあとで、画面のどこが変わるかを見ると、後半の実装説明を具体的に想像できます。
うまくいかなかったところ
開発中に難しかったのは、画面だけを見て原因を決めないことでした。見た目がおかしくても、原因はデータ、入力、描画、キャッシュ、外部取得のどこかにあります。逆に、テストが通っていても、スマートフォンで押しにくい、画面外へはみ出す、結果が見えないなら完成ではありません。
今回確認できたのは、registryがactiveであること、4つの資産が登録されていること、旧パス（legacy paths）が残っていることです。接続UIと4ページが公開先から読み込めることも確認しました。
一方で、まだ確認できていないこともあります。
注意点：サンプルごとに確認する
各サンプルのFPSやGPU負荷、reduced-motionへの対応、古い端末でのフォールバックは、サンプルごとに個別確認が必要です。ひとつのサンプルで問題がなくても、ほかのサンプルまで同じ条件で動くとは限りません。
未確認を隠さないのは、次に同じものを作る人が、完成済みの部分と自分で確かめる部分を区別できるようにするためです。
同じものを作るための順番
- サンプルを一つの入口に集め、最小限の動く状態を作る
- 共通接続を追加し、次の行動までつなげる
- 失敗時の境界を分け、原因を切り分ける
- 入力から結果までを一度通して操作する
- PCと375px、必要なら320pxで画面外へのはみ出しを確認する
- JavaScript、PHP、データ契約のテストを実行する
- ローカル完了と公開完了を分けて記録する
最初の版では、設定画面や管理機能を増やしません。利用者が一回の操作で中心体験へ到達できることを優先します。中心体験が弱いまま周辺機能を足すと、説明文と保守対象だけが増えます。
実装ファイルも責務ごとに分けます。画面の骨組み、見た目、状態計算、入力、保存、外部取得を一つの大きなファイルへ集めない方が、変更範囲とテスト対象を固定できます。ただし、最初から抽象化しすぎず、二度目の同じ変更が現れたところで共通化します。
作る前に紙へ書いておく契約
同じようなものを作るなら、コードを書く前に五つだけ書きます。一つ目は、利用者が最初に行う操作です。二つ目は、その操作で内部状態がどう変わるかです。三つ目は、変化を画面のどこで確認できるかです。四つ目は、失敗した時にどこへ戻るかです。五つ目は、完了を証明する操作です。
たとえば「ボタンを押せる」は完了条件になりません。「ボタンを押すと対象が変化し、結果が表示され、再読み込み後も必要な状態だけが残る」までを一つの契約にします。外部データを使う場合は、取得成功だけでなく、拒否、空データ、遅延、不正な入力を契約へ加えます。ゲームなら、開始、通常操作、失敗、終了、再挑戦を同じ流れで確認します。
この契約を先に書くと、見た目の調整中にゲームルールを変えたり、データ修正中に共通メニューを巻き込んだりする範囲拡大を防げます。また、記事を書く時も、読者は何を入力し、プログラムは何を処理し、どの結果を見て次を判断するのかを順番に説明できます。
最小版から育てる方法
最初の一周は、仮のデータ一件でも構いません。入力から結果までが通る最小版を作ります。二周目でデータを増やし、三周目で失敗経路を入れ、四周目でPCとスマートフォンを比べます。見た目の演出は、中心操作が成立したあとに一つずつ加えます。
追加するたびに、前の中心操作をもう一度実行します。新しい演出が増えても、開始が遅くなったり、ボタンが画面外へ逃げたり、保存済みデータが読めなくなったら前進ではありません。変更前後を同じ操作で比較し、改善した点を一文で言えない変更は一度止めます。
データが3件以上あるときは、件数、重複、必須項目、画像の存在、URL、並び順をプログラムで検査します。一方、記事の意味、ゲームの面白さ、画像の主役は自動判定だけで決めません。機械が守る契約と、人間が選ぶ体験を分けることが大切です。
作業中の画面写真も、完成記念ではなく証拠として残します。開始前、中心操作の途中、結果の三場面があれば、読者は文章と画面を対応させられます。数値だけを掲載せず、その数値を出した入力と操作も一緒に書きます。
検証で見る場所
検証では、ボタンがあることではなく、ボタンの意味が正しいことを見ます。右を押したら本当に右へ進むか、保存後に同じ状態へ戻るか、結果をコピーできるか、最後まで進んだ時に止まるかを確認します。
スマートフォンでは、375pxと320pxの横幅、44px以上の操作領域、スクロール中の固定要素、画面回転、タップ後の状態を見ます。3DやCanvasをiframeで表示する場合は、外側のページと内側のアプリを分けて確認します。
公開時は対象ファイルだけを転送し、本番のSHA-256を照合します。その後、対象URLだけのキャッシュを更新し、公開HTMLが新しい資産を読んでいるか、PCとスマートフォンで主要操作が完走するかを確かめます。全サイトのキャッシュ削除や無関係なファイル更新は、対象を広げるので行いません。
この作業から得たこと
サンプル集は、数を並べるだけでなく、対応環境や実行の境界、次に使える場所まで示すと教材になります。
道具を作るとき、完成画面だけを保存しても、次の人は同じ場所へたどり着けません。目的、最小の入口、三つの変更、失敗、検証、未確認を一緒に残すと、作業履歴が再利用できる設計書になります。
公開時点で確認できたツールURL、画面、資産、未確認事項を分けて記録しました。本文の図版は、理解が変わる場面だけに絞っています。アイキャッチは記事全体を一枚で伝える主役として選びました。画像を増やすこと自体が目的ではありません。
作り方を読んだあとにもう一度触ると、入力、状態変化、表示、検証のつながりが見えます。
